@rudderjs/ai 1.11.2 → 1.13.0

package/dist/agent-run-store.d.ts

@@ -0,0 +1,161 @@
+import type { AiMessage, ToolCall } from './types.js';
+/**
+ * Discriminator for the kind of pause a standalone run is parked on.
+ * Mirrors {@link SubAgentPauseKind} — the two run-store families share a
+ * vocabulary so a host can persist sub-agent and top-level pauses the same way.
+ *
+ * - `'client_tool'` — the run surfaced one or more client tools; resume must
+ *   carry one tool-result per id in `pendingToolCallIds`. The default when the
+ *   field is absent (older snapshots stay readable after an upgrade).
+ * - `'approval'` — the run stopped on an approval gate; resume must carry an
+ *   approve/reject decision covering the single id in `pendingToolCallIds`.
+ */
+export type AgentPauseKind = 'client_tool' | 'approval';
+/**
+ * Snapshot of a paused **standalone** (top-level) agent run — the state a host
+ * persists between an `agent.stream()` that parks on a client tool or approval
+ * gate and the follow-up request that resumes it.
+ *
+ * This is the standalone sibling of {@link SubAgentRunSnapshot}: same idea, but
+ * for a top-level `stream()` rather than an `Agent.asTool` sub-run. The shape is
+ * intentionally replay-ready — `messages` is the full conversation up to the
+ * pause point, so resume only appends the incoming client-tool results (or
+ * injects the approval decision) and re-enters `stream()` in `messages` mode.
+ */
+export interface AgentRunState {
+    /** Full conversation history at suspend time (system + user + every interleaved assistant/tool message). */
+    messages: AiMessage[];
+    /**
+     * Tool-call ids the run is waiting on.
+     *
+     * - `pauseKind === 'client_tool'` (default): one entry per client tool the
+     *   loop surfaced; resume appends one result per id.
+     * - `pauseKind === 'approval'`: a single entry for the approval-gated tool
+     *   call; resume injects the id into the approve or reject set.
+     */
+    pendingToolCallIds: string[];
+    /** Total steps the run has executed across all suspends so far. */
+    stepsSoFar: number;
+    /** Total prompt+completion tokens accumulated across all suspends. */
+    tokensSoFar: number;
+    /**
+     * Discriminator for the resume contract. Defaults to `'client_tool'` when
+     * absent so snapshots written before approval-pause support stay readable.
+     */
+    pauseKind?: AgentPauseKind;
+    /**
+     * Approval pauses only. The full pending tool-call payload (name + args + id)
+     * so a renderer can show "approve `delete_user(id=42)`?" without re-running
+     * the agent. Mirrors `AgentResponse.pendingApprovalToolCall`.
+     */
+    pendingApprovalToolCall?: {
+        toolCall: ToolCall;
+        isClientTool: boolean;
+    };
+    /**
+     * Opaque metadata the host can pass through. The framework treats this as
+     * JSON and never reads it — useful for rehydrating request context
+     * (e.g. `{ userId, threadId, agentSlug }`) around the resume call.
+     */
+    meta?: unknown;
+}
+/**
+ * Pluggable persistence backend for paused standalone agent runs. The framework
+ * ships two reference implementations:
+ *
+ * - {@link InMemoryAgentRunStore} — a `Map`-backed store. Single-process only;
+ *   fine for unit tests and small dev setups, lossy across worker processes and
+ *   restarts.
+ * - {@link CachedAgentRunStore} — lazy adapter on top of `@rudderjs/cache`.
+ *   Cross-process / cross-restart when the cache is configured with redis or any
+ *   non-memory driver.
+ *
+ * Hosts may implement their own (Redis directly, Prisma, etc.) by satisfying
+ * this interface.
+ *
+ * The split between {@link load} (non-destructive peek) and {@link consume}
+ * (atomic single-use read+delete) matters: a host can `load()` to render a
+ * "waiting for approval" view on a GET without burning the run, then `consume()`
+ * on the resume POST so a forged or replayed `runId` cannot read data twice.
+ */
+export interface AgentRunStore {
+    /** Persist a snapshot under `runId`. Implementations MAY apply a TTL. */
+    store(runId: string, state: AgentRunState): Promise<void>;
+    /**
+     * Non-destructive read. Returns `null` if the id is unknown or the snapshot
+     * has expired. Leaves the snapshot in place — use for read-only peeks
+     * (rendering a pending-run view); use {@link consume} when resuming.
+     */
+    load(runId: string): Promise<AgentRunState | null>;
+    /**
+     * Atomic read + delete. Returns `null` if the id is unknown or the snapshot
+     * has expired. Single-use semantics matter: a forged or replayed `runId` must
+     * not return data twice.
+     */
+    consume(runId: string): Promise<AgentRunState | null>;
+}
+/**
+ * Generate a fresh, hard-to-guess run id. Uses `crypto.randomUUID()` where the
+ * runtime exposes it (Node ≥ 16.7, every modern browser, Deno, Bun), falling
+ * back to a timestamp + random suffix. Run ids are unguessable on purpose — a
+ * `runId` is a capability handle to a parked conversation, so a predictable id
+ * would let a third party `consume()` someone else's run.
+ */
+export declare function newAgentRunId(): string;
+/**
+ * `Map`-backed implementation suitable for tests and single-process dev.
+ * Loses state across restarts and worker processes — for any multi-worker
+ * deployment, use {@link CachedAgentRunStore} or a custom backend.
+ */
+export declare class InMemoryAgentRunStore implements AgentRunStore {
+    private readonly states;
+    store(runId: string, state: AgentRunState): Promise<void>;
+    load(runId: string): Promise<AgentRunState | null>;
+    consume(runId: string): Promise<AgentRunState | null>;
+    /** Test helper — clears all snapshots without consuming. */
+    clear(): void;
+}
+/**
+ * Minimal structural shape of a cache adapter (the methods this store touches).
+ * Mirrors `@rudderjs/cache`'s `CacheAdapter` so the dep stays structural — the
+ * framework's main entry stays runtime-agnostic.
+ */
+interface CacheStoreLike {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    forget(key: string): Promise<void>;
+}
+export interface CachedAgentRunStoreOptions {
+    /**
+     * Cache adapter to use. When omitted, the store loads `@rudderjs/cache`
+     * lazily and falls back to the registered global adapter
+     * (`CacheRegistry.get()`); throws if neither resolves.
+     */
+    cache?: CacheStoreLike;
+    /** Key namespace prefix. Default `'rudderjs:ai:agent-run:'`. */
+    keyPrefix?: string;
+    /** Time-to-live in seconds. Default 5 minutes. */
+    ttlSeconds?: number;
+}
+/**
+ * Standalone agent run store backed by `@rudderjs/cache`. Loads the cache
+ * adapter lazily so `@rudderjs/ai`'s main entry stays runtime-agnostic (no
+ * static import on the cache package).
+ *
+ * Default TTL is 5 minutes — long enough for a browser to round-trip a few
+ * client tool calls or an approval decision, short enough that abandoned runs
+ * garbage-collect promptly and the storage bill stays bounded.
+ */
+export declare class CachedAgentRunStore implements AgentRunStore {
+    private readonly explicitCache?;
+    private readonly keyPrefix;
+    private readonly ttlSeconds;
+    private resolvedCache?;
+    constructor(opts?: CachedAgentRunStoreOptions);
+    private getCache;
+    store(runId: string, state: AgentRunState): Promise<void>;
+    load(runId: string): Promise<AgentRunState | null>;
+    consume(runId: string): Promise<AgentRunState | null>;
+}
+export {};
+//# sourceMappingURL=agent-run-store.d.ts.map

