Skip to main content
0.24.0 is the first release since 0.23.0, so it also carries every fix from the unpublished 0.23.1. The headline change is the Gateway SDK’s move to TanStack DB collections. Alongside it are new CLI surfaces, engine correctness work, and a wide set of Gateway and package fixes from dogfooding.

​
Breaking changes

​
Gateway sync SDK rebuilt on TanStack DB

@smithers-orchestrator/gateway-client and @smithers-orchestrator/gateway-react now build their declarative sync SDK on TanStack DB collections, replacing the previous SyncClient, SyncCache, and SyncSubscriptionHub classes.
  • gateway-client exports createGatewayCollection, gatewayCollectionDefs, and the run-node helpers (flattenGatewayRunNode, snapshotToGatewayRunNode, reconcileSnapshotNodes), all backed by the gateway RPC and WebSocket transport. The framework-free core stays in gateway-client.
  • gateway-react adds the SyncProvider context, the GatewayCollections registry, and the hooks useSyncQuery, useSyncMutation, and useSyncSubscription, plus the typed shortcuts useGatewayQuery, useGatewayMutation, useGatewayRunStream, useGatewayRunTree, and useGatewayConnectionStatus, backed by @tanstack/react-db.
  • The removed exports have no drop-in replacement. Rebuild custom-UI data access on the collection hooks. apps/smithers now reads connection status from the registry observer rather than a workflows probe.
This is the Phase 1 foundation for the Postgres-of-record and TanStack DB sync work. @tanstack/react-db is a new dependency of gateway-react.

​
New features

​
bunx smithers-orchestrator gateway command

A new bunx smithers-orchestrator gateway command starts the multi-run Gateway RPC and WebSocket control plane headlessly, backed by the workspace database. It exposes listRuns, streamRunEvents, and streamDevTools, and prints the workspace and DB paths it serves on startup. This is distinct from bunx smithers-orchestrator up --serve, which runs a single workflow and adds a lightweight serve layer. Use gateway when you need the full /v1/rpc/* control plane without launching a workflow run. Fixes #255. PR #268.

​
Workflow input schemas in inspect and generated skills

bunx smithers-orchestrator inspect now returns the machine-readable JSON schema for each workflow’s input alongside the run summary. The schema is also surfaced in generated skill docs: real field names, types, defaults, enums, and descriptions appear in the skill file rather than a generic placeholder. Fixes #258. PR #272.

​
bunx smithers-orchestrator monitor command

A new bunx smithers-orchestrator monitor [RUN_ID] command watches a running workflow, diagnoses failures with tool access, optionally applies a gated self-fix (--autofix), and writes an HTML report. It drives the seeded monitor workflow and supports --detach and --input. The CLI also auto-mounts workspace custom UIs.

​
smithers-orchestrator jsx-runtime and run-control exports

The smithers-orchestrator package now ships ./jsx-runtime and ./jsx-dev-runtime subpath exports with types, so /** @jsxImportSource smithers-orchestrator */ resolves directly from the published package. The public barrel also exposes the run-control and output API: runWorkflow, getRun, listRuns, approveNode, denyNode, and renderFrame.

​
Driver and graph surfaces

  • The driver exposes resolved worktree paths to workflow code, and jj worktrees resolve as real git worktrees for child tools.
  • A typed run-annotations option is exposed on the driver.
  • Sandbox egress props thread through the graph.

​
Bug fixes

​
Engine: dependency and Loop correctness

  • deps resolve across loop boundaries, and unsatisfiable deps fail loudly. A deps key pointing at an upstream id that needed remapping used to silently no-op. It now resolves across loop boundaries and raises DEPENDENCY_DEADLOCK when a dependency can never be satisfied.
  • Parallel <Loop> iterations no longer starve until total run quiescence. All three scheduling paths shared the bug: the legacy engine ladder returned await-trigger or schedule-retry before reaching ready-loop handling, the workflow session gated loop progress behind a global-idle check, and the WorkflowDriver’s Promise.all batch barrier held all completions until the batch finished. Ready loops now advance whenever a loop node completes, the driver processes completions incrementally, continue-as-new handoffs stay quiescence-only, and unhandled task failures keep precedence over further iterations. Fixes #267. PR #271.

