pipeai 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -5,11 +5,12 @@ declare const TOOL_PROVIDER_BRAND: unique symbol;
 type ToolExecuteOptions = ToolExecutionOptions & {
     writer?: UIMessageStreamWriter;
 };
+type ToolProviderOptions = NonNullable<Tool["providerOptions"]>;
 type ToolProviderConfig<TContext, TInput, TOutput> = {
     description?: string;
     input: FlexibleSchema<TInput>;
-    output?: FlexibleSchema<unknown>;
-    providerOptions?: unknown;
+    outputSchema?: FlexibleSchema<TOutput>;
+    providerOptions?: ToolProviderOptions;
     execute: (input: TInput, ctx: Readonly<TContext>, options: ToolExecuteOptions) => Promise<TOutput>;
 };
 interface IToolProvider<TContext> {
@@ -85,13 +86,13 @@ declare class Agent<TContext, TInput = void, TOutput = void> {
     private readonly _onStepFinish;
     private readonly _onFinish;
     constructor(config: AgentConfig<TContext, TInput, TOutput>);
-    generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<GenerateTextResult>;
-    stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<StreamTextResult>;
+    generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<GenerateTextResult<ToolSet, OutputType<TOutput>>>;
+    stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<StreamTextResult<ToolSet, OutputType<TOutput>>>;
     asTool(ctx: TContext, options?: {
-        mapOutput?: (result: GenerateTextResult) => MaybePromise<TOutput>;
+        mapOutput?: (result: GenerateTextResult<ToolSet, OutputType<TOutput>>) => MaybePromise<TOutput>;
     }): Tool;
     asToolProvider(options?: {
-        mapOutput?: (result: GenerateTextResult) => MaybePromise<TOutput>;
+        mapOutput?: (result: GenerateTextResult<ToolSet, OutputType<TOutput>>) => MaybePromise<TOutput>;
     }): IToolProvider<TContext>;
     private createToolInstance;
     private buildCallOptions;
@@ -109,29 +110,40 @@ declare class WorkflowLoopError extends Error {
     readonly maxIterations: number;
     constructor(iterations: number, maxIterations: number);
 }
+interface WorkflowSnapshot {
+    readonly version: 1;
+    readonly resumeFromIndex: number;
+    readonly output: unknown;
+    readonly gateId: string;
+    readonly gatePayload: unknown;
+}
+declare class WorkflowSuspended extends Error {
+    readonly snapshot: WorkflowSnapshot;
+    constructor(snapshot: WorkflowSnapshot);
+}
 interface AgentStepHooks<TContext, TOutput, TNextOutput> {
     mapGenerateResult?: (params: {
-        result: GenerateTextResult;
+        result: GenerateTextResult<ToolSet, OutputType<TNextOutput>>;
         ctx: Readonly<TContext>;
         input: TOutput;
     }) => MaybePromise<TNextOutput>;
     mapStreamResult?: (params: {
-        result: StreamTextResult;
+        result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
         ctx: Readonly<TContext>;
         input: TOutput;
     }) => MaybePromise<TNextOutput>;
     onGenerateResult?: (params: {
-        result: GenerateTextResult;
+        result: GenerateTextResult<ToolSet, OutputType<TNextOutput>>;
         ctx: Readonly<TContext>;
         input: TOutput;
     }) => MaybePromise<void>;
     onStreamResult?: (params: {
-        result: StreamTextResult;
+        result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
         ctx: Readonly<TContext>;
         input: TOutput;
     }) => MaybePromise<void>;
     handleStream?: (params: {
-        result: StreamTextResult;
+        result: StreamTextResult<ToolSet, OutputType<TNextOutput>>;
         writer: UIMessageStreamWriter;
         ctx: Readonly<TContext>;
     }) => MaybePromise<void>;
@@ -178,6 +190,9 @@ type RepeatOptions<TContext, TOutput> = {
     maxIterations?: number;
 };
 type ElementOf<T> = T extends readonly (infer E)[] ? E : never;
+interface SchemaWithParse<T = unknown> {
+    parse(data: unknown): T;
+}
 type StepNode = {
     readonly type: "step";
     readonly id: string;
@@ -195,6 +210,16 @@ type StepNode = {
     readonly type: "finally";
     readonly id: string;
     readonly execute: (state: RuntimeState) => MaybePromise<void>;
+} | {
+    readonly type: "gate";
+    readonly id: string;
+    readonly payload: (state: RuntimeState) => MaybePromise<unknown>;
+    readonly schema?: SchemaWithParse;
+    readonly condition?: (state: RuntimeState) => MaybePromise<boolean>;
+    readonly merge?: (params: {
+        priorOutput: unknown;
+        response: unknown;
+    }) => MaybePromise<unknown>;
 };
 interface RuntimeState {
     ctx: unknown;
@@ -202,45 +227,76 @@ interface RuntimeState {
     mode: "generate" | "stream";
     writer?: UIMessageStreamWriter;
 }
-declare class SealedWorkflow<TContext, TInput = void, TOutput = void> {
+declare class SealedWorkflow<TContext, TInput = void, TOutput = void, TGates extends Record<string, unknown> = {}> {
     readonly id?: string;
     protected readonly steps: ReadonlyArray<StepNode>;
     protected constructor(steps: ReadonlyArray<StepNode>, id?: string);
     generate(ctx: TContext, ...args: TInput extends void ? [input?: TInput] : [input: TInput]): Promise<WorkflowResult<TOutput>>;
     stream(ctx: TContext, ...args: TInput extends void ? [input?: TInput, options?: WorkflowStreamOptions] : [input: TInput, options?: WorkflowStreamOptions]): WorkflowStreamResult<TOutput>;
-    protected execute(state: RuntimeState): Promise<void>;
-    protected executeNestedWorkflow(state: RuntimeState, workflow: SealedWorkflow<TContext, unknown, unknown>): Promise<void>;
+    protected execute(state: RuntimeState, startIndex?: number): Promise<void>;
+    protected executeNestedWorkflow(state: RuntimeState, workflow: SealedWorkflow<TContext, unknown, unknown, any>): Promise<void>;
     protected executeAgent<TAgentInput, TNextOutput>(state: RuntimeState, agent: Agent<TContext, any, TNextOutput>, ctx: TContext, options?: AgentStepHooks<TContext, any, TNextOutput>): Promise<void>;
+    loadState<K extends string & keyof TGates>(gateId: K, snapshot: WorkflowSnapshot): ResumedWorkflow<TContext, TGates[K], TOutput>;
+    private findGateIndex;
+}
+declare class ResumedWorkflow<TContext, TResponse = unknown, TOutput = void> extends SealedWorkflow<TContext, TResponse, TOutput> {
+    private readonly startIndex;
+    private readonly schema?;
+    private readonly mergeFn?;
+    private readonly priorOutput;
+    /** @internal */
+    constructor(steps: ReadonlyArray<StepNode>, startIndex: number, schema?: SchemaWithParse<TResponse>, mergeFn?: (params: {
+        priorOutput: unknown;
+        response: unknown;
+    }) => MaybePromise<unknown>, priorOutput?: unknown);
+    private validateResponse;
+    generate(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse] : [response: TResponse]): Promise<WorkflowResult<TOutput>>;
+    stream(ctx: TContext, ...args: TResponse extends void ? [response?: TResponse, options?: WorkflowStreamOptions] : [response: TResponse, options?: WorkflowStreamOptions]): WorkflowStreamResult<TOutput>;
 }
-declare class Workflow<TContext, TInput = void, TOutput = void> extends SealedWorkflow<TContext, TInput, TOutput> {
+declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends Record<string, unknown> = {}> extends SealedWorkflow<TContext, TInput, TOutput, TGates> {
     private constructor();
     static create<TContext, TInput = void>(options?: {
         id?: string;
     }): Workflow<TContext, TInput, TInput>;
     static from<TContext, TInput, TOutput>(agent: Agent<TContext, TInput, TOutput>, options?: StepOptions<TContext, TInput, TOutput>): Workflow<TContext, TInput, TOutput>;
-    step<TNextOutput>(agent: Agent<TContext, TOutput, TNextOutput>, options?: StepOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput>;
-    step<TNextOutput>(workflow: SealedWorkflow<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput>;
+    step<TNextOutput>(agent: Agent<TContext, TOutput, TNextOutput>, options?: StepOptions<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
+    step<TNextOutput>(workflow: SealedWorkflow<TContext, TOutput, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
     step<TNextOutput>(id: string, fn: (params: {
         ctx: Readonly<TContext>;
         input: TOutput;
-    }) => MaybePromise<TNextOutput>): Workflow<TContext, TInput, TNextOutput>;
-    branch<TNextOutput>(cases: BranchCase<TContext, TOutput, TNextOutput>[]): Workflow<TContext, TInput, TNextOutput>;
-    branch<TKeys extends string, TNextOutput>(config: BranchSelect<TContext, TOutput, TKeys, TNextOutput>): Workflow<TContext, TInput, TNextOutput>;
+    }) => MaybePromise<TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
+    gate<TResponse = TOutput, Id extends string = string>(id: Id & (Id extends keyof TGates ? never : Id), options?: {
+        payload?: (params: {
+            ctx: Readonly<TContext>;
+            input: TOutput;
+        }) => MaybePromise<unknown>;
+        schema?: SchemaWithParse<TResponse>;
+        condition?: (params: {
+            ctx: Readonly<TContext>;
+            input: TOutput;
+        }) => MaybePromise<boolean>;
+        merge?: (params: {
+            priorOutput: TOutput;
+            response: TResponse;
+        }) => MaybePromise<TResponse>;
+    }): Workflow<TContext, TInput, TResponse, TGates & Record<Id, TResponse>>;
+    branch<TNextOutput>(cases: BranchCase<TContext, TOutput, TNextOutput>[]): Workflow<TContext, TInput, TNextOutput, TGates>;
+    branch<TKeys extends string, TNextOutput>(config: BranchSelect<TContext, TOutput, TKeys, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
     private branchPredicate;
     private branchSelect;
     foreach<TNextOutput>(target: Agent<TContext, ElementOf<TOutput>, TNextOutput> | SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput>, options?: {
         concurrency?: number;
-    }): Workflow<TContext, TInput, TNextOutput[]>;
-    repeat(target: Agent<TContext, TOutput, TOutput> | SealedWorkflow<TContext, TOutput, TOutput>, options: RepeatOptions<TContext, TOutput>): Workflow<TContext, TInput, TOutput>;
+    }): Workflow<TContext, TInput, TNextOutput[], TGates>;
+    repeat(target: Agent<TContext, TOutput, TOutput> | SealedWorkflow<TContext, TOutput, TOutput>, options: RepeatOptions<TContext, TOutput>): Workflow<TContext, TInput, TOutput, TGates>;
     catch(id: string, fn: (params: {
         error: unknown;
         ctx: Readonly<TContext>;
         lastOutput: TOutput;
         stepId: string;
-    }) => MaybePromise<TOutput>): Workflow<TContext, TInput, TOutput>;
+    }) => MaybePromise<TOutput>): Workflow<TContext, TInput, TOutput, TGates>;
     finally(id: string, fn: (params: {
         ctx: Readonly<TContext>;
-    }) => MaybePromise<void>): SealedWorkflow<TContext, TInput, TOutput>;
+    }) => MaybePromise<void>): SealedWorkflow<TContext, TInput, TOutput, TGates>;
 }
 
-export { Agent, type AgentConfig, type AgentStepHooks, type BranchCase, type BranchSelect, type GenerateTextResult, type IToolProvider, type MaybePromise, type RepeatOptions, type Resolvable, SealedWorkflow, type StepOptions, type StreamTextResult, type ToolExecuteOptions, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowResult, type WorkflowStreamOptions, type WorkflowStreamResult, defineTool };
+export { Agent, type AgentConfig, type AgentStepHooks, type BranchCase, type BranchSelect, type GenerateTextResult, type IToolProvider, type MaybePromise, type OutputType, type RepeatOptions, type Resolvable, ResumedWorkflow, SealedWorkflow, type StepOptions, type StreamTextResult, type ToolExecuteOptions, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowResult, type WorkflowSnapshot, type WorkflowStreamOptions, type WorkflowStreamResult, WorkflowSuspended, defineTool };

package/dist/index.js

@@ -43,9 +43,8 @@ var ToolProvider = class {
     const { execute, input: inputSchema, ...toolDef } = this.config;
     return tool({
       ...toolDef,
-      parameters: inputSchema,
+      inputSchema,
       execute: (input, options) => execute(input, context, { ...options, writer: getActiveWriter() })
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
     });
   }
 };
@@ -152,7 +151,7 @@ var Agent = class {
     }
     return tool2({
       description: this.description,
-      parameters: this.config.input,
+      inputSchema: this.config.input,
       execute: async (toolInput) => {
         const writer = getActiveWriter();
         if (writer) {
@@ -165,7 +164,8 @@ var Agent = class {
         if (options?.mapOutput) return options.mapOutput(result);
         return extractOutput(result, this.hasOutput);
       }
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      // TS cannot simplify the SDK's `NeverOptional<TOutput, ...>` conditional in a
+      // generic context, so we cast through `unknown` instead of `any`.
     });
   }
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -252,6 +252,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;
@@ -308,12 +316,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;
@@ -333,10 +342,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 };
       }
     }
@@ -346,7 +371,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.
@@ -385,6 +419,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 = 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) {
@@ -438,6 +572,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)) {
@@ -583,6 +743,7 @@ export {
   Workflow,
   WorkflowBranchError,
   WorkflowLoopError,
+  WorkflowSuspended,
   defineTool
 };
 //# sourceMappingURL=index.js.map