smithers-orchestrator 0.24.2 → 0.25.0

package/README.md

@@ -0,0 +1,231 @@
+# smithers-orchestrator
+
+**Run long-horizon coding-agent work as durable workflows.**
+
+[![npm](https://img.shields.io/npm/v/smithers-orchestrator?color=2563eb&label=npm)](https://www.npmjs.com/package/smithers-orchestrator)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2563eb)](https://github.com/smithersai/smithers/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-smithers.sh-2563eb)](https://smithers.sh)
+
+Tell your coding agent to do real, multi-step work, then Smithers runs it for minutes or
+days with crash recovery, retries, human approvals, and full observability. The same
+workflow runs across Claude Code, Codex, Pi, AI SDK models, and remote sandboxes.
+
+This package is the published Smithers runtime: the engine, the `smithers` CLI, the JSX
+workflow primitives, the agent adapters, and the Gateway. Install it once and your coding
+agent drives the rest.
+
+![Live workflow runs: some succeeded, some running, some paused on an approval gate, every run resumable and rewindable.](https://raw.githubusercontent.com/smithersai/smithers/main/marketing/0.22.0/assets/runs-live.gif)
+
+*A workflow run is a list of steps you can watch, pause, approve, and rewind. The run above shows several in flight at once.*
+
+## What you get
+
+- 🛡️ **Durable runs that survive crashes**: every completed step is persisted the moment it
+  finishes, so a run resumes from where it stopped instead of starting over.
+- 🔌 **Any agent, any model**: Claude Code, Codex, Pi, Antigravity, and more, plus any model
+  through the AI SDK. Swap the harness without rewriting the workflow.
+- 🛠️ **Higher-quality output**: review loops, human approvals, and evals give agents the
+  structure that real work demands.
+- 🧩 **Dozens of ready-to-run workflows**: planning, implementation, review, debugging,
+  tickets, audits, and long-horizon missions. Your agent can author new ones.
+
+## When to use Smithers
+
+Smithers is the durable runtime for *coding-agent* work: when the unit of work is an agent
+editing a real repository over many steps, and you need that work to be inspectable,
+approvable, and recoverable. Use it when order matters across multiple AI steps, you need
+crash recovery, a human must approve or answer mid-run, or different tasks need different
+models. For a single prompt → single response, call your model provider's SDK directly;
+Smithers adds nothing there.
+
+## Get started
+
+Smithers is driven by your coding agent, **not** a GUI you click. Your agent runs Smithers
+on your behalf: it scaffolds workflows, kicks off runs, watches them, and handles
+approvals.
+
+One command sets everything up. From inside your project:
+
+```bash
+bunx smithers-orchestrator init
+```
+
+`init` does everything:
+
+- **Installs the `smithers` skill** into the coding agents on your machine (Claude Code,
+  Pi, and more), so your agent knows how and when to use Smithers. No `mkdir`, no `curl`.
+- **Scaffolds `.smithers/`** with ready-made workflows (`hello`, `implement`, `plan`,
+  `review`, `debug`, and more) your agent can pick from.
+
+Then just ask:
+
+> *"orchestrate an agent to add rate limiting and keep iterating until the tests pass."*
+
+Your agent picks the right workflow, starts the run, and keeps going through retries and
+review loops until the work is actually done.
+
+> **Always run `bunx smithers-orchestrator`, never `bunx smithers`.** On npm, `smithers`
+> is an unrelated package. The installed binary alias `smithers` is only safe inside a
+> project that resolves `node_modules/.bin/smithers`.
+
+To wire the MCP server into every detected agent too, run
+`bunx smithers-orchestrator mcp add`. See [Agent Support](https://smithers.sh/agents/overview)
+for the full per-agent matrix.
+
+## Drive it yourself
+
+Prefer the CLI? The seeded `hello` workflow is the smallest possible run; its entire prompt
+is an editable Markdown file at `.smithers/prompts/hello.mdx`:
+
+```bash
+# run your first workflow (edit .smithers/prompts/hello.mdx to change it)
+bunx smithers-orchestrator workflow run hello
+
+# turn a request into a practical implementation plan
+bunx smithers-orchestrator workflow run plan --prompt "add rate limiting, audit logging, and API key rotation"
+```
+
+Watch what's happening, whether your agent started the run or you did:
+
+```bash
+bunx smithers-orchestrator ps              # list active, paused, and recently completed runs
+bunx smithers-orchestrator inspect RUN_ID  # steps, agents, approvals, and outputs for one run
+bunx smithers-orchestrator logs RUN_ID     # tail the event log
+bunx smithers-orchestrator chat RUN_ID     # read the agent's chat output
+```
+
+Run `bunx smithers-orchestrator starters` to browse plain-English starters, and
+`bunx smithers-orchestrator workflow list` to see what's installed.
+
+## Durable by default
+
+Durability is the differentiator. Runs survive crashes, restarts, and flaky tools because
+**every completed step is persisted to SQLite the moment it finishes**. The runtime always
+knows what's done and what to run next. Approvals, human questions, retries, and replay are
+first-class.
+
+```text
+prompt → render workflow → run task → validate output → persist to SQLite → re-render → resume · inspect · replay
+```
+
+That loop is the whole model: a task runs, its output is validated against a schema and
+written down, then the workflow re-renders from persisted state to decide the next task. A
+crash at any point resumes from the last write, not from the top.
+
+```bash
+bunx smithers-orchestrator up workflow.tsx --input '{"description":"Fix bug"}'
+bunx smithers-orchestrator up workflow.tsx --run-id abc123 --resume true   # resume after a crash
+bunx smithers-orchestrator rewind abc123 --frame 4                          # time-travel to an earlier frame
+bunx smithers-orchestrator fork abc123                                      # branch an alternate timeline
+bunx smithers-orchestrator replay abc123                                    # replay from a checkpoint
+```
+
+## Author your own
+
+The built-in workflows are normal Smithers TSX files: run them as-is, have your agent adapt
+them to your repo, or have it write new ones from the same primitives. A workflow is a JSX
+tree of tasks, each with a Zod-validated output:
+
+```tsx
+import { createSmithers, Sequence } from "smithers-orchestrator";
+import { z } from "zod";
+
+const { Workflow, Task, smithers, outputs } = createSmithers({
+  analyze: z.object({
+    summary: z.string(),
+    severity: z.enum(["low", "medium", "high"]),
+  }),
+  fix: z.object({
+    patch: z.string(),
+    explanation: z.string(),
+  }),
+});
+
+export default smithers((ctx) => (
+  <Workflow name="bugfix">
+    <Sequence>
+      <Task id="analyze" output={outputs.analyze} agent={analyzer}>
+        {`Analyze the bug: ${ctx.input.description}`}
+      </Task>
+
+      <Task id="fix" output={outputs.fix} agent={fixer}>
+        {`Fix this issue: ${ctx.latest("analyze").summary}`}
+      </Task>
+    </Sequence>
+  </Workflow>
+));
+```
+
+Each task output is validated against its Zod schema and persisted to SQLite. If the
+process crashes, Smithers resumes from the last completed node without re-running finished
+work.
+
+| Component    | Purpose                               |
+| ------------ | ------------------------------------- |
+| `<Workflow>` | Root container                        |
+| `<Task>`     | AI or static task node                |
+| `<Sequence>` | Ordered execution                     |
+| `<Parallel>` | Concurrent execution                  |
+| `<Branch>`   | Conditional execution                 |
+| `<Loop>`     | Repeat tasks until a condition is met |
+
+There are many more: approvals, merge queues, sub-workflows, signals, timers, sagas,
+sandboxes, and composite patterns. See
+[Components](https://smithers.sh/components/workflow).
+
+## Package entry points
+
+The main entry re-exports the full toolkit, so most code only needs
+`import { ... } from "smithers-orchestrator"`. Dedicated subpaths exist for focused imports:
+
+| Import | What it gives you |
+| --- | --- |
+| `smithers-orchestrator` | `createSmithers`, the workflow components, agent adapters, errors, and the rest of the core API. |
+| `smithers-orchestrator/tools` | The built-in agent tool sandbox. |
+| `smithers-orchestrator/gateway-client` | Typed client for the Gateway RPC/WS control plane. |
+| `smithers-orchestrator/gateway-react` | React hooks for live, multi-run state. |
+| `smithers-orchestrator/sandbox` | The `<Sandbox>` primitive and `SandboxProvider` interface. |
+| `smithers-orchestrator/control-plane` | Programmatic control-plane API for launching and steering runs. |
+| `smithers-orchestrator/server` | The Gateway server (`startServer`, `createServeApp`). |
+| `smithers-orchestrator/observability` | Prometheus metrics and OpenTelemetry tracing layers. |
+| `smithers-orchestrator/memory` | Cross-run memory store and recall. |
+| `smithers-orchestrator/scorers` | Eval scorers (LLM-judge, relevancy, faithfulness, …). |
+| `smithers-orchestrator/openapi` | Generate AI SDK tools from OpenAPI specs. |
+
+## Any agent, any model
+
+Point each task at whichever agent is best for the job, mix several in one workflow, and
+switch freely. The workflow doesn't change when the model does, so a frontier model can
+plan, a fast model can fan out, and a specialized harness can do the edits.
+
+Agent adapters ship in the box, including `ClaudeCodeAgent`, `CodexAgent`, `PiAgent`,
+`AntigravityAgent`, `GeminiAgent`, and `AnthropicAgent` / `OpenAIAgent` for any AI SDK
+model (with tools, structured output, and MCP). The same `<Sandbox>` primitive runs an
+agent locally (Bubblewrap or Docker), in a container, on a managed remote like
+[Freestyle](https://freestyle.sh), or on any backend you implement against
+`SandboxProvider`.
+
+## Requirements
+
+- [Bun](https://bun.sh) ≥ 1.3
+- TypeScript ≥ 5 (only for authoring TSX workflows)
+- Model or provider credentials (e.g. `ANTHROPIC_API_KEY`)
+- A version control system for snapshotting and isolating agent work:
+  [jj (Jujutsu)](https://github.com/jj-vcs/jj) or [git](https://git-scm.com). jj is
+  preferred and powers durability, time-travel, and per-task worktrees; the optional
+  `@smithers-orchestrator/jj-<platform>` package bundles a jj binary so a fresh install
+  works with no system jj.
+
+## Docs
+
+Full documentation lives at **[smithers.sh](https://smithers.sh)**.
+
+- [Introduction](https://smithers.sh/introduction) — what Smithers is and when to use it.
+- [Quickstart](https://smithers.sh/quickstart) — scaffold and run a workflow in two commands.
+- [Tour](https://smithers.sh/tour) — a guided walk through a real run.
+- [How It Works](https://smithers.sh/how-it-works) — the durable execution model.
+- [Components](https://smithers.sh/components/workflow) — the full primitive set.
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,32 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Public Smithers facade for durable coding-agent workflows and Gateway operation",
+  "license": "MIT",
+  "homepage": "https://smithers.sh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "agents",
+    "coding-agent",
+    "orchestration",
+    "workflow",
+    "durable-execution",
+    "react",
+    "jsx",
+    "llm",
+    "claude",
+    "codex",
+    "bun"
+  ],
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -52,7 +77,8 @@
     }
   },
   "files": [
-    "src/"
+    "src/",
+    "README.md"
   ],
   "bin": {
     "smithers": "./src/bin/smithers.js"
@@ -66,28 +92,28 @@
     "incur": "^0.4.1",
     "react": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/agents": "0.24.2",
-    "@smithers-orchestrator/control-plane": "0.24.2",
-    "@smithers-orchestrator/components": "0.24.2",
-    "@smithers-orchestrator/db": "0.24.2",
-    "@smithers-orchestrator/engine": "0.24.2",
-    "@smithers-orchestrator/driver": "0.24.2",
-    "@smithers-orchestrator/errors": "0.24.2",
-    "@smithers-orchestrator/gateway-client": "0.24.2",
-    "@smithers-orchestrator/gateway-react": "0.24.2",
-    "@smithers-orchestrator/graph": "0.24.2",
-    "@smithers-orchestrator/memory": "0.24.2",
-    "@smithers-orchestrator/openapi": "0.24.2",
-    "@smithers-orchestrator/react-reconciler": "0.24.2",
-    "@smithers-orchestrator/sandbox": "0.24.2",
-    "@smithers-orchestrator/observability": "0.24.2",
-    "@smithers-orchestrator/scheduler": "0.24.2",
-    "@smithers-orchestrator/scorers": "0.24.2",
-    "@smithers-orchestrator/server": "0.24.2",
-    "@smithers-orchestrator/time-travel": "0.24.2",
-    "@smithers-orchestrator/vcs": "0.24.2",
-    "@smithers-orchestrator/tool-context": "0.24.2",
-    "@smithers-orchestrator/cli": "0.24.2"
+    "@smithers-orchestrator/agents": "0.25.0",
+    "@smithers-orchestrator/components": "0.25.0",
+    "@smithers-orchestrator/control-plane": "0.25.0",
+    "@smithers-orchestrator/db": "0.25.0",
+    "@smithers-orchestrator/engine": "0.25.0",
+    "@smithers-orchestrator/driver": "0.25.0",
+    "@smithers-orchestrator/errors": "0.25.0",
+    "@smithers-orchestrator/gateway-client": "0.25.0",
+    "@smithers-orchestrator/gateway-react": "0.25.0",
+    "@smithers-orchestrator/graph": "0.25.0",
+    "@smithers-orchestrator/memory": "0.25.0",
+    "@smithers-orchestrator/observability": "0.25.0",
+    "@smithers-orchestrator/openapi": "0.25.0",
+    "@smithers-orchestrator/react-reconciler": "0.25.0",
+    "@smithers-orchestrator/sandbox": "0.25.0",
+    "@smithers-orchestrator/scorers": "0.25.0",
+    "@smithers-orchestrator/scheduler": "0.25.0",
+    "@smithers-orchestrator/server": "0.25.0",
+    "@smithers-orchestrator/time-travel": "0.25.0",
+    "@smithers-orchestrator/vcs": "0.25.0",
+    "@smithers-orchestrator/cli": "0.25.0",
+    "@smithers-orchestrator/tool-context": "0.25.0"
   },
   "optionalDependencies": {
     "@electric-sql/pglite": "0.5.1",
@@ -99,6 +125,7 @@
     "typescript": "~5.9.3"
   },
   "scripts": {
+    "test": "bun test tests",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build": "tsup --dts-only"
   }

package/src/CreateSmithersOptions.ts

@@ -6,4 +6,11 @@ export type CreateSmithersOptions = {
 	alertPolicy?: SmithersAlertPolicy;
 	dbPath?: string;
 	journalMode?: string;
+	/**
+	 * Backend the caller resolved this API to. The synchronous `createSmithers`
+	 * only serves `"sqlite"`; `"pglite"`/`"postgres"` require the async
+	 * `openSmithersBackend` factory and fail loud here rather than silently
+	 * opening bun:sqlite.
+	 */
+	backend?: "sqlite" | "pglite" | "postgres";
 };

package/src/MigrateSmithersStoreOptions.ts

@@ -0,0 +1,22 @@
+export type MigrateSmithersStoreOptions = {
+	cwd?: string;
+	dbPath?: string;
+	to?: "pglite" | "postgres";
+	url?: string;
+	env?: Record<string, string | undefined>;
+	pgliteDataDir?: string;
+	keepSqlite?: boolean;
+	batchSize?: number;
+	onProgress?: (event:
+		| { type: "table-start"; table?: string; sourceRows?: number }
+		| {
+				type: "table-copied";
+				table?: string;
+				copiedRows?: number;
+				sourceRows?: number;
+				targetRows?: number;
+				durationMs?: number;
+		  }
+		| { type: "done"; copiedRows?: number; tableCount?: number; durationMs?: number }
+	) => void | Promise<void>;
+};

package/src/OpenSmithersBackendOptions.ts

@@ -0,0 +1,13 @@
+import type { CreateSmithersOptions } from "./CreateSmithersOptions";
+
+type SmithersBackend = "sqlite" | "pglite" | "postgres";
+
+export type OpenSmithersBackendOptions = CreateSmithersOptions & {
+	backend?: SmithersBackend;
+	cwd?: string;
+	configPath?: string;
+	env?: Record<string, string | undefined>;
+	connectionString?: string;
+	connection?: object;
+	pgliteDataDir?: string;
+};

package/src/ResolveSmithersBackendChoiceOptions.ts

@@ -0,0 +1,7 @@
+export type ResolveSmithersBackendChoiceOptions = {
+	backend?: "sqlite" | "pglite" | "postgres";
+	cwd?: string;
+	dbPath?: string;
+	configPath?: string;
+	env?: Record<string, string | undefined>;
+};

package/src/SmithersBackendChoice.ts

@@ -0,0 +1,9 @@
+export type SmithersBackendChoice = {
+	backend: "sqlite" | "pglite" | "postgres";
+	source: "options" | "env" | "config" | "default";
+	dbPath: string;
+	workspaceRoot: string;
+	runCount: number;
+	schemaVersion: string;
+	migratedMarker: boolean;
+};

package/src/SmithersMigrationResult.ts

@@ -0,0 +1,15 @@
+export type SmithersMigrationResult = {
+	backend: "pglite" | "postgres";
+	dbPath: string;
+	markerPath: string;
+	target: {
+		backend: "pglite" | "postgres";
+		dataDir?: string;
+		url?: string;
+	};
+	runCount: number;
+	schemaVersion: string;
+	durationMs: number;
+	tables: Array<{ table: string; sourceRows: number; targetRows: number; durationMs: number }>;
+	sqliteRemoved: boolean;
+};

package/src/create.js

@@ -18,7 +18,9 @@ import { SmithersDb } from "@smithers-orchestrator/db/adapter";
 import { POSTGRES } from "@smithers-orchestrator/db/dialect";
 import { resolve, join } from "node:path";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { assertZodV4 } from "@smithers-orchestrator/errors/assertZodV4";
 import { findSmithersAnchorDir } from "./findSmithersAnchorDir.js";
+import { prepareOutputSchemas } from "./prepareOutputSchemas.js";
 /** @typedef {import("@smithers-orchestrator/components").ApprovalProps<any, any>} ApprovalProps */
 /** @typedef {import("@smithers-orchestrator/components").SandboxProps} SandboxProps */
 /** @typedef {import("@smithers-orchestrator/components").SignalProps<any>} SignalProps */
@@ -52,41 +54,6 @@ function computeSchemaSig(schemas, dbPath) {
     }
     return parts.join("\n");
 }
-/**
- * Duplicate schema objects need distinct output refs so Task `output={outputs.foo}`
- * can still resolve the intended table by identity.
- * @param {Record<string, any>} schemas
- */
-function prepareOutputSchemas(schemas) {
-    const counts = new Map();
-    for (const [name, zodSchema] of Object.entries(schemas)) {
-        if (name === "input")
-            continue;
-        counts.set(zodSchema, (counts.get(zodSchema) ?? 0) + 1);
-    }
-    const outputs = {
-        ...schemas,
-    };
-    const zodToKeyName = new Map();
-    const ambiguousZodSchemas = new Set();
-    for (const [name, zodSchema] of Object.entries(schemas)) {
-        if (name === "input")
-            continue;
-        if ((counts.get(zodSchema) ?? 0) > 1) {
-            ambiguousZodSchemas.add(zodSchema);
-            const aliasSchema = zodSchema.clone();
-            outputs[name] = aliasSchema;
-            zodToKeyName.set(aliasSchema, name);
-            continue;
-        }
-        zodToKeyName.set(zodSchema, name);
-    }
-    return {
-        outputs,
-        zodToKeyName,
-        ambiguousZodSchemas,
-    };
-}
 /**
  * @param {Record<string, string>} [base]
  * @param {Record<string, string>} [override]
@@ -184,6 +151,13 @@ function mergeAlertPolicies(base, override) {
  * @param {Record<string, any>} schemas
  */
 function prepareSmithersTables(schemas) {
+    // Fail fast and clearly at workflow construction if any schema is not Zod v4.
+    // smithers reads Zod v4 internals (schema._zod) and uses z.toJSONSchema();
+    // a Zod v3 schema would otherwise silently build wrong columns here and crash
+    // later with a cryptic `schema._zod.def` TypeError deep in the agent path.
+    for (const [name, zodSchema] of Object.entries(schemas)) {
+        assertZodV4(zodSchema, name);
+    }
     const tables = {};
     const inputTable = schemas.input
         ? zodToTable("input", schemas.input, { isInput: true })
@@ -366,6 +340,20 @@ function buildSmithersApi(config) {
  * ```
  */
 export function createSmithers(schemas, opts) {
+    // Honor an explicitly requested backend instead of silently opening
+    // bun:sqlite. `createSmithers` is the synchronous SQLite path; PGlite and
+    // Postgres provision over the wire asynchronously, so a workflow that wants
+    // them must use the async `openSmithersBackend` factory (which returns this
+    // exact API). When `--backend pglite|postgres` / `SMITHERS_BACKEND` selects a
+    // non-SQLite backend but the workflow still calls `createSmithers`, fail loud
+    // (design decision 4: never silently degrade) instead of running on SQLite.
+    const requestedBackend = (opts?.backend ?? process.env.SMITHERS_BACKEND ?? "").toLowerCase();
+    if (requestedBackend === "pglite" || requestedBackend === "postgres") {
+        throw new SmithersError("INVALID_INPUT", `createSmithers() is the synchronous bun:sqlite backend and cannot serve the "${requestedBackend}" backend. ` +
+            `Author the workflow with the async factory instead:\n\n` +
+            `  const { smithers, Workflow, outputs } = await openSmithersBackend(schemas);\n\n` +
+            `or run on SQLite with \`--backend sqlite\` (or SMITHERS_BACKEND=sqlite, or backend:"sqlite" in smithers.config.ts).`, { requestedBackend });
+    }
     // Resolve the DB path from the nearest .smithers/ anchor so that running a
     // workflow from a subdirectory always creates/uses the project-root DB, not
     // a new one at CWD. An explicit opts.dbPath overrides this entirely.

package/src/external/create-external-smithers.js

@@ -18,6 +18,7 @@ import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { prepareOutputSchemas } from "../prepareOutputSchemas.js";
 /** @typedef {import("@smithers-orchestrator/agents/AgentLike").AgentLike} AgentLike */
 /** @typedef {import("@smithers-orchestrator/components/SmithersWorkflow").SmithersWorkflow<any>} SmithersWorkflow */
 /**
@@ -64,33 +65,6 @@ export function hostNodeToReact(node, agents) {
     const children = node.children.map((child) => hostNodeToReact(child, agents));
     return React.createElement(node.tag, rawProps, ...children);
 }
-/**
- * @param {Record<string, any>} schemas
- */
-function prepareOutputSchemas(schemas) {
-    const counts = new Map();
-    for (const [name, zodSchema] of Object.entries(schemas)) {
-        if (name === "input")
-            continue;
-        counts.set(zodSchema, (counts.get(zodSchema) ?? 0) + 1);
-    }
-    const zodToKeyName = new Map();
-    const ambiguousZodSchemas = new Set();
-    for (const [name, zodSchema] of Object.entries(schemas)) {
-        if (name === "input")
-            continue;
-        if ((counts.get(zodSchema) ?? 0) > 1) {
-            ambiguousZodSchemas.add(zodSchema);
-            zodToKeyName.set(zodSchema.clone(), name);
-            continue;
-        }
-        zodToKeyName.set(zodSchema, name);
-    }
-    return {
-        zodToKeyName,
-        ambiguousZodSchemas,
-    };
-}
 /**
  * Create a SmithersWorkflow from an external build function.
  *