​
Detached runs and approvals

  • Gateway streams persisted events from detached runs. streamRunEvents returned heartbeats only for runs started with bunx smithers-orchestrator up -d, because the Gateway host had no visibility into events the detached process wrote. A built-in out-of-process event bridge now tails _smithers_events for runs the Gateway host did not execute. It is on by default and configurable via the outOfProcessEventBridge (boolean) and outOfProcessEventBridgePollMs (number) Gateway options. Fixes #254. PR #266.
  • Supervisor auto-resumes detached runs after an approval is recorded. Approving a gate on a detached run recorded the decision but left the run stuck in waiting-event. The supervisor now queries _smithers_approvals joined to pending nodes on every poll and spawns a detached resume for any decided-but-unconsumed approval. bunx smithers-orchestrator approve prepends a resume command to its CTA when the run is still waiting-event, and bunx smithers-orchestrator why emits an approval-decided-resume-required blocker. Fixes #242. PR #250.
  • approveNode no longer strands runs on post-commit bridge failure. Approving through the MCP resolve_approval tool could return an error while consuming the approval row, leaving the run permanently stuck. approveNode commits the decision first, then treats a post-commit bridge failure as non-fatal: it warns and returns success, because the committed approval is the durable source of truth and the engine processes it on resume. Fixes #241. PR #246.

​
CLI agents

  • CLI-agent answers survive captured-stdout truncation. Long runs overflow the 200 KB captured-stdout cap; the capture kept the head and dropped the terminal result event, so the engine’s context-free JSON repair persisted schema-valid but amnesiac rows that claimed the task “was not present in the available context.” The capture now keeps the stream tail and reports truncation, the agent prefers the live interpreter’s completed answer parsed before the cap, token usage falls back to the completed event, and a warning fires on truncation. Fixes #277.
  • Completed-event answer is preserved when result.text is empty, and structured-output extraction trusts the CLI output file over stdout fallbacks.
  • CodexAgent honors the <Worktree> cwd and the brittle --cd worktree fallback is removed.

