pipeai 0.1.1 → 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
@@ -596,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 }`.                                      |
 
@@ -618,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

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   Workflow: () => Workflow,
   WorkflowBranchError: () => WorkflowBranchError,
   WorkflowLoopError: () => WorkflowLoopError,
+  WorkflowSuspended: () => WorkflowSuspended,
   defineTool: () => defineTool
 });
 module.exports = __toCommonJS(index_exports);
@@ -276,6 +277,14 @@ var WorkflowLoopError = class extends Error {
     this.name = "WorkflowLoopError";
   }
 };
+var WorkflowSuspended = class extends Error {
+  snapshot;
+  constructor(snapshot) {
+    super(`Workflow suspended at gate "${snapshot.gateId}"`);
+    this.name = "WorkflowSuspended";
+    this.snapshot = snapshot;
+  }
+};
 var SealedWorkflow = class {
   id;
   steps;
@@ -332,12 +341,13 @@ var SealedWorkflow = class {
     };
   }
   // ── Internal: execute pipeline ────────────────────────────────
-  async execute(state) {
+  async execute(state, startIndex = 0) {
     if (this.steps.length === 0) {
       throw new Error("Workflow has no steps. Add at least one step before calling generate() or stream().");
     }
     let pendingError = null;
-    for (const node of this.steps) {
+    for (let i = startIndex; i < this.steps.length; i++) {
+      const node = this.steps[i];
       if (node.type === "finally") {
         await node.execute(state);
         continue;
@@ -357,10 +367,26 @@ var SealedWorkflow = class {
         }
         continue;
       }
+      if (node.type === "gate") {
+        if (pendingError) continue;
+        if (node.condition) {
+          const shouldSuspend = await node.condition(state);
+          if (!shouldSuspend) continue;
+        }
+        const gatePayload = await node.payload(state);
+        throw new WorkflowSuspended({
+          version: 1,
+          resumeFromIndex: i,
+          output: state.output,
+          gateId: node.id,
+          gatePayload
+        });
+      }
       if (pendingError) continue;
       try {
         await node.execute(state);
       } catch (error) {
+        if (error instanceof WorkflowSuspended) throw error;
         pendingError = { error, stepId: node.id };
       }
     }
@@ -370,7 +396,16 @@ var SealedWorkflow = class {
   // Defined on SealedWorkflow (not Workflow) because TypeScript's protected
   // access rules only allow calling workflow.execute() from the same class.
   async executeNestedWorkflow(state, workflow) {
-    await workflow.execute(state);
+    try {
+      await workflow.execute(state);
+    } catch (error) {
+      if (error instanceof WorkflowSuspended) {
+        throw new Error(
+          `Gates inside nested workflows are not yet supported. Gate "${error.snapshot.gateId}" was hit inside nested workflow "${workflow.id ?? "(anonymous)"}". Consider using a conditional gate with \`condition\` to skip when criteria are met, or restructure the workflow to use gates at the top level only.`
+        );
+      }
+      throw error;
+    }
   }
   // ── Internal: execute an agent within a step/branch ───────────
   // In stream mode, output extraction awaits the full stream before returning.
@@ -409,6 +444,106 @@ var SealedWorkflow = class {
       }
     }
   }
