smithers-orchestrator 0.7.0 → 0.8.0

package/README.md

@@ -23,7 +23,7 @@ There is no hidden in-memory state. Every task result is stored as:
 ## Example
 
 ```tsx
-import { createSmithers, Task, Sequence } from "smithers-orchestrator";
+import { createSmithers, Sequence } from "smithers-orchestrator";
 import { z } from "zod";
 
 const analyzeSchema = z.object({
@@ -36,7 +36,7 @@ const fixSchema = z.object({
   explanation: z.string(),
 });
 
-const { Workflow, smithers } = createSmithers({
+const { Workflow, Task, smithers, outputs } = createSmithers({
   analyze: analyzeSchema,
   fix: fixSchema,
 });
@@ -44,11 +44,11 @@ const { Workflow, smithers } = createSmithers({
 export default smithers((ctx) => (
   <Workflow name="bugfix">
     <Sequence>
-      <Task id="analyze" output="analyze" agent={analyzer}>
+      <Task id="analyze" output={outputs.analyze} agent={analyzer}>
         {`Analyze the bug: ${ctx.input.description}`}
       </Task>
 
-      <Task id="fix" output="fix" agent={fixer}>
+      <Task id="fix" output={outputs.fix} agent={fixer}>
         {`Fix this issue: ${ctx.output("analyze", { nodeId: "analyze" }).summary}`}
       </Task>
     </Sequence>
@@ -103,16 +103,22 @@ If new nodes are unblocked, they become runnable.
 
 ### 2. Zod Schemas = Durable Tables
 
-Each output schema becomes a SQLite table.
+Each output schema becomes a SQLite table. Pass the schema directly to `<Task>` via the `outputs` object returned by `createSmithers`:
 
 ```ts
 const analyzeSchema = z.object({
   summary: z.string(),
   severity: z.enum(["low", "medium", "high"]),
 });
+
+const { Workflow, Task, smithers, outputs } = createSmithers({
+  analyze: analyzeSchema,
+});
+
+// outputs.analyze === analyzeSchema (the ZodObject, by reference)
 ```
 
-* Agent output must validate.
+* Agent output must validate against the schema.
 * If validation fails, the task retries (with error feedback).
 * Validated output is persisted.
 
@@ -156,8 +162,7 @@ If an agent returns malformed JSON:
 ```tsx
 <Task
   id="analyze"
-  output="analyze"
-  outputSchema={analyzeSchema}
+  output={outputs.analyze}
   agent={analyzer}
   retries={2}
 >
@@ -178,11 +183,11 @@ Each iteration is stored separately in the database.
   until={ctx.latest("review", "validate")?.approved}
   maxIterations={5}
 >
-  <Task id="implement" output="implement" agent={coder}>
+  <Task id="implement" output={outputs.implement} agent={coder}>
     Fix based on feedback
   </Task>
 
-  <Task id="validate" output="review" agent={reviewer}>
+  <Task id="validate" output={outputs.review} agent={reviewer}>
     Review the implementation
   </Task>
 </Ralph>
