> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 0.24.1

> Aspects budgets are now enforced at dispatch, plus a PiAgent JSON-mode reliability fix and regenerated TypeScript declarations.

Smithers 0.24.1 makes Aspects budgets enforce at runtime, fixes a PiAgent reliability bug where JSON-mode runs could time out instead of completing, gives the workflow CLI a consistent sandbox root, and regenerates the stale `packages/smithers/src/index.d.ts`. There are no breaking changes and no public API symbols were removed.

***

## Aspects budgets are enforced

`Aspects` budget props (`tokenBudget`, `costBudget`, `latencySlo`) were type only: nothing consumed them at runtime, so wrapping an expensive agent fan-out in a budget gave no protection. The engine now enforces scope budgets at task dispatch.

* The engine keeps a per-run usage accumulator seeded from persisted `TokenUsageReported` events and fed live from the event bus, so accumulated usage survives resume. Cost is estimated from token counts via a built-in model price table.
* Scope totals are checked when a task is dispatched, on both the driver and the legacy scheduler. `onExceeded` controls the outcome: `fail` raises `ASPECT_BUDGET_EXCEEDED` and fails the run, `warn` logs and continues, and `skip-remaining` skips the task and the rest of the scope.
* Per-task limits (`perTask`) are not enforced yet.

## Agents

`PiAgent` could hang and fail with `PROCESS_TIMEOUT` whenever Smithers captured events. In JSON mode the process was launched without pi's `--print` flag, so pi stayed open as an interactive session after emitting a complete answer; Smithers then killed it at the task timeout and discarded the finished output.

* `PiAgent` now passes `--print` for every non-RPC mode, so `json` and `stream-json` runs process the prompt and exit instead of blocking until the timeout.
* `agent_end` is treated as a terminal event: the final assistant answer is harvested and a `completed` event is emitted during streaming, with `onExit` deduping so a run completes exactly once.
* pi token usage (per-message, `turn_end`, and `agent_end`) is attached to the completed event, so usage telemetry is reported instead of always reading zero.
* pi diagnostics are now provider-aware. Google, OpenAI, or Anthropic auth and rate-limit checks are selected from the effective `--provider`, a `provider/model` prefix, or a bare model id, and an explicit `apiKey` maps to the right provider environment variable.

## CLI

Workflow commands resolved the tool sandbox root inconsistently, so a run launched from a subdirectory could read and write files from a different root than the one its run database used.

* `up`, `workflow run`, `graph`, `eval`, and `resume` now resolve the launch root the same way, anchored to the nearest `.smithers/` directory (the same anchor used to locate the run database).
* `graph` gains a `--root` flag to set the sandbox root explicitly.
* `resume` preserves the root persisted with the original run.

## Type declarations

The published `@smithers-orchestrator/smithers` package now ships a declaration file that matches the actual dts build output.

* Regenerated `packages/smithers/src/index.d.ts` so type consumers get accurate declarations without a local rebuild.
* Corrected the export ordering on the `@smithers-orchestrator/engine` re-export line that shipped out of date in 0.24.0.
* All exported symbols are identical to 0.24.0; only the generated file was refreshed.

## Upgrade

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator@0.24.1
```

No configuration changes are required. Workflows that already set `Aspects` budgets will now have them enforced at dispatch.