> ## 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.18.0

> 0.18.0 should be a minor release. Since 0.17.0, Smithers has gained new

0.18.0 should be a **minor release**. Since 0.17.0, Smithers has gained new
public Gateway UI APIs, two browser-facing SDK packages, an OpenCode CLI agent,
new stable RPC methods, and a larger default workflow pack. There are no
intentional breaking changes, but the new package and API surface is larger than
a patch release.

***

## Gateway UI SDKs

* **New browser client package: `@smithers-orchestrator/gateway-client`.** It
  ships `SmithersGatewayClient`, `SmithersGatewayConnection`, typed request and
  response maps for the stable Gateway RPC contract, structured `GatewayRpcError`
  handling, HTTP RPC helpers, WebSocket connection support, and a
  `streamRunEvents()` async iterator for run-scoped event streams.

* **New React package: `@smithers-orchestrator/gateway-react`.** It ships
  `SmithersGatewayProvider`, `createGatewayReactRoot`, and hooks for common UI
  reads and actions: `useGatewayRpc`, `useGatewayRuns`, `useGatewayRun`,
  `useGatewayRunEvents`, `useGatewayWorkflows`, `useGatewayApprovals`,
  `useGatewayNodeOutput`, and `useGatewayActions`.

* **Convenience subpath exports from `smithers-orchestrator`.** Apps can import
  the new SDK surfaces through `smithers-orchestrator/gateway-client` and
  `smithers-orchestrator/gateway-react` in addition to the standalone workspace
  packages.

## Gateway-Hosted React UIs

* **Gateway can now serve a custom browser UI from the Gateway origin.** Pass
  `ui: { entry, path, title, props }` to `new Gateway(...)` to mount a
  gateway-level React app.

* **Workflows can define their own UI mounts.** `gateway.register("deploy",
  workflow, { ui })` mounts workflow-specific UIs, defaulting to
  `/workflows/<workflowKey>` when no explicit path is provided.

* **The server generates the HTML shell and browser boot config.** Gateway
  injects `globalThis.__SMITHERS_GATEWAY_UI__` with the API version, mount kind,
  workflow key, RPC path, WebSocket path, asset base path, and custom props.

* **React entries are bundled with Bun for the browser.** The generated client
  bundle is served under `__smithers_ui/client.js` with no-store caching and
  content-type hardening.

## Gateway RPC

* **New stable `listWorkflows` RPC.** Clients can list Gateway-registered
  workflows over HTTP or WebSocket with `run:read`, optionally filtering by
  `hasUi`. Responses include `key`, optional `readableName` and `description`,
  `hasUi`, and `uiPath`.

* **New stable `listApprovals` RPC.** Clients can list pending approval requests
  over HTTP or WebSocket with `run:read`, filtering by `runId`, `workflow`, and
  `limit`. Approval summaries now include the workflow key and approval metadata
  needed by operator UIs.

* **Legacy aliases remain supported.** `workflows.list` maps to
  `listWorkflows`, and `approvals.list` continues to work through the updated
  approval-listing path.

* **OpenAPI and RPC docs were updated.** The Gateway contract now documents 19
  stable RPC methods, including new reference pages for `listWorkflows` and
  `listApprovals`.

## Agents

* **New `OpenCodeAgent`.** Smithers now ships an OpenCode CLI integration with
  support for system prompts, per-call session resume, token usage parsing from
  OpenCode `step_finish` events, structured provider errors on nonzero exits,
  capability discovery, and published TypeScript types.

* **CLI agent JSON output parsing is broader.** The shared CLI agent base now
  understands OpenCode-style `finish`, `done`, and `text` JSON events, strips
  terminal OSC title sequences from parsed output, and extracts structured error
  messages from JSON streams before falling back to stderr.

* **OpenAI and Anthropic SDK agents use native structured output.** SDK-backed
  agents now advertise `supportsNativeStructuredOutput` and pass task
  `outputSchema` through the provider's native object-output path instead of
  relying only on prompt-level JSON instructions.

## Default Workflow Pack