@@ -195,16 +200,16 @@ Each iteration is stored separately in the database.
 Because the workflow re-renders after each task, you can branch with normal JSX:
 
 ```tsx
-<Task id="assess" output="assess" agent={analyst}>
+<Task id="assess" output={outputs.assess} agent={analyst}>
   Assess complexity
 </Task>
 
 {ctx.output("assess", { nodeId: "assess" }).complexity === "high" ? (
-  <Task id="plan" output="plan" agent={architect}>
+  <Task id="plan" output={outputs.plan} agent={architect}>
     Plan implementation
   </Task>
 ) : (
-  <Task id="implement" output="code" agent={coder}>
+  <Task id="implement" output={outputs.code} agent={coder}>
     Quick fix
   </Task>
 )}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "AI workflow orchestration with JSX",
   "author": "William Cory",
   "license": "MIT",

package/src/AgentLike.ts

@@ -0,0 +1,14 @@
+export type AgentLike = {
+  id?: string;
+  tools?: Record<string, any>;
+  generate: (args: {
+    options?: any;
+    abortSignal?: AbortSignal;
+    prompt: string;
+    timeout?: { totalMs: number } | undefined;
+    onStdout?: (text: string) => void;
+    onStderr?: (text: string) => void;
+    outputSchema?: import("zod").ZodObject<any>;
+  }) => Promise<any>;
+  [key: string]: any;
+};

package/src/GraphSnapshot.ts

@@ -0,0 +1,9 @@
+import type { XmlNode } from "./XmlNode";
+import type { TaskDescriptor } from "./TaskDescriptor";
+
+export type GraphSnapshot = {
+  runId: string;
+  frameNo: number;
+  xml: XmlNode | null;
+  tasks: TaskDescriptor[];
+};

package/src/OutputAccessor.ts

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+
+export type InferRow<TTable> = TTable extends { $inferSelect: infer R }
+  ? R
+  : never;
+
+/**
+ * Infer the output type from either a Zod schema or a Drizzle table.
+ */
+export type InferOutputEntry<T> = T extends z.ZodTypeAny
+  ? z.infer<T>
+  : T extends { $inferSelect: any }
+    ? InferRow<T>
+    : never;
+
+export type OutputAccessor<Schema> = {
+  <K extends keyof Schema & string>(table: K): Array<InferOutputEntry<Schema[K]>>;
+} & {
+  [K in keyof Schema & string]: Array<InferOutputEntry<Schema[K]>>;
+};

package/src/OutputKey.ts

@@ -0,0 +1 @@
+export type OutputKey = { nodeId: string; iteration?: number };

package/src/RunOptions.ts

@@ -0,0 +1,16 @@
+import type { SmithersEvent } from "./SmithersEvent";
+
+export type RunOptions = {
+  runId?: string;
+  input: Record<string, unknown>;
+  maxConcurrency?: number;
+  onProgress?: (e: SmithersEvent) => void;
+  signal?: AbortSignal;
+  resume?: boolean;
+  workflowPath?: string;
+  rootDir?: string;
+  logDir?: string | null;
+  allowNetwork?: boolean;
+  maxOutputBytes?: number;
+  toolTimeoutMs?: number;
+};

package/src/RunResult.ts

@@ -0,0 +1,6 @@
+export type RunResult = {
+  runId: string;
+  status: "finished" | "failed" | "cancelled" | "waiting-approval";
+  output?: unknown;
+  error?: unknown;
+};

package/src/RunStatus.ts

@@ -0,0 +1,6 @@
+export type RunStatus =
+  | "running"
+  | "waiting-approval"
+  | "finished"
+  | "failed"
+  | "cancelled";

package/src/SchemaRegistryEntry.ts

@@ -0,0 +1,4 @@
+export type SchemaRegistryEntry = {
+  table: any;
+  zodSchema: import("zod").ZodObject<any>;
+};

package/src/SmithersCtx.ts

@@ -0,0 +1,29 @@
+import type { OutputKey } from "./OutputKey";
+import type { OutputAccessor, InferOutputEntry } from "./OutputAccessor";
+
+export interface SmithersCtx<Schema> {
+  runId: string;
+  iteration: number;
+  iterations?: Record<string, number>;
+  input: Schema extends { input: infer T } ? T : Record<string, unknown>;
+  outputs: OutputAccessor<Schema>;
+
+  output<K extends keyof Schema & string>(
+    table: K,
+    key: OutputKey,
+  ): InferOutputEntry<Schema[K]>;
+
+  outputMaybe<K extends keyof Schema & string>(
+    table: K,
+    key: OutputKey,
+  ): InferOutputEntry<Schema[K]> | undefined;
+
+  latest<K extends keyof Schema & string>(
+    table: K,
+    nodeId: string,
+  ): InferOutputEntry<Schema[K]> | undefined;
+
+  latestArray(value: unknown, schema: import("zod").ZodType): any[];
+
+  iterationCount(table: any, nodeId: string): number;
+}

package/src/SmithersError.ts

@@ -0,0 +1,5 @@
+export type SmithersError = {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+};

package/src/SmithersEvent.ts

@@ -0,0 +1,155 @@
+import type { RunStatus } from "./RunStatus";
+
+export type SmithersEvent =
+  | { type: "RunStarted"; runId: string; timestampMs: number }
+  | {
+      type: "RunStatusChanged";
+      runId: string;
+      status: RunStatus;
+      timestampMs: number;
+    }
+  | { type: "RunFinished"; runId: string; timestampMs: number }
+  | { type: "RunFailed"; runId: string; error: unknown; timestampMs: number }
+  | { type: "RunCancelled"; runId: string; timestampMs: number }
+  | {
+      type: "FrameCommitted";
+      runId: string;
+      frameNo: number;
+      xmlHash: string;
+      timestampMs: number;
+    }
+  | {
+      type: "NodePending";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeStarted";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeFinished";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeFailed";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      error: unknown;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeCancelled";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt?: number;
+      reason?: string;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeSkipped";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeRetrying";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      timestampMs: number;
+    }
+  | {
+      type: "NodeWaitingApproval";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      timestampMs: number;
+    }
+  | {
+      type: "ApprovalRequested";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      timestampMs: number;
+    }
+  | {
+      type: "ApprovalGranted";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      timestampMs: number;
+    }
+  | {
+      type: "ApprovalDenied";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      timestampMs: number;
+    }
+  | {
+      type: "ToolCallStarted";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      toolName: string;
+      seq: number;
+      timestampMs: number;
+    }
+  | {
+      type: "ToolCallFinished";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      toolName: string;
+      seq: number;
+      status: "success" | "error";
+      timestampMs: number;
+    }
+  | {
+      type: "NodeOutput";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      text: string;
+      stream: "stdout" | "stderr";
+      timestampMs: number;
+    }
+  | {
+      type: "RevertStarted";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      jjPointer: string;
+      timestampMs: number;
+    }
+  | {
+      type: "RevertFinished";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      jjPointer: string;
+      success: boolean;
+      error?: string;
+      timestampMs: number;
+    };

package/src/SmithersWorkflow.ts

@@ -0,0 +1,13 @@
+import type React from "react";
+import type { SmithersCtx } from "./SmithersCtx";
+import type { SmithersWorkflowOptions } from "./SmithersWorkflowOptions";
+import type { SchemaRegistryEntry } from "./SchemaRegistryEntry";
+
+export type SmithersWorkflow<Schema> = {
+  db: unknown;
+  build: (ctx: SmithersCtx<Schema>) => React.ReactElement;
+  opts: SmithersWorkflowOptions;
+  schemaRegistry?: Map<string, SchemaRegistryEntry>;
+  /** Reverse lookup: ZodObject reference → schema key name */
+  zodToKeyName?: Map<import("zod").ZodObject<any>, string>;
+};

package/src/SmithersWorkflowOptions.ts

@@ -0,0 +1,3 @@
+export type SmithersWorkflowOptions = {
+  cache?: boolean;
+};

package/src/TaskDescriptor.ts

@@ -0,0 +1,28 @@
+import type { AgentLike } from "./AgentLike";
+
+export type TaskDescriptor = {
+  nodeId: string;
+  ordinal: number;
+  iteration: number;
+  ralphId?: string;
+  worktreeId?: string;
+  worktreePath?: string;
+  outputTable: any | null;
+  outputTableName: string;
+  outputSchema?: import("zod").ZodObject<any>;
+  parallelGroupId?: string;
+  parallelMaxConcurrency?: number;
+  needsApproval: boolean;
+  skipIf: boolean;
+  retries: number;
+  timeoutMs: number | null;
+  continueOnFail: boolean;
+  agent?: AgentLike;
+  /** Fallback agent used on retry when the primary agent fails (e.g. rate-limited). */
+  fallbackAgent?: AgentLike;
+  prompt?: string;
+  staticPayload?: unknown;
+  computeFn?: () => unknown | Promise<unknown>;
+  label?: string;
+  meta?: Record<string, unknown>;
+};

package/src/XmlNode.ts

@@ -0,0 +1,13 @@
+export type XmlNode = XmlElement | XmlText;
+
+export type XmlElement = {
+  kind: "element";
+  tag: string;
+  props: Record<string, string>;
+  children: XmlNode[];
+};
+
+export type XmlText = {
+  kind: "text";
+  text: string;
+};