pipeai 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -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;
@@ -122,27 +123,27 @@ declare class WorkflowSuspended extends Error {
 }
 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>;
@@ -253,6 +254,12 @@ declare class ResumedWorkflow<TContext, TResponse = unknown, TOutput = void> ext
     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, TGates extends Record<string, unknown> = {}> extends SealedWorkflow<TContext, TInput, TOutput, TGates> {
+    /**
+     * Sentinel value for `foreach`'s `onError` handler. Returning `Workflow.SKIP`
+     * from `onError` omits the failed item's index from the output array,
+     * shortening it relative to the input array.
+     */
+    static readonly SKIP: unique symbol;
     private constructor();
     static create<TContext, TInput = void>(options?: {
         id?: string;
@@ -283,8 +290,29 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
     branch<TKeys extends string, TNextOutput>(config: BranchSelect<TContext, TOutput, TKeys, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
     private branchPredicate;
     private branchSelect;
+    /**
+     * Map each item of an array through an agent or sub-workflow.
+     *
+     * @param target Agent or `SealedWorkflow` invoked once per item.
+     * @param options.concurrency Max items in flight at any moment (default 1).
+     *   Backed by a semaphore: as soon as one item completes, the next launches —
+     *   no lockstep batching.
+     * @param options.onError Per-iteration error handler. When provided, a single
+     *   item's failure no longer aborts the foreach. Return a `TNextOutput` value
+     *   to substitute for the failed item, return `Workflow.SKIP` to omit the
+     *   index (shortening the output array), or throw / return a rejected promise
+     *   to abort the foreach step (the thrown error is caught by any downstream
+     *   `.catch()`). When omitted, the existing fail-fast behavior is preserved.
+     *   `onError` is invoked sequentially in index order after all items settle.
+     */
     foreach<TNextOutput>(target: Agent<TContext, ElementOf<TOutput>, TNextOutput> | SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput>, options?: {
         concurrency?: number;
+        onError?: (params: {
+            error: unknown;
+            item: ElementOf<TOutput>;
+            index: number;
+            ctx: Readonly<TContext>;
+        }) => MaybePromise<TNextOutput | typeof Workflow.SKIP>;
     }): 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: {
@@ -298,4 +326,4 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
     }) => 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, ResumedWorkflow, SealedWorkflow, type StepOptions, type StreamTextResult, type ToolExecuteOptions, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowResult, type WorkflowSnapshot, type WorkflowStreamOptions, type WorkflowStreamResult, WorkflowSuspended, 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.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;
@@ -122,27 +123,27 @@ declare class WorkflowSuspended extends Error {
 }
 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>;
@@ -253,6 +254,12 @@ declare class ResumedWorkflow<TContext, TResponse = unknown, TOutput = void> ext
     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, TGates extends Record<string, unknown> = {}> extends SealedWorkflow<TContext, TInput, TOutput, TGates> {
+    /**
+     * Sentinel value for `foreach`'s `onError` handler. Returning `Workflow.SKIP`
+     * from `onError` omits the failed item's index from the output array,
+     * shortening it relative to the input array.
+     */
+    static readonly SKIP: unique symbol;
     private constructor();
     static create<TContext, TInput = void>(options?: {
         id?: string;
@@ -283,8 +290,29 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
     branch<TKeys extends string, TNextOutput>(config: BranchSelect<TContext, TOutput, TKeys, TNextOutput>): Workflow<TContext, TInput, TNextOutput, TGates>;
     private branchPredicate;
     private branchSelect;
+    /**
+     * Map each item of an array through an agent or sub-workflow.
+     *
+     * @param target Agent or `SealedWorkflow` invoked once per item.
+     * @param options.concurrency Max items in flight at any moment (default 1).
+     *   Backed by a semaphore: as soon as one item completes, the next launches —
+     *   no lockstep batching.
+     * @param options.onError Per-iteration error handler. When provided, a single
+     *   item's failure no longer aborts the foreach. Return a `TNextOutput` value
+     *   to substitute for the failed item, return `Workflow.SKIP` to omit the
+     *   index (shortening the output array), or throw / return a rejected promise
+     *   to abort the foreach step (the thrown error is caught by any downstream
+     *   `.catch()`). When omitted, the existing fail-fast behavior is preserved.
+     *   `onError` is invoked sequentially in index order after all items settle.
+     */
     foreach<TNextOutput>(target: Agent<TContext, ElementOf<TOutput>, TNextOutput> | SealedWorkflow<TContext, ElementOf<TOutput>, TNextOutput>, options?: {
         concurrency?: number;
+        onError?: (params: {
+            error: unknown;
+            item: ElementOf<TOutput>;
+            index: number;
+            ctx: Readonly<TContext>;
+        }) => MaybePromise<TNextOutput | typeof Workflow.SKIP>;
     }): 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: {
@@ -298,4 +326,4 @@ declare class Workflow<TContext, TInput = void, TOutput = void, TGates extends R
     }) => 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, ResumedWorkflow, SealedWorkflow, type StepOptions, type StreamTextResult, type ToolExecuteOptions, type ToolProviderConfig, Workflow, WorkflowBranchError, WorkflowLoopError, type WorkflowResult, type WorkflowSnapshot, type WorkflowStreamOptions, type WorkflowStreamResult, WorkflowSuspended, 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

@@ -23,6 +23,28 @@ function resolveValue(value, ctx, input) {
   }
   return value;
 }
+var Semaphore = class {
+  available;
+  waiters = [];
+  constructor(permits) {
+    if (!Number.isInteger(permits) || permits < 1) {
+      throw new Error(`Semaphore: permits must be a positive integer, got ${permits}`);
+    }
+    this.available = permits;
+  }
+  async acquire() {
+    if (this.available > 0) {
+      this.available--;
+      return;
+    }
+    await new Promise((resolve) => this.waiters.push(resolve));
+  }
+  release() {
+    const next = this.waiters.shift();
+    if (next) next();
+    else this.available++;
+  }
+};
 async function extractOutput(result, hasStructuredOutput) {
   if (hasStructuredOutput) {
     const output = await result.output;
@@ -43,9 +65,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 +173,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 +186,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
@@ -521,6 +543,12 @@ var ResumedWorkflow = class extends SealedWorkflow {
   }
 };
 var Workflow = class _Workflow extends SealedWorkflow {
+  /**
+   * Sentinel value for `foreach`'s `onError` handler. Returning `Workflow.SKIP`
+   * from `onError` omits the failed item's index from the output array,
+   * shortening it relative to the input array.
+   */
+  static SKIP = /* @__PURE__ */ Symbol("pipeai.foreach.skip");
   constructor(steps = [], id) {
     super(steps, id);
   }
@@ -647,8 +675,24 @@ var Workflow = class _Workflow extends SealedWorkflow {
     return new _Workflow([...this.steps, node], this.id);
   }
   // ── foreach: array iteration ─────────────────────────────────
+  /**
+   * Map each item of an array through an agent or sub-workflow.
+   *
+   * @param target Agent or `SealedWorkflow` invoked once per item.
+   * @param options.concurrency Max items in flight at any moment (default 1).
+   *   Backed by a semaphore: as soon as one item completes, the next launches —
+   *   no lockstep batching.
+   * @param options.onError Per-iteration error handler. When provided, a single
+   *   item's failure no longer aborts the foreach. Return a `TNextOutput` value
+   *   to substitute for the failed item, return `Workflow.SKIP` to omit the
+   *   index (shortening the output array), or throw / return a rejected promise
+   *   to abort the foreach step (the thrown error is caught by any downstream
+   *   `.catch()`). When omitted, the existing fail-fast behavior is preserved.
+   *   `onError` is invoked sequentially in index order after all items settle.
+   */
   foreach(target, options) {
     const concurrency = options?.concurrency ?? 1;
+    const onError = options?.onError;
     const isWorkflow = target instanceof SealedWorkflow;
     const id = isWorkflow ? target.id ?? "foreach" : `foreach:${target.id}`;
     const node = {
@@ -661,6 +705,7 @@ var Workflow = class _Workflow extends SealedWorkflow {
         }
         const ctx = state.ctx;
         const results = new Array(items.length);
+        const skipped = /* @__PURE__ */ new Set();
         const executeItem = async (item, index) => {
           const itemState = { ctx: state.ctx, output: item, mode: "generate" };
           if (isWorkflow) {
@@ -670,17 +715,47 @@ var Workflow = class _Workflow extends SealedWorkflow {
           }
           results[index] = itemState.output;
         };
+        const handleRejection = async (error, item, index) => {
+          if (!onError) throw error;
+          const recovered = await onError({
+            error,
+            item,
+            index,
+            ctx: state.ctx
+          });
+          if (recovered === _Workflow.SKIP) {
+            skipped.add(index);
+          } else {
+            results[index] = recovered;
+          }
+        };
         if (concurrency <= 1) {
           for (let i = 0; i < items.length; i++) {
-            await executeItem(items[i], i);
+            try {
+              await executeItem(items[i], i);
+            } catch (error) {
+              await handleRejection(error, items[i], i);
+            }
           }
         } else {
-          for (let i = 0; i < items.length; i += concurrency) {
-            const batch = items.slice(i, i + concurrency);
-            await Promise.all(batch.map((item, j) => executeItem(item, i + j)));
+          const sem = new Semaphore(concurrency);
+          const failures = [];
+          await Promise.all(items.map(async (item, i) => {
+            await sem.acquire();
+            try {
+              await executeItem(item, i);
+            } catch (error) {
+              failures.push({ index: i, error });
+            } finally {
+              sem.release();
+            }
+          }));
+          failures.sort((a, b) => a.index - b.index);
+          for (const { index, error } of failures) {
+            await handleRejection(error, items[index], index);
           }
         }
-        state.output = results;
+        state.output = skipped.size === 0 ? results : results.filter((_, i) => !skipped.has(i));
       }
     };
     return new _Workflow([...this.steps, node], this.id);