smithers-orchestrator 0.3.0 → 0.4.0

package/README.md

@@ -1,220 +1,324 @@
 # Smithers
 
-[![npm version](https://img.shields.io/npm/v/smithers-orchestrator.svg)](https://www.npmjs.com/package/smithers-orchestrator)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+**Declarative AI workflow orchestration with React.**
 
-**Ralph the plan, not the agent.**
+Multi-agent workflows are messy. Prompt chains break. Error handling is ad hoc. State lives in variables that vanish when your process crashes. Smithers fixes this by letting you define AI workflows as React component trees — declarative, composable, and automatically durable.
 
-**Status: Alpha - not ready for production use.**
+```tsx
+import { createSmithers, Task, Parallel, Ralph } from "smithers-orchestrator";
 
-Your orchestrating agent writes React code that spawns and controls other agents. [Let your agents write agents](https://smithers.sh/harness-integration#claude-code-plugin).
+const { Workflow, smithers } = createSmithers({
+  discover: z.object({ issues: z.array(z.string()) }),
+  ticket:   z.object({ title: z.string(), body: z.string() }),
+  review:   z.object({ approved: z.boolean(), feedback: z.string() }),
+});
 
-Used to orchestrate coding agents that run for days, ship PRs autonomously, and self-heal when they fail.
+export default smithers((ctx) => (
+  <Workflow name="triage">
+    <Task id="discover" output="discover" agent={analyst}>
+      Find issues in the codebase
+    </Task>
+    <Parallel>
+      {ctx.output("discover", { nodeId: "discover" }).issues.map((issue, i) => (
+        <Task key={i} id={`ticket-${i}`} output="ticket" agent={writer}>
+          {`Write a ticket for: ${issue}`}
+        </Task>
+      ))}
+    </Parallel>
+    <Ralph until={ctx.latest("review", "review-0")?.approved} maxIterations={3}>
+      <Task id="review-0" output="review" agent={reviewer}>
+        {`Review the tickets. Previous feedback: ${ctx.latest("review", "review-0")?.feedback ?? "none"}`}
+      </Task>
+    </Ralph>
+  </Workflow>
+));
+```
 
-```tsx
-#!/usr/bin/env smithers
-import {
-  createSmithersRoot,
-  createSmithersDB,
-  SmithersProvider,
-  Claude,
-} from "smithers-orchestrator";
-
-const db = createSmithersDB({ path: ".smithers/demo.db" });
-const executionId = db.execution.start("Demo", "demo.tsx");
-
-function Demo() {
-  return (
-    <SmithersProvider db={db} executionId={executionId} maxIterations={5}>
-      <Claude model="sonnet" onFinished={(r) => console.log(r.output)}>
-        Fix the failing tests in this repository.
-      </Claude>
-    </SmithersProvider>
-  );
-}
+Your workflow is a DAG. Each `<Task>` is a node. `<Sequence>`, `<Parallel>`, `<Branch>`, and `<Ralph>` control execution order. The tree re-renders after each task completes — just like React re-renders after state changes. Outputs are persisted to SQLite, so a crashed workflow resumes exactly where it left off.
 
-const root = createSmithersRoot();
-await root.mount(Demo);
-await db.close();
-```
+## Install
 
-Run it and monitor the execution frame by frame:
+Requires [Bun](https://bun.sh) >= 1.3.
 
 ```bash
-smithers demo.tsx
+bun add smithers-orchestrator ai @ai-sdk/anthropic zod
 ```
 
-Smithers is a React framework for coding agents. Write the plan in any coding harness, then monitor your agents as they execute it. The plan is a mix of hardcoded logic and agent output that evolves reactively.
-
-By evolving a declarative plan rather than wiring up every agent interaction, Smithers excels at:
+## Quick Start
 
-1. **One-time agents** that accomplish a task and discard
-2. **Long-running agents** that run for days or weeks
+### 1. Define your schemas
 
----
+Each task output is a Zod schema. Smithers auto-creates SQLite tables from them.
 
-## Core Idea
+```ts
+import { z } from "zod";
 
-You program the **plan**, not the agents. The plan is real executable code: React components that declare what should happen.
+const analyzeSchema = z.object({
+  summary: z.string(),
+  severity: z.enum(["low", "medium", "high"]),
+  files: z.array(z.string()),
+});
 
-| Other Frameworks     | Smithers                   |
-| -------------------- | -------------------------- |
-| `agent.do_step_1()`  | `<Phase name="implement">` |
-| `agent.do_step_2()`  | `<Step name="code">`       |
-| `if failed: retry()` | `<Claude>Fix it</Claude>`  |
+const fixSchema = z.object({
+  patch: z.string(),
+  explanation: z.string(),
+});
+```
 
-The plan is declarative. Plans evolve in an easy-to-understand way over time, and if the plan breaks for any reason, your monitoring agent can edit the code and restart.
+### 2. Create your smithers instance
 
-What renders is the current state of the multi-agent setup as readable XML, with SQLite durably persisting state.
+```ts
+import { createSmithers, Task, Sequence } from "smithers-orchestrator";
+import { ToolLoopAgent as Agent } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
 
-Each iteration:
+const { Workflow, useCtx, smithers } = createSmithers({
+  analyze: analyzeSchema,
+  fix: fixSchema,
+});
+```
 
-1. Render React to execution plan
-2. Execute runnable agents
-3. Agent output updates state
-4. State change triggers re-render
-5. Loop until done
+`createSmithers` handles everything: SQLite database, Drizzle tables, schema validation, context provider. You get back a typed `Workflow` component, a `useCtx()` hook, and a `smithers()` function to export your workflow.
 
-The plan runs as deterministic code, but agents can read it to understand the larger context they're operating within.
+### 3. Define your agents
 
-Ralph (the [autonomous agent loop pattern](https://ghuntley.com/ralph/)) handles the render cycle, allowing the plan to run and evolve indefinitely. React handles the diffing.
+```ts
+const analyzer = new Agent({
+  model: anthropic("claude-sonnet-4-20250514"),
+  instructions: "You are a code analyst. Return structured JSON.",
+});
 
----
+const fixer = new Agent({
+  model: anthropic("claude-sonnet-4-20250514"),
+  instructions: "You are a senior engineer who writes minimal, correct fixes.",
+});
+```
 
-## Why React?
+### 4. Build your workflow
 
-LLMs and humans perform well writing declarative React code. All coding agents can one-shot valid Smithers workflows naturally.
+```tsx
+export default smithers((ctx) => (
+  <Workflow name="bugfix">
+    <Sequence>
+      <Task id="analyze" output="analyze" outputSchema={analyzeSchema} agent={analyzer}>
+        {`Analyze the bug: ${ctx.input.description}`}
+      </Task>
+      <Task id="fix" output="fix" outputSchema={fixSchema} agent={fixer}>
+        {`Fix this issue: ${ctx.output("analyze", { nodeId: "analyze" }).summary}`}
+      </Task>
+    </Sequence>
+  </Workflow>
+));
+```
 
-Most multi-agent frameworks fail. They add coordination overhead that costs more than it saves, and you end up worse than a simple while loop. Smithers avoids this by making the plan declarative and the state durable. React's functional nature makes even complex multiagent setups easy to modularize and easy to reason about.
+### 5. Run it
 
-React has a rich ecosystem that works well with agents: Zustand, React Query, and reactive versions of most libraries plug directly into React's reactivity system. This lets you compose declarative plans from battle-tested primitives.
+```bash
+bunx smithers run workflow.tsx --input '{"description": "Auth tokens expire silently"}'
+```
 
-React gives you:
+Or programmatically:
 
-- Composition and reuse
-- Version control diffs that make sense
-- Agent-generated code you can review
-- A massive ecosystem of reactive hooks to reuse
+```ts
+import { runWorkflow } from "smithers-orchestrator";
+import workflow from "./workflow";
 
-**React Hook Compatibility**: All [TanStack AI](https://tanstack.com/ai/latest/docs) and [Vercel AI SDK](https://ai-sdk.dev/docs) React hooks work in Smithers components.
+const result = await runWorkflow(workflow, {
+  input: { description: "Auth tokens expire silently" },
+});
+```
 
----
+## Core Concepts
 
-## Quick Examples
+### Components as pipeline stages
 
-### Sequential Phases
+Every stage in your pipeline is a React component. This means you get composition, reuse, and conditional rendering for free.
 
 ```tsx
-<SmithersProvider db={db} executionId={executionId} maxIterations={10}>
-  <Phase name="implement">
-    <Step name="code">
-      <Claude>Implement the feature</Claude>
-    </Step>
-    <Step name="test">
-      <Claude>Write tests</Claude>
-    </Step>
-  </Phase>
-  <Phase name="review">
-    <Claude>Review the changes</Claude>
-  </Phase>
-</SmithersProvider>
-```
-
-### Parallel Agents
+function CodeReview({ fileGlob }: { fileGlob: string }) {
+  const ctx = useCtx();
+  return (
+    <Sequence>
+      <Task id="lint" output="lint" outputSchema={lintSchema} agent={linter}>
+        {`Lint files matching ${fileGlob}`}
+      </Task>
+      <Task id="review" output="review" outputSchema={reviewSchema} agent={reviewer}>
+        {`Review the lint results: ${JSON.stringify(ctx.latest("lint", "lint"))}`}
+      </Task>
+    </Sequence>
+  );
+}
 
-```tsx
+// Reuse it
 <Parallel>
-  <Claude>Fix auth</Claude>
-  <Claude>Fix database</Claude>
-  <Claude>Fix API</Claude>
+  <CodeReview fileGlob="src/**/*.ts" />
+  <CodeReview fileGlob="tests/**/*.ts" />
 </Parallel>
 ```
 
-### Structured Output
+### Structured output with Zod
 
-```tsx
-const ReviewSchema = z.object({
-  approved: z.boolean(),
-  issues: z.array(z.string()),
-});
+Every task output is validated against its Zod schema. If the agent returns malformed JSON, Smithers automatically retries with the validation error appended to the prompt — the agent self-corrects.
 
-<Claude schema={ReviewSchema}>Review the PR.</Claude>;
-// result.structured: { approved: boolean, issues: string[] }
+```tsx
+<Task
+  id="analyze"
+  output="analyze"
+  outputSchema={analyzeSchema}
+  agent={analyzer}
+  retries={2}
+>
+  Analyze the codebase for security issues
+</Task>
 ```
 
-### Worktree Isolation
+### MDX prompts
 
-```tsx
-<Worktree branch="feature-auth" cleanup>
-  <Claude>Implement authentication</Claude>
-</Worktree>
-```
+Complex prompts get unwieldy as template literals. Use MDX instead — it renders to clean markdown, not HTML.
 
----
+```mdx
+{/* prompts/analyze.mdx */}
+# Security Analysis
 
-## Persistence
+Analyze **{props.target}** for vulnerabilities.
 
-State lives in SQLite. Survives restarts.
+## Focus areas
+- {props.focus}
+- Input validation
+- Authentication flows
+```
 
 ```tsx
-// Set state
-db.state.set("phase", "review");
+import { mdxPlugin } from "smithers-orchestrator";
+import AnalyzePrompt from "./prompts/analyze.mdx";
 
-// Get state
-const phase = db.state.get("phase");
+mdxPlugin(); // register once
 
-// Resume after crash
-const incomplete = db.execution.findIncomplete();
-if (incomplete) {
-  executionId = incomplete.id;
-}
+<Task id="analyze" output="analyze" agent={analyzer}>
+  <AnalyzePrompt target="src/auth" focus="token handling" />
+</Task>
 ```
 
----
+### Validation loops with Ralph
 
-## Observability
+`<Ralph>` re-runs its children until a condition is met. Each iteration is tracked separately in the database with an `iteration` counter.
 
-The React tree is the observability. What you write is what gets logged.
+```tsx
+<Ralph
+  until={ctx.latest("review", "validate")?.approved}
+  maxIterations={5}
+>
+  <Task id="implement" output="implement" agent={coder}>
+    {`Fix based on feedback: ${ctx.latest("review", "validate")?.feedback ?? "Initial implementation"}`}
+  </Task>
+  <Task id="validate" output="review" agent={reviewer}>
+    {`Review the implementation: ${ctx.latest("implement", "implement")?.code}`}
+  </Task>
+</Ralph>
+```
+
+### Dynamic branching
+
+The workflow tree re-renders after each task. Use standard JSX conditionals to create dynamic plans.
 
 ```tsx
-<Phase name="deploy">
-  <Step name="build" status="completed">
-    ...
-  </Step>
-  <Step name="test" status="running">
-    ...
-  </Step>
-</Phase>
+<Task id="assess" output="assess" agent={analyst}>
+  Assess the complexity of this task
+</Task>
+
+{ctx.output("assess", { nodeId: "assess" }).complexity === "high" ? (
+  <Sequence>
+    <Task id="plan" output="plan" agent={architect}>Plan the implementation</Task>
+    <Task id="implement" output="code" agent={coder}>
+      {`Follow this plan: ${ctx.output("plan", { nodeId: "plan" }).steps}`}
+    </Task>
+  </Sequence>
+) : (
+  <Task id="implement" output="code" agent={coder}>
+    Quick fix for the issue
+  </Task>
+)}
 ```
 
-SQLite stores every frame. Use version control to rewind.
+## Components
 
----
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `<Workflow>` | Root container | `name`, `cache` |
+| `<Task>` | Single AI or static task | `id`, `output`, `agent`, `outputSchema`, `retries` |
+| `<Sequence>` | Run children in order | `skipIf` |
+| `<Parallel>` | Run children concurrently | `maxConcurrency`, `skipIf` |
+| `<Branch>` | Conditional execution | `if`, `then`, `else` |
+| `<Ralph>` | Loop until condition met | `until`, `maxIterations` |
 
-## Install
+## Context API
 
-```bash
-bun add -g smithers-orchestrator
+```tsx
+ctx.input                                          // workflow input
+ctx.output("analyze", { nodeId: "analyze" })       // specific row by string key
+ctx.output(table, { nodeId: "analyze" })           // specific row by table object
+ctx.latest("analyze", "analyze")                   // latest iteration for a node
+ctx.latestArray(value, zodSchema)                  // parse + validate array field
+ctx.iterationCount("analyze", "analyze")           // count iterations for a node
+ctx.runId                                          // current run ID
+ctx.iteration                                      // current Ralph iteration
 ```
 
-This installs the `smithers` CLI globally. Requires [Bun](https://bun.sh/) 1.0+.
+Access context inside components with the `useCtx()` hook:
 
-Or install the Claude Code plugin:
+```tsx
+const { Workflow, useCtx, smithers } = createSmithers({ ... });
 
+function MyComponent() {
+  const ctx = useCtx();
+  return <>{`Process: ${ctx.input.description}`}</>;
+}
 ```
-/plugin add evmts/smithers
+
+## Built-in Tools
+
+```tsx
+import { read, edit, bash, grep, write } from "smithers-orchestrator/tools";
+
+const codeAgent = new Agent({
+  model: anthropic("claude-sonnet-4-20250514"),
+  tools: { read, edit, bash, grep, write },
+  instructions: "You are a senior software engineer.",
+});
 ```
 
----
+All tools are sandboxed to the workflow root directory. `bash` is network-disabled by default.
+
+## How It Works
+
+1. **Define** — Zod schemas become SQLite tables. React components become your DAG.
+2. **Render** — Smithers renders the React tree, identifies runnable tasks (depth-first, left-to-right).
+3. **Execute** — The engine runs each task, validates output against the schema, writes to SQLite.
+4. **Re-render** — The tree re-renders with updated context. Newly unblocked tasks become runnable.
+5. **Repeat** — Until no runnable tasks remain. Crash at any point and resume from the last checkpoint.
 
-## Roadmap
+Every task result is a row in SQLite keyed by `(runId, nodeId, iteration)`. There is no in-memory state to lose.
 
-**North Star: SuperSmithers**: A meta-agent that watches your agents and rewrites their code to optimize. The architecture is ready. Coming soon.
+## CLI
 
----
+```bash
+smithers run workflow.tsx --input '{"description": "Fix bugs"}'
+smithers resume workflow.tsx --run-id abc123
+smithers list workflow.tsx
+smithers approve workflow.tsx --run-id abc123 --node-id review
+```
+
+## Server Mode
+
+```ts
+import { startServer } from "smithers-orchestrator/server";
+
+startServer({
+  port: 7331,
+  authToken: process.env.SMITHERS_API_KEY,
+});
+```
 
-## More
+## License
 
-- [Documentation](https://smithers.sh)
-- [Examples](./examples)
-- [Contributing](./CONTRIBUTING.md)
+MIT

package/package.json

@@ -1,71 +1,39 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.3.0",
-  "description": "Build AI agents with React - Declarative JSX for Claude orchestration",
+  "version": "0.4.0",
+  "description": "AI workflow orchestration with JSX",
+  "author": "William Cory",
   "license": "MIT",
+  "module": "src/index.ts",
   "type": "module",
-  "main": "./dist/src/index.js",
   "bin": {
-    "smithers": "./dist/bin/cli.js"
+    "smithers": "src/cli/index.ts"
   },
   "exports": {
-    ".": "./dist/src/index.js",
-    "./jsx-runtime": "./dist/src/reconciler/jsx-runtime.js",
-    "./jsx-dev-runtime": "./dist/src/reconciler/jsx-runtime.js",
-    "./db": "./dist/src/db/index.js",
-    "./supersmithers": "./dist/src/supersmithers/index.js",
-    "./supersmithers/runtime": "./dist/src/supersmithers/runtime.js",
-    "./supersmithers/register": "./dist/src/supersmithers/register.js"
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-runtime.ts",
+    "./tools": "./src/tools/index.ts",
+    "./server": "./src/server/index.ts",
+    "./pi-plugin": "./src/pi-plugin/index.ts",
+    "./mdx-plugin": "./src/mdx-plugin.ts",
+    "./dom/renderer": "./src/dom/renderer.ts"
   },
   "files": [
-    "dist",
-    "opencode",
-    "skills",
-    "templates",
-    "preload.ts",
-    "bunfig.toml",
-    "plugin.json",
-    "README.md"
+    "src/",
+    "README.md",
+    "LICENSE"
   ],
-  "scripts": {
-    "build": "bun build:lib && bun build:bin && bun build:assets",
-    "build:assets": "cp src/db/schema.sql dist/src/db/",
-    "build:lib": "bun scripts/build-lib.ts",
-    "build:bin": "bun build ./bin/cli.ts --outdir dist/bin --target bun",
-    "typecheck": "tsc --noEmit",
-    "typecheck:docs": "bun --config=/dev/null scripts/typecheck-docs.ts",
-    "lint": "oxlint src/",
-    "lint:fix": "oxlint --fix src/",
-    "test": "bun test",
-    "test:watch": "bun test --watch",
-    "check": "bun run typecheck && bun run lint && bun run test",
-    "prepare": "husky"
+  "engines": {
+    "bun": ">=1.3.0"
   },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.76",
-    "@anthropic-ai/sdk": "^0.71.2",
-    "@babel/core": "^7.28.6",
-    "@babel/preset-typescript": "^7.28.5",
-    "@electric-sql/pglite": "^0.3.15",
-    "@opencode-ai/plugin": "^1.1.31",
-    "@opentui/core": "^0.1.74",
-    "@opentui/react": "^0.1.74",
-    "commander": "^12.0.0",
-    "opencode-ai": "^1.1.31",
-    "react": "^19.0.0",
-    "react-reconciler": "^0.32.0",
-    "zod": "^4.3.5"
-  },
-  "peerDependencies": {
-    "bun": ">=1.0.0"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evmts/smithers.git"
   },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@types/react": "^19.0.0",
-    "@types/react-reconciler": "^0.28.9",
-    "husky": "^9.1.7",
-    "oxlint": "^1.39.0",
-    "typescript": "^5.7.2"
+  "homepage": "https://github.com/evmts/smithers#readme",
+  "bugs": {
+    "url": "https://github.com/evmts/smithers/issues"
   },
   "keywords": [
     "ai",
@@ -74,14 +42,37 @@
     "jsx",
     "llm",
     "claude",
-    "anthropic",
     "orchestration",
+    "workflow",
     "bun"
   ],
-  "author": "William Cory",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/evmts/smithers.git"
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "cli": "bun run src/cli/index.ts",
+    "test": "bun test tests/*.test.ts tests/*.test.tsx",
+    "e2e": "playwright test",
+    "dev": "bun run --filter smithers-desktop dev"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.36",
+    "@mdx-js/esbuild": "^3.1.1",
+    "ai": "^6.0.69",
+    "diff": "^5.2.0",
+    "drizzle-orm": "^0.45.1",
+    "drizzle-zod": "^0.8.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-reconciler": "^0.31.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/diff": "^5.2.0",
+    "@types/react": "^19.2.10",
+    "@types/react-reconciler": "^0.28.9",
+    "@playwright/test": "^1.52.0"
   }
 }