package/dist/agent-run-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-run-store.d.ts","sourceRoot":"","sources":["../src/agent-run-store.ts"],"names":[],"mappings":"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"}

package/dist/agent-run-store.js

@@ -0,0 +1,98 @@
+/**
+ * Generate a fresh, hard-to-guess run id. Uses `crypto.randomUUID()` where the
+ * runtime exposes it (Node ≥ 16.7, every modern browser, Deno, Bun), falling
+ * back to a timestamp + random suffix. Run ids are unguessable on purpose — a
+ * `runId` is a capability handle to a parked conversation, so a predictable id
+ * would let a third party `consume()` someone else's run.
+ */
+export function newAgentRunId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    return `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+// ─── In-memory ─────────────────────────────────────────────
+/**
+ * `Map`-backed implementation suitable for tests and single-process dev.
+ * Loses state across restarts and worker processes — for any multi-worker
+ * deployment, use {@link CachedAgentRunStore} or a custom backend.
+ */
+export class InMemoryAgentRunStore {
+    states = new Map();
+    async store(runId, state) {
+        this.states.set(runId, state);
+    }
+    async load(runId) {
+        return this.states.get(runId) ?? null;
+    }
+    async consume(runId) {
+        const state = this.states.get(runId);
+        if (!state)
+            return null;
+        this.states.delete(runId);
+        return state;
+    }
+    /** Test helper — clears all snapshots without consuming. */
+    clear() {
+        this.states.clear();
+    }
+}
+/**
+ * Standalone agent run store backed by `@rudderjs/cache`. Loads the cache
+ * adapter lazily so `@rudderjs/ai`'s main entry stays runtime-agnostic (no
+ * static import on the cache package).
+ *
+ * Default TTL is 5 minutes — long enough for a browser to round-trip a few
+ * client tool calls or an approval decision, short enough that abandoned runs
+ * garbage-collect promptly and the storage bill stays bounded.
+ */
+export class CachedAgentRunStore {
+    explicitCache;
+    keyPrefix;
+    ttlSeconds;
+    resolvedCache;
+    constructor(opts = {}) {
+        if (opts.cache)
+            this.explicitCache = opts.cache;
+        this.keyPrefix = opts.keyPrefix ?? 'rudderjs:ai:agent-run:';
+        this.ttlSeconds = opts.ttlSeconds ?? 5 * 60;
+    }
+    async getCache() {
+        if (this.resolvedCache)
+            return this.resolvedCache;
+        if (this.explicitCache) {
+            this.resolvedCache = this.explicitCache;
+            return this.resolvedCache;
+        }
+        // Lazy-import @rudderjs/cache and ask the registry for the active adapter.
+        // This keeps the static import surface zero — the import only fires when the
+        // host actually opts into suspendable standalone runs. We dodge static
+        // module-resolution by using an indirected specifier so `@rudderjs/cache`
+        // doesn't need to be a declared dep of `@rudderjs/ai` (optional runtime peer).
+        const cacheSpecifier = '@rudderjs/cache';
+        const mod = await import(/* @vite-ignore */ cacheSpecifier);
+        const adapter = mod.CacheRegistry?.get?.();
+        if (!adapter) {
+            throw new Error('[RudderJS AI] CachedAgentRunStore needs a cache adapter. Install `@rudderjs/cache`, register a driver, or pass `{ cache }` explicitly.');
+        }
+        this.resolvedCache = adapter;
+        return adapter;
+    }
+    async store(runId, state) {
+        const cache = await this.getCache();
+        await cache.set(this.keyPrefix + runId, state, this.ttlSeconds);
+    }
+    async load(runId) {
+        const cache = await this.getCache();
+        return (await cache.get(this.keyPrefix + runId)) ?? null;
+    }
+    async consume(runId) {
+        const cache = await this.getCache();
+        const key = this.keyPrefix + runId;
+        const state = await cache.get(key);
+        if (!state)
+            return null;
+        await cache.forget(key);
+        return state;
+    }
+}
+//# sourceMappingURL=agent-run-store.js.map

package/dist/agent-run-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-run-store.js","sourceRoot":"","sources":["../src/agent-run-store.ts"],"names":[],"mappings":"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"}

package/dist/agent.d.ts

@@ -9,6 +9,146 @@ import type { AgentPromptOptions, AiMessage, AiMiddleware, AgentResponse, AgentS
 export declare function stepCountIs(n: number): StopCondition;
 /** Stop when a specific tool is called in the latest step */
 export declare function hasToolCall(toolName: string): StopCondition;
+/** Options for {@link Agent.resumeAsTool}. */
+export interface SubAgentResumeOptions {
+    /** Shared run store the snapshot lives in. */
+    runStore: SubAgentRunStore;
+    /** The sub-agent instance to resume. */
+    agent: Agent;
+    /** Approved ids for an `approval` pause. */
+    approvedToolCallIds?: string[];
+    /** Rejected ids for an `approval` pause. */
+    rejectedToolCallIds?: string[];
+    /**
+     * Opt-in live progress during the resume. When set, the resumed inner loop
+     * runs via `stream()` instead of `prompt()` and each chunk is projected into
+     * a {@link SubAgentUpdate} forwarded to {@link onUpdate}. `true` uses
+     * {@link defaultSubAgentProjector} (emits `tool_call` / `agent_pending_approval`);
+     * a function is your own projector. Mirrors {@link Agent.asTool}'s `streaming`
+     * on the initial-dispatch path. Unset → the legacy non-streaming `prompt()`
+     * resume (no behavior change). The pause/completion partition is identical
+     * either way — this only adds a progress channel.
+     */
+    streaming?: AsToolStreamingOption;
+    /**
+     * Sink for projected updates. Only fires when {@link streaming} is set, once
+     * per non-null projection, in stream order. Awaited, so a slow sink applies
+     * backpressure to the resume.
+     */
+    onUpdate?: (update: SubAgentUpdate) => void | Promise<void>;
+}
+/**
+ * One entry in a {@link Agent.resumeManyAsTool} batch — a single paused
+ * sub-agent to resume. Mirrors the positional args of the singular
+ * {@link Agent.resumeAsTool}, plus an optional host `key` echoed back on the
+ * matching outcome so callers can correlate results without relying on array
+ * order.
+ */
+export interface SubAgentResumeRequest {
+    /** The paused run's id (the `subRunId` from its pause chunk/snapshot). */
+    subRunId: string;
+    /** The sub-agent instance to resume (each item may be a different agent). */
+    agent: Agent;
+    /** Client tool-results for a `client_tool` pause (one per pending id). */
+    clientToolResults?: ReadonlyArray<{
+        toolCallId: string;
+        result: unknown;
+    }>;
+    /** Approved ids for an `approval` pause. */
+    approvedToolCallIds?: string[];
+    /** Rejected ids for an `approval` pause. */
+    rejectedToolCallIds?: string[];
+    /** Opaque correlation key echoed back on this item's outcome. */
+    key?: string;
+}
+/** Outcome for a single item in a {@link Agent.resumeManyAsTool} batch. */
+export type SubAgentResumeOutcome = {
+    key?: string;
+    originalSubRunId: string;
+    kind: 'completed';
+    response: AgentResponse;
+} | {
+    key?: string;
+    originalSubRunId: string;
+    kind: 'paused';
+    subRunId: string;
+    pauseKind: SubAgentPauseKind;
+    pendingToolCallIds: string[];
+    toolCall?: ToolCall;
+    isClientTool?: boolean;
+} | {
+    key?: string;
+    originalSubRunId: string;
+    kind: 'error';
+    error: Error;
+};
+export interface SubAgentResumeManyOptions {
+    /** Shared run store all the snapshots live in. */
+    runStore: SubAgentRunStore;
+    /**
+     * What to do when one item fails (expired/forged `subRunId`, duplicate
+     * result id, inner error):
+     * - `'capture'` (default) — record it as a `{ kind: 'error' }` outcome and
+     *   let the rest of the batch resume; the aggregated round-trip still
+     *   returns.
+     * - `'throw'` — reject the whole call on the first failure, matching the
+     *   singular `resumeAsTool` strictness.
+     */
+    onError?: 'capture' | 'throw';
+    /**
+     * - `'parallel'` (default) — resume all snapshots concurrently. Snapshots
+     *   are independent and `consume()` is per-id atomic, so this is safe and
+     *   fastest.
+     * - `'serial'` — resume one at a time in array order, for deterministic
+     *   side-effect ordering when sub-agents touch shared state.
+     */
+    concurrency?: 'parallel' | 'serial';
+    /**
+     * Shared live-progress projector applied to every resumed item — same option
+     * as {@link SubAgentResumeOptions.streaming}. Unset → every item resumes
+     * non-streaming (legacy behavior). Set → each item streams and its projected
+     * updates flow to {@link onUpdate} tagged with the originating request.
+     */
+    streaming?: AsToolStreamingOption;
+    /**
+     * Sink for projected updates across the whole batch. Only fires when
+     * {@link streaming} is set. Each call carries the originating item's `key`
+     * (when supplied) and `originalSubRunId`, so a host can correlate a chunk
+     * back to its request and fan it out (e.g. to a per-sub-agent SSE channel).
+     */
+    onUpdate?: (update: SubAgentUpdate, ctx: {
+        key?: string;
+        originalSubRunId: string;
+    }) => void | Promise<void>;
+}
+/** Aggregated result of a {@link Agent.resumeManyAsTool} batch. */
+export interface SubAgentResumeManyResult {
+    /** Every item's outcome, in input order. */
+    results: SubAgentResumeOutcome[];
+    /** The items that paused again (need another client round-trip). */
+    paused: Extract<SubAgentResumeOutcome, {
+        kind: 'paused';
+    }>[];
+    /** The items that ran to completion. */
+    completed: Extract<SubAgentResumeOutcome, {
+        kind: 'completed';
+    }>[];
+    /** The items that failed (only populated under `onError: 'capture'`). */
+    errors: Extract<SubAgentResumeOutcome, {
+        kind: 'error';
+    }>[];
+    /**
+     * All pending tool-call ids across every paused item, flattened — the
+     * single set the host gathers client results / approvals for before the
+     * next `resumeManyAsTool`. Empty when nothing paused.
+     */
+    pendingToolCallIds: string[];
+    /**
+     * `true` when nothing is still paused and no item errored — i.e. there is
+     * no further round-trip to do. Loop `resumeManyAsTool` until this is `true`.
+     */
+    allCompleted: boolean;
+}
 export declare abstract class Agent {
     /** System instructions for this agent */
     abstract instructions(): string;
@@ -204,12 +344,7 @@ export declare abstract class Agent {
     static resumeAsTool(subRunId: string, clientToolResults: ReadonlyArray<{
         toolCallId: string;
         result: unknown;
-    }>, options: {
-        runStore: SubAgentRunStore;
-        agent: Agent;
-        approvedToolCallIds?: string[];
-        rejectedToolCallIds?: string[];
-    }): Promise<{
+    }>, options: SubAgentResumeOptions): Promise<{
         kind: 'completed';
         response: AgentResponse;
     } | {
@@ -220,9 +355,43 @@ export declare abstract class Agent {
         toolCall?: ToolCall;
         isClientTool?: boolean;
     }>;
+    /**
+     * Resume MANY paused sub-agents in one call and aggregate their pending
+     * tool calls into a single client round-trip.
+     *
+     * When an orchestrator dispatches several sub-agents in one parent turn
+     * and more than one pauses on a client tool (or approval gate), the host
+     * would otherwise loop over {@link Agent.resumeAsTool} by hand and stitch
+     * the pending sets back together. This does that: each request resumes its
+     * own `(subRunId, agent)` snapshot, and the result carries the combined
+     * `completed` / `paused` / `errors` partition plus the flattened
+     * `pendingToolCallIds` the host collects the next batch of results for.
+     *
+     * Re-entrant: feed the next round of `clientToolResults` / approvals back
+     * in as a fresh batch keyed off each paused item's NEW `subRunId` until
+     * `allCompleted` is `true`.
+     *
+     * @example
+     * let batch = await Agent.resumeManyAsTool(
+     *   paused.map(p => ({ subRunId: p.subRunId, agent: p.agent, clientToolResults: results[p.subRunId] })),
+     *   { runStore },
+     * )
+     * // batch.pendingToolCallIds → gather the next round from the browser, repeat.
+     */
+    static resumeManyAsTool(requests: ReadonlyArray<SubAgentResumeRequest>, options: SubAgentResumeManyOptions): Promise<SubAgentResumeManyResult>;
 }
-type ChunkProjector = (chunk: StreamChunk) => SubAgentUpdate | null;
-type AsToolStreamingOption = boolean | ChunkProjector;
+/**
+ * Projects an inner-agent {@link StreamChunk} into a {@link SubAgentUpdate} the
+ * host can render, or `null` to suppress it. Used by both {@link Agent.asTool}
+ * (`streaming`) and the streaming resume path ({@link SubAgentResumeOptions.streaming}).
+ */
+export type ChunkProjector = (chunk: StreamChunk) => SubAgentUpdate | null;
+/**
+ * Live-progress option shared by {@link Agent.asTool} and the streaming resume
+ * surface: `true` uses {@link defaultSubAgentProjector}; a function is your own
+ * {@link ChunkProjector}.
+ */
+export type AsToolStreamingOption = boolean | ChunkProjector;
 type AsToolSuspendableOption = {
     runStore: SubAgentRunStore;
 };

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -360,7 +360,25 @@ export class Agent {
                 promptOpts.rejectedToolCallIds = rejected;
         }
         promptOpts.messages = messages;
-        const result = await options.agent.prompt('', promptOpts);
+        // Default path: non-streaming resume — one prompt() call, one response.
+        // Opt-in streaming path: run the inner loop via stream() and forward each
+        // projected chunk to onUpdate, so a host can keep a resumed sub-agent's
+        // progress live across the round-trip. Either way `result` is the same
+        // AgentResponse and the pause/completion partition below is unchanged.
+        let result;
+        if (options.streaming) {
+            const project = options.streaming === true ? defaultSubAgentProjector : options.streaming;
+            const { stream, response } = options.agent.stream('', promptOpts);
+            for await (const chunk of stream) {
+                const update = project(chunk);
+                if (update && options.onUpdate)
+                    await options.onUpdate(update);
+            }
+            result = await response;
+        }
+        else {
+            result = await options.agent.prompt('', promptOpts);
+        }
         if (result.finishReason === 'client_tool_calls' &&
             result.pendingClientToolCalls?.length) {
             const newSubRunId = generateSubRunId();
@@ -405,6 +423,87 @@ export class Agent {
         }
         return { kind: 'completed', response: result };
     }
+    /**
+     * Resume MANY paused sub-agents in one call and aggregate their pending
+     * tool calls into a single client round-trip.
+     *
+     * When an orchestrator dispatches several sub-agents in one parent turn
+     * and more than one pauses on a client tool (or approval gate), the host
+     * would otherwise loop over {@link Agent.resumeAsTool} by hand and stitch
+     * the pending sets back together. This does that: each request resumes its
+     * own `(subRunId, agent)` snapshot, and the result carries the combined
+     * `completed` / `paused` / `errors` partition plus the flattened
+     * `pendingToolCallIds` the host collects the next batch of results for.
+     *
+     * Re-entrant: feed the next round of `clientToolResults` / approvals back
+     * in as a fresh batch keyed off each paused item's NEW `subRunId` until
+     * `allCompleted` is `true`.
+     *
+     * @example
+     * let batch = await Agent.resumeManyAsTool(
+     *   paused.map(p => ({ subRunId: p.subRunId, agent: p.agent, clientToolResults: results[p.subRunId] })),
+     *   { runStore },
+     * )
+     * // batch.pendingToolCallIds → gather the next round from the browser, repeat.
+     */
+    static async resumeManyAsTool(requests, options) {
+        const onError = options.onError ?? 'capture';
+        const concurrency = options.concurrency ?? 'parallel';
+        const runOne = async (req) => {
+            const base = { originalSubRunId: req.subRunId, ...(req.key !== undefined ? { key: req.key } : {}) };
+            try {
+                const opts = { runStore: options.runStore, agent: req.agent };
+                if (req.approvedToolCallIds)
+                    opts.approvedToolCallIds = req.approvedToolCallIds;
+                if (req.rejectedToolCallIds)
+                    opts.rejectedToolCallIds = req.rejectedToolCallIds;
+                // Thread the shared projector + correlate each update back to this item.
+                if (options.streaming !== undefined)
+                    opts.streaming = options.streaming;
+                if (options.onUpdate) {
+                    const batchOnUpdate = options.onUpdate;
+                    opts.onUpdate = (update) => batchOnUpdate(update, base);
+                }
+                const r = await Agent.resumeAsTool(req.subRunId, req.clientToolResults ?? [], opts);
+                if (r.kind === 'completed')
+                    return { ...base, kind: 'completed', response: r.response };
+                return {
+                    ...base,
+                    kind: 'paused',
+                    subRunId: r.subRunId,
+                    pauseKind: r.pauseKind,
+                    pendingToolCallIds: r.pendingToolCallIds,
+                    ...(r.toolCall !== undefined ? { toolCall: r.toolCall } : {}),
+                    ...(r.isClientTool !== undefined ? { isClientTool: r.isClientTool } : {}),
+                };
+            }
+            catch (err) {
+                if (onError === 'throw')
+                    throw err;
+                return { ...base, kind: 'error', error: err instanceof Error ? err : new Error(String(err)) };
+            }
+        };
+        let results;
+        if (concurrency === 'serial') {
+            results = [];
+            for (const req of requests)
+                results.push(await runOne(req));
+        }
+        else {
+            results = await Promise.all(requests.map(runOne));
+        }
+        const paused = results.filter((o) => o.kind === 'paused');
+        const completed = results.filter((o) => o.kind === 'completed');
+        const errors = results.filter((o) => o.kind === 'error');
+        return {
+            results,
+            paused,
+            completed,
+            errors,
+            pendingToolCallIds: paused.flatMap((p) => p.pendingToolCallIds),
+            allCompleted: paused.length === 0 && errors.length === 0,
+        };
+    }
 }
 /**
  * Default projection from inner-agent stream chunks to {@link SubAgentUpdate}