+  // ── Gate: load persisted state for resumption ──────────────────
+  loadState(gateId, snapshot) {
+    if (snapshot.gateId !== gateId) {
+      throw new Error(
+        `loadState: gate ID mismatch \u2014 expected "${gateId}" but snapshot has "${snapshot.gateId}".`
+      );
+    }
+    const gateIndex = this.findGateIndex(snapshot);
+    const gateNode = this.steps[gateIndex];
+    return new ResumedWorkflow(
+      this.steps,
+      gateIndex + 1,
+      gateNode.schema,
+      gateNode.merge,
+      snapshot.output
+    );
+  }
+  findGateIndex(snapshot) {
+    if (snapshot.version !== 1) {
+      throw new Error(`Unsupported snapshot version: ${snapshot.version}`);
+    }
+    const hint = snapshot.resumeFromIndex;
+    if (hint >= 0 && hint < this.steps.length) {
+      const node = this.steps[hint];
+      if (node.type === "gate" && node.id === snapshot.gateId) {
+        return hint;
+      }
+    }
+    for (let i = 0; i < this.steps.length; i++) {
+      const node = this.steps[i];
+      if (node.type === "gate" && node.id === snapshot.gateId) {
+        return i;
+      }
+    }
+    throw new Error(
+      `Gate "${snapshot.gateId}" not found in workflow. The workflow definition may have changed since the snapshot was created.`
+    );
+  }
+};
+var ResumedWorkflow = class extends SealedWorkflow {
+  startIndex;
+  schema;
+  mergeFn;
+  priorOutput;
+  /** @internal */
+  constructor(steps, startIndex, schema, mergeFn, priorOutput) {
+    super(steps);
+    this.startIndex = startIndex;
+    this.schema = schema;
+    this.mergeFn = mergeFn;
+    this.priorOutput = priorOutput;
+  }
+  validateResponse(response) {
+    if (this.schema) {
+      return this.schema.parse(response);
+    }
+    return response;
+  }
+  async generate(ctx, ...args) {
+    const response = this.validateResponse(args[0]);
+    const output = this.mergeFn ? await this.mergeFn({ priorOutput: this.priorOutput, response }) : response;
+    const state = { ctx, output, mode: "generate" };
+    await this.execute(state, this.startIndex);
+    return { output: state.output };
+  }
+  stream(ctx, ...args) {
+    const response = this.validateResponse(args[0]);
+    const options = args[1];
+    let resolveOutput;
+    let rejectOutput;
+    const outputPromise = new Promise((res, rej) => {
+      resolveOutput = res;
+      rejectOutput = rej;
+    });
+    outputPromise.catch(() => {
+    });
+    const mergeFn = this.mergeFn;
+    const priorOutput = this.priorOutput;
+    const stream = (0, import_ai3.createUIMessageStream)({
+      execute: async ({ writer }) => {
+        const output = mergeFn ? await mergeFn({ priorOutput, response }) : response;
+        const state = {
+          ctx,
+          output,
+          mode: "stream",
+          writer
+        };
+        try {
+          await this.execute(state, this.startIndex);
+          resolveOutput(state.output);
+        } catch (error) {
+          rejectOutput(error);
+          throw error;
+        }
+      },
+      ...options?.onError ? { onError: options.onError } : {},
+      ...options?.onFinish ? { onFinish: options.onFinish } : {}
+    });
+    return { stream, output: outputPromise };
+  }
 };
 var Workflow = class _Workflow extends SealedWorkflow {
   constructor(steps = [], id) {
@@ -462,6 +597,32 @@ var Workflow = class _Workflow extends SealedWorkflow {
     };
     return new _Workflow([...this.steps, node], this.id);
   }
+  // ── gate: human-in-the-loop suspension point ────────────────
+  gate(id, options) {
+    if (this.steps.some((s) => s.type === "gate" && s.id === id)) {
+      throw new Error(`Workflow: duplicate gate ID "${id}". Each gate must have a unique identifier.`);
+    }
+    const node = {
+      type: "gate",
+      id,
+      schema: options?.schema,
+      condition: options?.condition ? async (state) => options.condition({
+        ctx: state.ctx,
+        input: state.output
+      }) : void 0,
+      merge: options?.merge ? (params) => options.merge(params) : void 0,
+      payload: async (state) => {
+        if (options?.payload) {
+          return options.payload({
+            ctx: state.ctx,
+            input: state.output
+          });
+        }
+        return state.output;
+      }
+    };
+    return new _Workflow([...this.steps, node], this.id);
+  }
   // ── branch: implementation ────────────────────────────────────
   branch(casesOrConfig) {
     if (Array.isArray(casesOrConfig)) {
@@ -608,6 +769,7 @@ var Workflow = class _Workflow extends SealedWorkflow {
   Workflow,
   WorkflowBranchError,
   WorkflowLoopError,
+  WorkflowSuspended,
   defineTool
 });
 //# sourceMappingURL=index.cjs.map