* **`bunx smithers-orchestrator init` now seeds the `mission` workflow.** `mission` is a
  long-horizon workflow that plans work into milestones, optionally waits for
  plan approval, runs focused feature workers in parallel, integrates milestone
  output, validates the checkpoint, performs one follow-up repair pass when
  validation fails, and writes a final report.

* **Mission runs can use worktree isolation.** The workflow supports
  `useWorktrees`, `baseBranch`, milestone and feature limits, and a configurable
  max concurrency.

* **New local `workflow-skill` workflow.** This workflow scans local
  `.smithers/workflows` files and asks an agent to create or update
  agent-facing skill docs under `.smithers/skills` or a caller-provided output
  path.

* **Workflow follow-up CTAs were expanded.** Research, planning, PRD, and ticket
  workflows now point toward `mission` when a request should become a
  milestone-gated run. `mission` points to review, test-coverage, and audit
  workflows for follow-up quality passes.

## Docs

* **New Default Workflows docs section.** The docs navigation now lists the
  scaffolded workflow pack, with pages for `implement`, `research`,
  `research-plan-implement`, `plan`, `mission`, `kanban`, `review`, `debug`,
  `improve-test-coverage`, `ticket-create`, `tickets-create`, `grill-me`,
  `write-a-prd`, `feature-enum`, `audit`, `ralph`, and `workflow-skill`.

* **Gateway integration docs now show the custom React UI flow.** The page
  documents gateway-level and workflow-level UI config, browser client usage,
  and React hook usage.

* **Docs config gained repository links.** The Mintlify navbar and footer now
  link to the Smithers GitHub repository.

* **README onboarding was refreshed.** The README now points new users at
  `bunx smithers-orchestrator@latest init` and describes the generated workflow
  pack as ready-to-run.

## Fixes and Hardening

* **Non-retryable agent failures are now honored.** Agent configuration failures
  such as `AGENT_CONFIG_INVALID`, and failures marked with
  `failureRetryable: false`, now stop retrying instead of looping through the
  scheduler and bridge retry paths.

* **Scheduler failure recovery no longer trips over planned recovery work.** The
  scheduler now tracks active failure-recovery keys so failed tasks that are
  being handled by recovery branches do not prematurely terminate the run.

* **Duplicate output-schema references produce a clear error.** Workflows that
  register the same raw Zod object under multiple output keys now fail with an
  explicit `UNKNOWN_OUTPUT_SCHEMA` message telling authors to use
  `createSmithers(...).outputs.<key>` or a string output key.

* **`bunx smithers-orchestrator init` resolves published package versions
  correctly.** The workflow pack now reads its own package version from the
  installed CLI package, resolves dependency versions with `createRequire`, and
  writes a concrete `smithers-orchestrator` semver range instead of always using
  `"latest"`.

* **Published package dependency guardrails were added.** New tests simulate the
  installed `bunx` layout and verify published workspace packages declare their
  external runtime imports instead of depending on monorepo-hoisted phantom
  dependencies.

* **Gateway React provider handles `createElement` children correctly.** The
  provider now renders children through React's `createElement` call path and
  has regression coverage.

* **Gateway UI bundling uses an explicit Bun browser config.** The bundler now
  sets the browser target, ESM format, inline source maps, and React automatic
  JSX settings.

* **Generated server types include the new Gateway UI surface.** The server type
  bundle now exports `GatewayRegisterOptions`, `GatewayUiConfig`,
  `GatewayUiMount`, and `ResolvedGatewayUiConfig`; the server build also clears
  stale generated declarations before rebuilding.

* **`<Worktree>` accepts React keys in its props type.** `WorktreeProps` now
  includes `key`, matching how keyed worktree wrappers are used in generated and
  hand-written TSX workflows.

* **SDK checks are deterministic.** The new client and React packages use local
  tool paths for build/typecheck scripts and include focused tests for HTTP RPC
  calls and React provider wiring.

* **CLI init smoke coverage was expanded.** The E2E init test now verifies the
  seeded `mission` files, prompt templates, and workflow-pack typecheck harness.