smithers-orchestrator 0.1.18 → 0.2.1

package/README.md

@@ -18,9 +18,8 @@ I use Smithers for both long-term (weeks) agentic work, as well as one-off scrip
 ## Table of Contents
 
 - [Why](#why)
-- [Installation](#installation)
-- [Dependencies](#dependencies)
-- [Usage](#usage)
+- [Getting Started](#getting-started)
+- [AI SDK React Hooks](#ai-sdk-react-hooks)
 - [Recipes](#recipes)
 - [Features](#features)
   - [Claude Component](#claude-component)
@@ -29,7 +28,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,91 +46,66 @@ 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
 
 ---
 
-## Installation
+## Getting Started
 
-### Install the Smithers Plugin for Claude Code
+### Prerequisites
 
-**Step 1:** Add the Smithers marketplace:
-```bash
-/plugin marketplace add evmts/smithers
-```
-
-**Step 2:** Install the plugin:
-```bash
-/plugin install smithers@smithers
-```
+- **[Bun](https://bun.sh/)** - JavaScript runtime (v1.0+)
+- **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)** - `bun install -g @anthropic-ai/claude-code`
 
-This gives Claude Code the `smithers-orchestrator` skill for creating multi-agent workflows.
+Optional:
+- **[jj (Jujutsu)](https://github.com/martinvonz/jj)** - Alternative VCS with better snapshot support
+- **[Codex CLI](https://github.com/openai/codex)** - Used for post-commit code reviews
 
-### Optional: Install the npm package for programmatic use
+### Install into Claude Code
 
-If you want to use Smithers components directly in your own scripts:
+Add to your Claude Code settings (`~/.claude/settings.json`):
 
-```bash
-bun add smithers
+```json
+{
+  "projects": {
+    "/path/to/your/project": {
+      "mcpServers": {},
+      "allowedTools": ["smithers-orchestrator:*"]
+    }
+  }
+}
 ```
 
----
-
-## Dependencies
-
-### 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`
-
-### Optional
+Then install the package as a dev dependency:
 
-- **[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)
-
----
-
-## Usage
+```bash
+bun add -d smithers-orchestrator
+```
 
-### Let Your Agent Write Smithers
+### Use It
 
-**You don't have to write Smithers yourself.** Tell your agent what you want, and it generates the workflow:
+**You don't have to write Smithers yourself.** Tell Claude what you want:
 
 ```
-User: "Create a workflow that monitors my CI, fixes failures automatically, and escalates after 3 failed attempts"
+User: "Create a workflow that monitors my CI, fixes failures automatically,
+       and escalates after 3 failed attempts"
 
 Claude: *generates ci-recovery.tsx*
 ```
 
-Your agent understands the component model and generates correct, working orchestration scripts.
+Claude understands the component model and generates correct, working orchestration scripts.
 
-### State Persistence
-
-All Smithers state is saved in a **PGlite database** on your system that can be easily inspected:
-
-```bash
-# View execution history
-smithers-orchestrator 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"
-```
-
-### Basic Example
+### Run a Workflow
 
 ```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");
@@ -151,12 +129,54 @@ await root.mount(MyWorkflow);
 await db.close();
 ```
 
-Run it:
-
 ```bash
 bun my-workflow.tsx
 ```
 
+### Inspect State
+
+All state persists in SQLite:
+
+```bash
+smithers db executions                      # View execution history
+smithers db state --execution-id abc123     # View specific execution state
+```
+
+---
+
+## 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
@@ -168,40 +188,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 +311,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 +325,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 +357,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 +404,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 +427,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 +491,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 +521,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/**"]