pipeai 0.1.0 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@ The library is ~1000 lines across 4 files. It's designed to be read, understood,
 | Primitive      | Purpose                                                                                              |
 | -------------- | ---------------------------------------------------------------------------------------------------- |
 | `Agent`        | A pure AI SDK wrapper. Supports `generate()`, `stream()`, `asTool()`, and `asToolProvider()`. |
-| `Workflow`     | A typed pipeline that chains agents with `step()`, `branch()`, `foreach()`, `repeat()`, `catch()`, and `finally()`. |
+| `Workflow`     | A typed pipeline that chains agents with `step()`, `branch()`, `foreach()`, `repeat()`, `gate()`, `catch()`, and `finally()`. |
 | `defineTool`   | A context-aware tool factory — injects runtime context into tool `execute` calls.                     |
 
 ## Installation
@@ -117,15 +117,17 @@ const agent = new Agent<Ctx>({
 
 ### AI SDK callbacks
 
-Same callback names as AI SDK v6, extended with `ctx` and `input`. The AI SDK event payload is available as `result`:
+Same callback names as AI SDK v6, extended with `ctx`, `input`, and `writer`. The AI SDK event payload is available as `result`. When the agent runs inside a streaming workflow, `writer` is available for writing metadata or custom stream parts:
 
 ```ts
 const agent = new Agent<Ctx>({
   id: "monitored",
   model: openai("gpt-4o"),
   prompt: (ctx, input) => input,
-  onStepFinish: ({ result, ctx }) => {
+  onStepFinish: ({ result, ctx, writer }) => {
     console.log(`Step done, used ${result.usage.totalTokens} tokens`);
+    // Stream progress metadata to the client
+    writer?.write({ type: "metadata", value: { tokensUsed: result.usage.totalTokens } });
   },
   onFinish: ({ result, ctx }) => {
     console.log(`Total: ${result.totalUsage.totalTokens} tokens`);
@@ -152,9 +154,9 @@ const agent = new Agent<Ctx>({
 | `activeTools` | `Resolvable`              | Subset of tool names to enable.                                   |
 | `toolChoice`  | `Resolvable`              | Tool choice strategy. Static or `(ctx, input) => toolChoice`.     |
 | `stopWhen`    | `Resolvable`              | Condition for stopping the tool loop. Static or `(ctx, input) => condition`. |
-| `onStepFinish`| `({ result, ctx, input })`| Called after each step.                                           |
-| `onFinish`    | `({ result, ctx, input })`| Called when all steps complete.                                   |
-| `onError`     | `({ error, ctx, input })` | Called on error.                                                  |
+| `onStepFinish`| `({ result, ctx, input, writer? })`| Called after each step. `writer` available in streaming workflows. |
+| `onFinish`    | `({ result, ctx, input, writer? })`| Called when all steps complete.                                   |
+| `onError`     | `({ error, ctx, input, writer? })` | Called on error.                                                  |
 | `...`         | AI SDK options            | All other `streamText`/`generateText` options pass through (e.g. `temperature`, `maxTokens`, `maxRetries`, `headers`, `prepareStep`, `onChunk`, etc.). |
 
 ## `asTool()` — Agent as Tool
@@ -212,7 +214,7 @@ codingAgent.asTool(ctx, {
 });
 ```
 
-**Note:** `asTool()` uses `generate()` internally — sub-agent execution is non-streaming. This is an AI SDK tool loop constraint. For streaming multi-agent workflows, use `step()` with `branch()` instead.
+**Automatic streaming:** When `asTool()` is used inside a streaming workflow, sub-agents automatically use `stream()` and merge their output to the parent's stream — the user sees sub-agent responses in real-time. Outside of a streaming context (standalone use or generate mode), `asTool()` falls back to `generate()`. This is handled invisibly — no configuration needed.
 
 ## `asToolProvider()` — Deferred Context
 
@@ -236,11 +238,10 @@ This is useful when the agent is defined at module scope but the context isn't a
 
 ## defineTool — Context-Aware Tools
 
-`defineTool` wraps a tool definition so the agent's runtime context is injected into every `execute` call. The `input` field maps to AI SDK's `parameters`:
+`defineTool` wraps a tool definition so the agent's runtime context is injected into every `execute` call. The `input` field maps to AI SDK's `parameters`. When running inside a streaming workflow, the `writer` is automatically available in the third parameter for streaming metadata or progress updates to the client:
 
 ```ts
 import { defineTool } from "pipeai";
-import { tool } from "ai";
 
 type Ctx = { db: Database; userId: string };
 
@@ -249,8 +250,11 @@ const define = defineTool<Ctx>();
 const searchOrders = define({
   description: "Search user orders",
   input: z.object({ query: z.string() }),
-  execute: async ({ query }, ctx) => {
-    return ctx.db.orders.search(ctx.userId, query);
+  execute: async ({ query }, ctx, { writer }) => {
+    writer?.write({ type: "metadata", value: { status: "searching" } });
+    const results = await ctx.db.orders.search(ctx.userId, query);
+    writer?.write({ type: "metadata", value: { status: "done", count: results.length } });
+    return results;
   },
 });
 
@@ -271,6 +275,8 @@ const agent = new Agent<Ctx>({
 });
 ```
 
+The `writer` is `undefined` when running in generate mode or standalone — `?.` handles both cases naturally.
+
 ## Workflow
 
 A `Workflow` chains agents and transformation steps into a typed pipeline. Context is read-only — agents communicate through outputs.
@@ -313,6 +319,7 @@ Workflows can be passed as steps into other workflows. The nested workflow's ste
 // A reusable sub-workflow
 const classifyAndRoute = Workflow.create<Ctx>()
   .step(classifier, {
+    // Suppress the classifier's stream — only route the result
     handleStream: async ({ result }) => { await result.text; },
   })
   .branch({
@@ -402,7 +409,10 @@ const pipeline = Workflow.create<Ctx>()
     // Called during workflow.stream() — StreamTextResult (async access)
     mapStreamResult: async ({ result }) => ({
       text: await result.text,
-      files: [],
+      files: (await result.steps)
+        .flatMap(s => s.toolResults)
+        .filter(tr => tr.toolName === "writeFile")
+        .map(tr => tr.args.path),
     }),
   });
 ```
@@ -423,10 +433,11 @@ const pipeline = Workflow.create<Ctx>()
       });
     },
     // Called during workflow.stream()
-    onStreamResult: async ({ result, ctx, input }) => {
+    onStreamResult: async ({ result, ctx }) => {
       await ctx.db.conversations.save(ctx.userId, {
         role: "assistant",
         content: await result.text,
+        toolCalls: await result.toolCalls,
       });
     },
   });
@@ -434,7 +445,7 @@ const pipeline = Workflow.create<Ctx>()
 
 ### Fine-grained stream control
 
-Override how each agent's stream is merged into the workflow stream. By default, every agent's output is merged into the workflow stream via `writer.merge(result.toUIMessageStream())`. Use `handleStream` to change this — for example, to suppress intermediate agents so only the final response streams to the client:
+Override how each agent's stream is merged into the workflow stream. By default, every agent's output is merged via `writer.merge(result.toUIMessageStream())`. Use `handleStream` to take control — the callback receives `{ result, writer, ctx }`:
 
 ```ts
 const pipeline = Workflow.create<Ctx>()
@@ -442,14 +453,16 @@ const pipeline = Workflow.create<Ctx>()
   // the structured classification output, only the final response
   .step(classifier, {
     handleStream: async ({ result }) => {
-      await result.text; // consume the stream without forwarding it
+      await result.text; // consume without forwarding to the client
     },
   })
-  .branch({
-    select: ({ input }) => input.agent,
-    agents: { bug: bugAgent, feature: featureAgent, question: questionAgent },
+  // Custom merging — e.g. add metadata annotations to the stream
+  .step(supportAgent, {
+    handleStream: async ({ result, writer, ctx }) => {
+      writer.write({ type: "metadata", value: { agentId: "support", userId: ctx.userId } });
+      writer.merge(result.toUIMessageStream());
+    },
   });
-  // Only the selected agent's response streams to the client
 ```
 
 ### Array iteration via `foreach()`
@@ -485,7 +498,9 @@ const processItem = Workflow.create<Ctx, string>()
   .step(analyzeAgent)
   .step(enrichAgent);
 
-pipeline.foreach(processItem, { concurrency: 5 });
+const pipeline = Workflow.create<Ctx>()
+  .step("fetch-items", async ({ ctx }) => ctx.db.items.getAll())
+  .foreach(processItem, { concurrency: 5 });
 ```
 
 **Type safety:** `foreach()` uses `ElementOf<TOutput>` to extract the array element type. If the previous step doesn't produce an array, the call is rejected at compile time.
@@ -581,6 +596,7 @@ const { stream, output } = pipeline.stream(ctx, initialInput, {
 | `.branch({ select, agents })` | Key routing. `select` returns a key, runs the matching agent.          |
 | `.foreach(target, opts?)` | Map each array element through an agent or workflow. `opts.concurrency` controls parallelism (default: 1). |
 | `.repeat(target, opts)`   | Loop an agent or workflow. Use `{ until }` or `{ while }` (mutually exclusive). `maxIterations` defaults to 10. |
+| `.gate(id, opts?)`        | Human-in-the-loop suspension point. Throws `WorkflowSuspended` with a serializable snapshot. Resume via `loadState(gateId, snapshot)`. |
 | `.catch(id, fn)`          | Handle errors. `fn` receives `{ error, ctx, lastOutput, stepId }` and returns a recovery value. |
 | `.finally(id, fn)`        | Always runs. `fn` receives `{ ctx }`.                                      |
 
@@ -603,6 +619,191 @@ Auto-extraction priority for `step()` with an agent:
 | `foreach()`          | Deterministic         | Items don't stream     | Process each element of an array through an agent or workflow |
 | `repeat()`           | Condition function    | Each iteration streams | Iterative refinement until a quality threshold is met |
 
+## Human-in-the-Loop via `gate()`
+
+`gate()` suspends a workflow at a designated point, producing a JSON-serializable snapshot. The consumer persists the snapshot, collects human input out-of-band (HTTP, WebSocket, CLI, queue — any transport), then resumes the workflow from where it left off.
+
+### Basic gate
+
+```ts
+import { Workflow, WorkflowSuspended } from "pipeai";
+
+const pipeline = Workflow.create<Ctx>()
+  .step(draftAgent)
+  .gate("review", {
+    payload: ({ input }) => ({ draft: input, instructions: "Please review this draft" }),
+  })
+  .step(publishAgent);
+
+// Run — suspends at gate
+try {
+  await pipeline.generate(ctx, input);
+} catch (e) {
+  if (e instanceof WorkflowSuspended) {
+    await db.saveSnapshot(e.snapshot);
+    return res.status(202).json(e.snapshot.gatePayload);
+  }
+}
+
+// Resume — load state, pass gate ID + snapshot to generate or stream
+const snapshot = await db.loadSnapshot(id);
+const resumed = pipeline.loadState("review", snapshot);
+const { output } = await resumed.generate(ctx, humanResponse);
+```
+
+The `snapshot` is plain JSON — it survives `JSON.parse(JSON.stringify())`, database storage, and process restarts. The workflow definition (code) stays in the process; only the data is serialized.
+
+### Resuming with streaming
+
+For chat applications where the client reconnects and needs a live stream for the remaining steps:
+
+```ts
+const resumed = pipeline.loadState("review", snapshot);
+const { stream, output } = resumed.stream(ctx, humanResponse);
+return new Response(stream);
+```
+
+The previous stream is gone — the library only streams forward from the resume point. Load prior chat history from your database and send it to the client before piping the resume stream.
+
+### Streaming suspension
+
+When `stream()` hits a gate, the stream closes cleanly (partial content from steps before the gate is delivered). The `output` promise rejects with `WorkflowSuspended`:
+
+```ts
+const { stream, output } = pipeline.stream(ctx, input);
+pipeStreamToResponse(res, stream); // partial content delivered normally
+
+try {
+  await output;
+} catch (e) {
+  if (e instanceof WorkflowSuspended) {
+    await db.saveSnapshot(e.snapshot);
+  }
+}
+```
+
+### Schema validation
+
+Add a `schema` to validate the human response at runtime. The schema uses a structural type — any object with a `.parse()` method works (Zod, Valibot, ArkType, etc.):
+
+```ts
+const pipeline = Workflow.create<Ctx>()
+  .step(draftAgent)
+  .gate("review", {
+    schema: z.object({ approved: z.boolean(), notes: z.string() }),
+  })
+  .step("publish", ({ input }) => {
+    if (!input.approved) return "Rejected";
+    return `Published with notes: ${input.notes}`;
+  });
+
+// Resume — gate ID enables type inference, schema validates at runtime
+const resumed = pipeline.loadState("review", snapshot);
+await resumed.generate(ctx, { approved: true, notes: "lgtm" }); // passes
+await resumed.generate(ctx, { approved: "yes" });                // throws parse error
+```
+
+### Multiple gates
+
+A workflow can have multiple gates. Each `generate()`/`stream()` call advances to the next gate or completes:
+
+```ts
+const pipeline = Workflow.create<Ctx>()
+  .step(draftAgent)
+  .gate("review")
+  .step("process", ({ input }) => `reviewed: ${input}`)
+  .gate("final-approval")
+  .step("publish", ({ input }) => `published: ${input}`);
+
+// First gate
+let snapshot: WorkflowSnapshot;
+try { await pipeline.generate(ctx, input); }
+catch (e) { snapshot = (e as WorkflowSuspended).snapshot; }
+
+// Second gate
+const resumed1 = pipeline.loadState("review", snapshot);
+try { await resumed1.generate(ctx, "first approval"); }
+catch (e) { snapshot = (e as WorkflowSuspended).snapshot; }
+
+// Complete
+const resumed2 = pipeline.loadState("final-approval", snapshot);
+const { output } = await resumed2.generate(ctx, "final approval");
+```
+
+### Merging pre-gate output with response
+
+The `snapshot.output` field contains the pre-gate output. Use it to merge with the human response:
+
+```ts
+// The step after the gate needs both the draft and the approval
+const resumed = pipeline.loadState("review", snapshot);
+await resumed.generate(ctx, {
+  draft: snapshot.output,       // pre-gate output
+  approval: humanResponse,      // human's response
+});
+```
+
+### Injecting updated context on resume
+
+`ctx` is provided fresh on every `generate()`/`stream()` call — never serialized. Use it to inject updated chat history, refreshed auth tokens, or new database connections:
+
+```ts
+const freshCtx = {
+  chatHistory: await db.loadChatHistory(userId), // includes messages added during the pause
+  db: getDbConnection(),
+  userId,
+};
+const resumed = pipeline.loadState("review", snapshot);
+await resumed.stream(freshCtx, humanResponse);
+```
+
+### Conditional gates
+
+Use `condition` to make a gate fire only when a predicate returns `true`. When the condition returns `false`, the gate is skipped and the current output passes through unchanged:
+
+```ts
+const pipeline = Workflow.create<Ctx>()
+  .step(draftAgent)
+  .gate("review", {
+    condition: ({ input }) => input.needsReview,
+  })
+  .step(publishAgent);
+```
+
+### Merging pre-gate output with response
+
+Use `merge` to combine the pre-gate output with the human response into a single value for the next step. Without `merge`, only the human response is forwarded:
+
+```ts
+const pipeline = Workflow.create<Ctx>()
+  .step(draftAgent)
+  .gate("review", {
+    merge: ({ priorOutput, response }) => ({
+      draft: priorOutput,
+      approval: response,
+    }),
+  })
+  .step("publish", ({ input }) => {
+    // input is { draft, approval }
+  });
+```
+
+### Snapshot shape
+
+```ts
+interface WorkflowSnapshot {
+  version: 1;
+  resumeFromIndex: number;  // step index of the gate
+  output: unknown;          // pre-gate output
+  gateId: string;           // gate identifier
+  gatePayload: unknown;     // data for the human
+}
+```
+
+### Limitations
+
+Gates inside nested workflows, `foreach()`, and `repeat()` are not yet supported — a descriptive error is thrown at runtime. Gates at the top level of a workflow work in all cases.
+
 ## Full Example
 
 ```ts
@@ -671,11 +872,9 @@ const questionAgent = new Agent<Ctx>({
 
 // 4. Compose workflow
 const pipeline = Workflow.create<Ctx>()
-  // Classify silently — don't stream the structured JSON to the client
+  // Classify silently — consume the stream without forwarding to client
   .step(classifier, {
-    handleStream: async ({ result }) => {
-      await result.text;
-    },
+    handleStream: async ({ result }) => { await result.text; },
   })
   // Route to the right specialist based on classification
   .branch({