​
CLI and database

  • smithers.db resolves from the project anchor, not raw CWD. Running commands from inside .smithers/ (or any subdirectory) created a stray smithers.db and silently fragmented run history. Both apps/cli and packages/smithers now walk upward for a .smithers/ anchor (excluding HOME and the filesystem root), stop at an anchor whose DB does not exist yet rather than crossing the project boundary, warn when multiple databases are found, and include the consulted DB path in RUN_NOT_FOUND. Fixes #240. PR #248.
  • bunx smithers-orchestrator output resolves camelCase output tables. A node whose output table schema key is camelCase printed null, because state stores the schema key verbatim while the physical table is snake_case. The lookup now tries the stored name first and falls back to the snake_case translation only when no physical table with the stored name exists. Fixes #276.
  • Large command stdout is flushed synchronously so piped output is no longer truncated. Fixes #235.
  • Default agent scaffolding no longer ships broken providers. Generated agents.ts now leads the smart and smartTool pools with a working Claude subscription provider, drops the opencode-over-Anthropic-API entry from the defaults, and fails with NO_USABLE_AGENTS rather than writing a configuration that cannot run. Fixes #236. PR #270.
  • bunx smithers-orchestrator ui GATEWAY_UNREACHABLE hint now points at starting a real Gateway instead of a command that does not exist, and clarifies that up --serve lacks the /v1/rpc/* routes ui needs. Fixes #244.

​
Gateway and observability

  • Approval-submit errors are corrected, duplicate-approval errors are documented, and inactive-cancel errors are mapped.
  • The SSE reconnect loop stops for already-finished runs, due timer runs resume, and devtools sync streams resume after reconnect.
  • observability ships its Docker Compose stack assets at the path the CLI resolves, with a clearer prerequisite message (fixes #262, PR #269). Truncation logs are downgraded from ERROR to WARN, and the apps/observability dts build is fixed so the faults CI job is green (fixes #275).

​
Package facades and types

  • VibeAgent is exposed from the root facade, and Vibe is included in the agent-availability type.
  • time-travel exposes typed revert helpers, and vcs root exports and declarations are aligned.
  • The db runState subpath is Bun-safe and typed.
  • components honors drift-detector alerts and relaxes the DriftDetector poll interval, and the scheduler retry-policy surface is aligned.

​
MCP and Pi plugin

  • MCP artifact serialization preserves boolean values (fixes #234), approval-request metadata is inspectable through the semantic tools (fixes #232), and summaries include the workflow path.
  • Silent structured-output degradation now emits a warning at the prompt-injection fallback, and ctx.output() strips the internal harness fields (runId, nodeId, iteration) so they do not leak into downstream prompts. Fixes #243. PR #247.
  • The Pi plugin no longer crashes the inspector on /smithers in Pi 0.78.1 (fixes #233), no longer unconditionally replaces the Pi footer and header (fixes #231), and no longer blocks Pi session reload on MCP startup.

​
Changes

​
Default model ids refreshed to the current generation

The built-in provider defaults now point at the current model generation. bunx smithers-orchestrator init scaffolding, the ask and optimize flows, and the documentation examples were all updated:
  • Anthropic, Claude Code, and OpenCode-via-Anthropic default to claude-fable-5.
  • OpenAI, Codex, and Pi default to gpt-5.5.
  • Cerebras defaults to zai-glm-4.7.
  • Kimi and Moonshot default to kimi-k2.6.
bunx smithers-orchestrator init also scaffolds a Claude Opus (claude-opus-4-8) variant alongside Claude Sonnet, and derives the smart, smartTool, and cheapFast agent pools from provider families instead of placing every detected account in smart. If you pin models explicitly in .smithers/agents.ts, nothing changes; the new ids only affect freshly scaffolded projects and unpinned defaults.

​
Documentation

​
Agent-operated CLI framing

The docs now state explicitly that a coding agent operates the Smithers CLI on the human’s behalf. The guide, quickstart, CLI cheatsheet, component pages, MCP server docs, and the agent skill make the division of responsibility concrete: the agent runs every command itself, relays approval and human-task prompts to the human in conversation, and submits the resolving command (approve, deny, human answer, signal) without asking the human to type Smithers commands. Installation remains the one step a human may run by hand.

​
Aspects token and latency budgets enforced

<Aspects> tokenBudget and latencySlo are now enforced by the engine at task-dispatch time: before each descendant task runs, the run’s accumulated token total (tokenBudget.max) and wall-clock since the run started (latencySlo.maxMs) are checked against the budget and onExceeded is applied: fail raises ASPECT_BUDGET_EXCEEDED and fails the run, warn logs and continues, skip-remaining skips the task. Accumulated token usage survives resume. The USD costBudget prop was removed; budget on tokens instead. Per-task limits (perTask) are not enforced yet. Implements #273; fixes #265. PRs #274, #290. The reference docs also document the @smithers-orchestrator/review package and the sandbox:up and sandbox:down GCP VM scripts in the package-configuration tables.

​
Also in this release

The init-pack seeded workflows gained close-issues (with a gateway UI), validated-implement, real-stack-e2e, the smithering meta-workflow, and release-content (replacing marketing-thread), plus regression eval suites for the seeded init workflows that measured and lifted their pass rate from 43/60 to 59/60. More example workflow patterns landed under examples/. Internal product work also landed in this period, including the Smithers review cloud service and the Smithers Pair multiplayer proof of concept; these are not part of the published npm packages.