smithers-orchestrator 0.1.18 → 0.2.0

package/README.md

@@ -21,6 +21,7 @@ I use Smithers for both long-term (weeks) agentic work, as well as one-off scrip
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Usage](#usage)
+- [AI SDK React Hooks](#ai-sdk-react-hooks)
 - [Recipes](#recipes)
 - [Features](#features)
   - [Claude Component](#claude-component)
@@ -29,7 +30,11 @@ I use Smithers for both long-term (weeks) agentic work, as well as one-off scrip
   - [MCP Tool Integration](#mcp-tool-integration)
   - [Smithers Subagent](#smithers-subagent)
   - [Git/JJ VCS Integration](#gitjj-vcs-integration)
+  - [Orchestration Lifecycle](#orchestration-lifecycle)
+  - [PhaseRegistry & Step](#phaseregistry--step)
+  - [Parallel Execution](#parallel-execution)
   - [Database State Management](#database-state-management)
+  - [Rate Limit Monitoring](#rate-limit-monitoring)
 - [Contributing](#contributing)
 
 ---
@@ -43,7 +48,7 @@ I wanted a tool that allows me to:
 - **Persist state across sessions** - pick up where I left off, even days later
 - **Mix short scripts with long-running workflows** - same syntax for a quick task or a week-long project
 - **See what my agents are doing** - full observability with database logging and reports
-- **Use reactive primitives** - Solid.js signals mean my workflows respond to state changes automatically
+- **Use reactive primitives** - React state means my workflows respond to state changes automatically
 - **Compose complex behaviors from simple components** - loops, phases, steps, and validation all snap together
 - **Keep everything in version control** - workflows are just TypeScript files
 
@@ -54,11 +59,13 @@ I wanted a tool that allows me to:
 ### Install the Smithers Plugin for Claude Code
 
 **Step 1:** Add the Smithers marketplace:
+
 ```bash
 /plugin marketplace add evmts/smithers
 ```
 
 **Step 2:** Install the plugin:
+
 ```bash
 /plugin install smithers@smithers
 ```
@@ -70,7 +77,7 @@ This gives Claude Code the `smithers-orchestrator` skill for creating multi-agen
 If you want to use Smithers components directly in your own scripts:
 
 ```bash
-bun add smithers
+bun add smithers-orchestrator
 ```
 
 ---
@@ -80,13 +87,12 @@ bun add smithers
 ### Required
 
 - **[Bun](https://bun.sh/)** - JavaScript runtime (v1.0+)
-- **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)** - `npm install -g @anthropic-ai/claude-code`
+- **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)** - `bun install -g @anthropic-ai/claude-code`
 
 ### Optional
 
 - **[jj (Jujutsu)](https://github.com/martinvonz/jj)** - Alternative VCS with better snapshot support
-- **Gemini CLI** - For Gemini model support (coming soon)
-- **Codex CLI** - For OpenAI model support (coming soon)
+- **[Codex CLI](https://github.com/openai/codex)** - Used for post-commit code reviews
 
 ---
 
@@ -106,17 +112,14 @@ Your agent understands the component model and generates correct, working orches
 
 ### State Persistence
 
-All Smithers state is saved in a **PGlite database** on your system that can be easily inspected:
+All Smithers state is saved in a **SQLite database** on your system that can be easily inspected:
 
 ```bash
 # View execution history
-smithers-orchestrator db executions
+smithers db executions
 
 # View state for a specific execution
-smithers-orchestrator db state --execution-id abc123
-
-# Query the database directly
-smithers-orchestrator db query "SELECT * FROM agents ORDER BY started_at DESC LIMIT 10"
+smithers db state --execution-id abc123
 ```
 
 ### Basic Example
@@ -124,10 +127,10 @@ smithers-orchestrator db query "SELECT * FROM agents ORDER BY started_at DESC LI
 ```tsx
 #!/usr/bin/env bun
 
-import { createSmithersRoot } from "smithers";
-import { createSmithersDB } from "smithers/smithers-orchestrator/src/db";
-import { SmithersProvider } from "smithers/smithers-orchestrator/src/components/SmithersProvider";
-import { Claude } from "smithers/smithers-orchestrator/src/components/Claude";
+import { createSmithersRoot } from "smithers-orchestrator";
+import { createSmithersDB } from "smithers-orchestrator/db";
+import { SmithersProvider } from "smithers-orchestrator/components/SmithersProvider";
+import { Claude } from "smithers-orchestrator/components/Claude";
 
 const db = await createSmithersDB({ path: ".smithers/my-task" });
 const executionId = await db.execution.start("My Task", "scripts/my-task.tsx");
@@ -159,6 +162,41 @@ bun my-workflow.tsx
 
 ---
 
+## AI SDK React Hooks
+
+Smithers re-exports the Vercel AI SDK React hooks so you can import everything
+from a single package:
+
+```tsx
+import { useChat, useCompletion, useSmithers } from "smithers-orchestrator";
+
+function ChatUI() {
+  const { messages, sendMessage, status } = useChat({ api: "/api/chat" });
+  const { db } = useSmithers();
+
+  return (
+    <div>
+      <p>Status: {status}</p>
+      {messages.map((message) => (
+        <div key={message.id}>{message.content}</div>
+      ))}
+      <button onClick={() => sendMessage({ role: "user", content: "Hi" })}>
+        Send
+      </button>
+    </div>
+  );
+}
+```
+
+You can also import directly from the hooks subpath:
+
+```tsx
+import { useChat } from "smithers-orchestrator/hooks";
+import { useChat as useAiChat } from "smithers-orchestrator/hooks/ai-sdk";
+```
+
+---
+
 ## Recipes
 
 ### Multi-Phase Review Workflow
@@ -168,40 +206,38 @@ async function ReviewWorkflow() {
   const phase = (await db.state.get("phase")) ?? "implement";
 
   return (
-    <SmithersProvider db={db} executionId={executionId}>
+    <SmithersProvider db={db} executionId={executionId} maxIterations={10}>
       <Orchestration globalTimeout={3600000}>
-        <Ralph maxIterations={10}>
-          {phase === "implement" && (
-            <Phase name="Implementation">
-              <Claude
-                model="sonnet"
-                onFinished={() => db.state.set("phase", "review")}
-              >
-                Implement the user authentication feature.
-              </Claude>
-            </Phase>
-          )}
-
-          {phase === "review" && (
-            <Phase name="Code Review">
-              <Review
-                target={{ type: "diff", ref: "main" }}
-                criteria={[
-                  "No security vulnerabilities",
-                  "Tests cover edge cases",
-                  "Types are properly defined",
-                ]}
-                onFinished={(review) => {
-                  if (review.approved) {
-                    db.state.set("phase", "complete");
-                  } else {
-                    db.state.set("phase", "implement");
-                  }
-                }}
-              />
-            </Phase>
-          )}
-        </Ralph>
+        {phase === "implement" && (
+          <Phase name="Implementation">
+            <Claude
+              model="sonnet"
+              onFinished={() => db.state.set("phase", "review")}
+            >
+              Implement the user authentication feature.
+            </Claude>
+          </Phase>
+        )}
+
+        {phase === "review" && (
+          <Phase name="Code Review">
+            <Review
+              target={{ type: "diff", ref: "main" }}
+              criteria={[
+                "No security vulnerabilities",
+                "Tests cover edge cases",
+                "Types are properly defined",
+              ]}
+              onFinished={(review) => {
+                if (review.approved) {
+                  db.state.set("phase", "complete");
+                } else {
+                  db.state.set("phase", "implement");
+                }
+              }}
+            />
+          </Phase>
+        )}
       </Orchestration>
     </SmithersProvider>
   );
@@ -293,10 +329,12 @@ The core agent component that executes Claude with full tool access:
 
 ### Ralph Loop Controller
 
+> **Prefer SmithersProvider.** The loop functionality is built into `<SmithersProvider>` with `maxIterations`. Use `<Ralph>` only for nested loops within a workflow.
+
 Named after Ralph Wiggum's "I'm in danger" catchphrase - controls iterative loops that could run away:
 
 ```tsx
-<Ralph maxIterations={10} onMaxIterations={() => console.log("I'm in danger!")}>
+<SmithersProvider db={db} executionId={executionId} maxIterations={10}>
   {/* Children re-render on each iteration */}
   <Claude
     onFinished={() => {
@@ -305,7 +343,7 @@ Named after Ralph Wiggum's "I'm in danger" catchphrase - controls iterative loop
   >
     Keep improving until tests pass.
   </Claude>
-</Ralph>
+</SmithersProvider>
 ```
 
 ### Structured Output with Zod
@@ -337,6 +375,37 @@ Give Claude access to external tools via Model Context Protocol:
 </Claude>
 ```
 
+### AI SDK Tool Format
+
+Define tools with Zod schemas and pass them to Claude:
+
+```tsx
+import { z } from "zod";
+import { createSmithersTool } from "smithers-orchestrator/tools";
+
+const reportTool = createSmithersTool({
+  name: "report",
+  description: "Report progress to the orchestrator",
+  inputSchema: z.object({
+    message: z.string(),
+    severity: z.enum(["info", "warning", "error"]).optional(),
+  }),
+  execute: async ({ message, severity }, { db }) => {
+    await db.vcs.addReport({
+      type: "progress",
+      title: "Agent Report",
+      content: message,
+      severity: severity ?? "info",
+    });
+    return { success: true };
+  },
+});
+
+<Claude tools={[reportTool]}>
+  Report progress as you go.
+</Claude>
+```
+
 ### Smithers Subagent
 
 Spawn a new Smithers instance to plan and execute complex subtasks:
@@ -353,6 +422,16 @@ Spawn a new Smithers instance to plan and execute complex subtasks:
 </Smithers>
 ```
 
+### Worktree
+
+Run agents in isolated git worktrees:
+
+```tsx
+<Worktree branch="feature-auth" cleanup>
+  <Claude>Implement user authentication</Claude>
+</Worktree>
+```
+
 ### Git/JJ VCS Integration
 
 First-class version control support:
@@ -366,6 +445,52 @@ First-class version control support:
 <Commit autoDescribe />
 ```
 
+### Orchestration Lifecycle
+
+Global timeout and completion logic for workflows:
+
+```tsx
+<Orchestration
+  globalTimeout={3600000} // 1 hour max
+  onComplete={() => console.log("Workflow finished")}
+  onTimeout={() => console.log("Workflow timed out")}
+>
+  {/* Your workflow components */}
+</Orchestration>
+```
+
+### PhaseRegistry & Step
+
+Manage multi-phase sequential execution:
+
+```tsx
+<PhaseRegistry>
+  <Phase name="implement">
+    <Step name="write-code" snapshotBefore commitAfter commitMessage="feat: Implementation">
+      <Claude>Implement the feature</Claude>
+    </Step>
+    <Step name="write-tests">
+      <Claude>Write tests for the implementation</Claude>
+    </Step>
+  </Phase>
+  <Phase name="review">
+    <Review target={{ type: "diff", ref: "main" }} />
+  </Phase>
+</PhaseRegistry>
+```
+
+### Parallel Execution
+
+Run multiple agents concurrently within a step:
+
+```tsx
+<Parallel>
+  <Claude model="haiku">Quick task 1</Claude>
+  <Claude model="haiku">Quick task 2</Claude>
+  <Claude model="haiku">Quick task 3</Claude>
+</Parallel>
+```
+
 ### Database State Management
 
 Persistent state that survives restarts:
@@ -384,6 +509,22 @@ const history = await db.state.getHistory("phase");
 const all = await db.state.getAll();
 ```
 
+### Rate Limit Monitoring
+
+Track provider rate limit headroom and execution-scoped token usage:
+
+```typescript
+import { createRateLimitMonitor } from "smithers-orchestrator/rate-limits";
+
+const monitor = createRateLimitMonitor({
+  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },
+  db,
+});
+
+const status = await monitor.getStatus("anthropic", "claude-sonnet-4");
+const usage = await monitor.getUsage(executionId);
+```
+
 ---
 
 ## Contributing
@@ -398,4 +539,4 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
 ---
 
-**Built with Solid.js, powered by Claude.**
+**Built with React, powered by Claude.**

package/bin/cli.ts

@@ -1,69 +1,117 @@
 #!/usr/bin/env bun
 
-import { Command } from 'commander'
-import { init } from '../src/orchestrator/commands/init.ts'
-import { run } from '../src/orchestrator/commands/run.ts'
-import { monitor } from '../src/orchestrator/commands/monitor.ts'
-import { dbCommand } from '../src/orchestrator/commands/db.ts'
+import { Command } from "commander";
+import { init } from "../src/commands/init.ts";
+import { run } from "../src/commands/run.ts";
+import { monitor } from "../src/commands/monitor.ts";
+import { dbCommand } from "../src/commands/db.ts";
+import { launchTUI } from "../src/tui/index.tsx";
+import { DEFAULT_DB_DIR, DEFAULT_MAIN_FILE, resolveDbPaths } from "../src/commands/cli-utils.ts";
 
-const program = new Command()
+const program = new Command();
 
 program
-  .name('smithers')
-  .description('CLI tool for multi-agent AI orchestration with Smithers framework')
-  .version('0.1.0')
+  .name("smithers")
+  .description(
+    "CLI tool for multi-agent AI orchestration with Smithers framework",
+  )
+  .version("0.1.0");
 
 program
-  .command('init')
-  .description('Create a new Smithers orchestration in .smithers/')
-  .option('-d, --dir <directory>', 'Directory to create .smithers in', process.cwd())
-  .action(init)
+  .command("init")
+  .description("Create a new Smithers orchestration in .smithers/")
+  .option(
+    "-d, --dir <directory>",
+    "Directory to create .smithers in",
+    process.cwd(),
+  )
+  .action(init);
 
 program
-  .command('run [file]')
-  .description('Run a Smithers orchestration file')
-  .option('-f, --file <file>', 'Orchestration file to run', '.smithers/main.tsx')
-  .action(run)
+  .command("run [file]")
+  .description("Run a Smithers orchestration file (default: .smithers/main.tsx)")
+  .action((file?: string) => run(file));
 
 program
-  .command('monitor [file]')
-  .description('Run with LLM-friendly monitoring (recommended)')
-  .option('-f, --file <file>', 'Orchestration file to monitor', '.smithers/main.tsx')
-  .option('--no-summary', 'Disable Haiku summarization')
-  .action(monitor)
+  .command("monitor [file]")
+  .description("Run with LLM-friendly monitoring (recommended)")
+  .option(
+    "-f, --file <file>",
+    "Orchestration file to monitor",
+    DEFAULT_MAIN_FILE,
+  )
+  .option("--no-summary", "Disable Haiku summarization")
+  .action(monitor);
 
 program
-  .command('db [subcommand]')
-  .description('Inspect and manage the PGlite database')
-  .option('--path <path>', 'Database path', '.smithers/data')
-  .action(dbCommand)
+  .command("db [subcommand]")
+  .description("Inspect and manage the SQLite database")
+  .option("--path <path>", "Database path", DEFAULT_DB_DIR)
+  .action(dbCommand);
 
-// Hook trigger command - called by git hooks to notify orchestration
 program
-  .command('hook-trigger <type> <data>')
-  .description('Trigger a hook event (used by git hooks)')
-  .option('--path <path>', 'Database path', '.smithers/data')
+  .command("tui")
+  .description("Launch observability TUI dashboard")
+  .option("-p, --path <path>", "Database path", ".smithers/data")
+  .action(async (options: { path: string }) => {
+    try {
+      await launchTUI({ dbPath: options.path });
+    } catch (error) {
+      console.error('❌ Failed to launch TUI:', error instanceof Error ? error.message : error);
+      if (!process.stdout.isTTY) {
+        console.error('   TUI requires an interactive terminal');
+      }
+      process.exit(1);
+    }
+  });
+
+const VALID_HOOK_TYPES = ['pre-commit', 'post-commit', 'pre-push', 'post-merge'] as const
+
+program
+  .command("hook-trigger <type> <data>")
+  .description("Trigger a hook event (used by git hooks). Data must be valid JSON.")
+  .option("--path <path>", "Database path", DEFAULT_DB_DIR)
   .action(async (type: string, data: string, options: { path: string }) => {
+    if (!VALID_HOOK_TYPES.includes(type as typeof VALID_HOOK_TYPES[number])) {
+      console.error(`❌ Invalid hook type: ${type}`)
+      console.error(`   Valid types: ${VALID_HOOK_TYPES.join(', ')}`)
+      process.exit(1)
+    }
+
+    let parsedData: unknown
     try {
-      // Dynamically import to avoid loading DB on every CLI call
-      const { createSmithersDB } = await import('../src/orchestrator/db/index.ts')
+      parsedData = JSON.parse(data)
+    } catch {
+      console.error(`❌ Invalid JSON data: ${data}`)
+      console.error('   Data must be valid JSON')
+      process.exit(1)
+    }
 
-      const db = await createSmithersDB({ path: options.path })
+    try {
+      const { createSmithersDB } = await import(
+        "../src/db/index.ts"
+      );
+
+      const { dbFile } = resolveDbPaths(options.path);
+      const db = createSmithersDB({ path: dbFile });
 
-      // Store the trigger in state
-      await db.state.set('last_hook_trigger', {
-        type,
-        data,
-        timestamp: Date.now(),
-      })
+      db.state.set(
+        "last_hook_trigger",
+        {
+          type,
+          data: parsedData,
+          timestamp: Date.now(),
+        },
+        "hook-trigger",
+      );
 
-      await db.close()
+      db.close();
 
-      console.log(`[Hook] Triggered: ${type} with ${data}`)
+      console.log(`[Hook] Triggered: ${type}`);
     } catch (error) {
-      console.error('[Hook] Error:', error)
-      process.exit(1)
+      console.error("[Hook] Error:", error);
+      process.exit(1);
     }
-  })
+  });
 
-program.parse(process.argv)
+program.parse(process.argv);

package/bunfig.toml

@@ -1,11 +1,9 @@
 # Bun configuration for Smithers
 # https://bun.sh/docs/runtime/bunfig
 
-# Use bun-plugin-solid for Solid JSX transform
-preload = ["./preload.ts"]
-
 [install]
 auto = "fallback"
 
 [test]
-preload = ["./preload.ts", "./test/preload.ts"]
+preload = ["./test/preload.ts"]
+exclude = ["**/reference/**", "**/node_modules/**"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.1.18",
-  "description": "Build AI agents with Solid.js - Declarative JSX for Claude orchestration",
+  "version": "0.2.0",
+  "description": "Build AI agents with React - Declarative JSX for Claude orchestration",
   "type": "module",
   "main": "./src/index.ts",
   "bin": {
@@ -9,26 +9,32 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./jsx-runtime": "./src/jsx-runtime.ts",
-    "./jsx-dev-runtime": "./src/jsx-runtime.ts",
+    "./jsx-runtime": "./src/reconciler/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/reconciler/jsx-runtime.ts",
     "./core": "./src/core/index.ts",
-    "./solid": "./src/solid/index.ts",
+    "./reconciler": "./src/reconciler/index.ts",
+    "./react": "./src/reconciler/index.ts",
     "./components": "./src/components/index.ts",
     "./components/Ralph": "./src/components/Ralph.tsx",
     "./components/Review": "./src/components/Review.tsx",
     "./components/Phase": "./src/components/Phase.tsx",
     "./components/Step": "./src/components/Step.tsx",
+    "./components/Claude": "./src/components/Claude.tsx",
+    "./components/SmithersProvider": "./src/components/SmithersProvider.tsx",
+    "./components/Orchestration": "./src/components/Orchestration.tsx",
+    "./components/Smithers": "./src/components/Smithers.tsx",
     "./components/JJ": "./src/components/JJ/index.ts",
     "./components/Git": "./src/components/Git/index.ts",
     "./components/Hooks": "./src/components/Hooks/index.ts",
     "./components/MCP": "./src/components/MCP/index.ts",
-    "./orchestrator": "./src/orchestrator/components/index.ts",
-    "./orchestrator/SmithersProvider": "./src/orchestrator/components/SmithersProvider.tsx",
-    "./orchestrator/Orchestration": "./src/orchestrator/components/Orchestration.tsx",
-    "./orchestrator/Claude": "./src/orchestrator/components/Claude.tsx",
-    "./orchestrator/Phase": "./src/orchestrator/components/Phase.tsx",
-    "./orchestrator/Step": "./src/orchestrator/components/Step.tsx",
-    "./db": "./src/orchestrator/db/index.ts"
+    "./middleware": "./src/middleware/index.ts",
+    "./db": "./src/db/index.ts",
+    "./monitor": "./src/monitor/index.ts",
+    "./rate-limits": "./src/rate-limits/index.ts",
+    "./tools": "./src/tools/index.ts",
+    "./reactive-sqlite": "./src/reactive-sqlite/index.ts",
+    "./hooks": "./src/hooks/index.ts",
+    "./hooks/ai-sdk": "./src/hooks/ai-sdk.ts"
   },
   "files": [
     "src",
@@ -43,18 +49,23 @@
   "scripts": {
     "build": "echo 'No build needed - Bun runs TypeScript directly'",
     "typecheck": "tsc --noEmit",
-    "test": "bun test",
-    "test:watch": "bun test --watch"
+    "lint": "oxlint src/",
+    "lint:fix": "oxlint --fix src/",
+    "test": "cd src && bun test .",
+    "test:watch": "cd src && bun test --watch .",
+    "check": "bun run typecheck && bun run lint && bun run test",
+    "prepare": "husky"
   },
   "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",
-    "babel-preset-solid": "^1.9.10",
+    "@opentui/core": "^0.1.74",
+    "@opentui/react": "^0.1.74",
     "commander": "^12.0.0",
-    "solid-js": "^1.9.10",
+    "react": "^19.0.0",
+    "react-reconciler": "^0.32.0",
     "zod": "^4.3.5"
   },
   "peerDependencies": {
@@ -62,13 +73,16 @@
   },
   "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"
   },
   "keywords": [
     "ai",
     "agent",
-    "solid",
-    "solidjs",
+    "react",
     "jsx",
     "llm",
     "claude",