@rudderjs/ai 1.4.0 → 1.5.0

package/dist/agent.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { AiRegistry } from './registry.js';
-import { isPauseForClientToolsChunk, pauseForClientTools, toolDefinition, toolToSchema } from './tool.js';
+import { isPauseForApprovalChunk, isPauseForClientToolsChunk, pauseForApproval, pauseForClientTools, toolDefinition, toolToSchema } from './tool.js';
+import { isHandoffTool } from './handoff.js';
 import { attachmentsToContentParts, getMessageText } from './attachment.js';
 import { QueuedPromptBuilder } from './queue-job.js';
 import { resolveAutoPersistSpec, runWithPersistence, runWithPersistenceStreaming, } from './conversation-persistence.js';
@@ -184,6 +185,7 @@ export class Agent {
                     pendingToolCallIds: result.pendingClientToolCalls.map((tc) => tc.id),
                     stepsSoFar: result.steps.length,
                     tokensSoFar: result.usage?.totalTokens ?? 0,
+                    pauseKind: 'client_tool',
                 };
                 await suspendable.runStore.store(subRunId, snapshot);
                 yield { kind: 'subagent_paused', subRunId, pendingToolCallIds: snapshot.pendingToolCallIds };
@@ -191,6 +193,30 @@ export class Agent {
                 // Unreachable — the parent loop halts iteration after the pause chunk.
                 return undefined;
             }
+            if (suspendable &&
+                result.finishReason === 'tool_approval_required' &&
+                result.pendingApprovalToolCall) {
+                const subRunId = generateSubRunId();
+                const { toolCall: pendingCall, isClientTool } = result.pendingApprovalToolCall;
+                const snapshot = {
+                    messages: buildSubAgentSnapshotMessages(userPrompt, result),
+                    pendingToolCallIds: [pendingCall.id],
+                    stepsSoFar: result.steps.length,
+                    tokensSoFar: result.usage?.totalTokens ?? 0,
+                    pauseKind: 'approval',
+                    pendingApprovalToolCall: { toolCall: pendingCall, isClientTool },
+                };
+                await suspendable.runStore.store(subRunId, snapshot);
+                yield {
+                    kind: 'subagent_paused_approval',
+                    subRunId,
+                    toolCall: pendingCall,
+                    isClientTool,
+                };
+                yield pauseForApproval(pendingCall, isClientTool, subRunId);
+                // Unreachable — the parent loop halts iteration after the pause chunk.
+                return undefined;
+            }
             yield {
                 kind: 'agent_done',
                 steps: result.steps.length,
@@ -207,54 +233,96 @@ export class Agent {
             .modelOutput(modelOutput);
     }
     /**
-     * Resume a sub-agent run that previously paused with
-     * `pauseForClientTools` (typically from {@link Agent.asTool} with
-     * `suspendable: { runStore }` set). Loads the snapshot, validates the
-     * incoming tool-result ids against the pending set, and re-runs the
-     * inner loop with those results appended.
+     * Resume a sub-agent run that previously paused with either
+     * `pauseForClientTools` (client-tool pause) or `pauseForApproval`
+     * (approval pause), typically from {@link Agent.asTool} with
+     * `suspendable: { runStore }` set. The snapshot's `pauseKind`
+     * (default `'client_tool'`) selects the resume contract:
      *
-     * Returns either a `'completed'` result (the inner agent finished) or
+     * - **`client_tool`** — `clientToolResults` must carry one entry per
+     *   id in the snapshot's `pendingToolCallIds`. Results are appended
+     *   to the inner-agent message history and the loop re-runs.
+     * - **`approval`** — `approvedToolCallIds` and/or
+     *   `rejectedToolCallIds` must reference the single pending id.
+     *   `clientToolResults` must be empty; the loop re-runs with the
+     *   approval decision injected via `AgentPromptOptions`.
+     *
+     * Returns either a `'completed'` result (the inner agent finished),
      * a `'paused'` continuation pointing at a fresh `subRunId` for the
-     * next round-trip.
+     * next round-trip, or stays `'paused'` if the inner loop hits another
+     * gate. The resume can pause on a different kind than it started on
+     * (e.g. an approval pause that, once approved, hits a client-tool
+     * pause on the next step).
      *
-     * @example
+     * @example  Client-tool resume
      * const r = await Agent.resumeAsTool(subRunId, browserResults, { runStore, agent: subAgent })
-     * if (r.kind === 'completed') {
-     *   feedToolResultBackToParent(r.response.text)
-     * } else {
-     *   emitPendingClientToolsSse(r.subRunId, r.pendingToolCallIds)
-     * }
+     *
+     * @example  Approval resume
+     * const r = await Agent.resumeAsTool(subRunId, [], {
+     *   runStore, agent: subAgent,
+     *   approvedToolCallIds: ['inner-call-id'],
+     * })
      */
     static async resumeAsTool(subRunId, clientToolResults, options) {
         const snapshot = await options.runStore.consume(subRunId);
         if (!snapshot) {
             throw new Error(`[RudderJS AI] resumeAsTool: subRunId "${subRunId}" expired or never existed.`);
         }
-        // Forgery guard — every incoming tool-result id must be in the pending set.
+        const pauseKind = snapshot.pauseKind ?? 'client_tool';
         const pending = new Set(snapshot.pendingToolCallIds);
-        const seen = new Set();
-        for (const r of clientToolResults) {
-            if (!pending.has(r.toolCallId)) {
-                throw new Error(`[RudderJS AI] resumeAsTool: toolCallId "${r.toolCallId}" was not in the pending set.`);
+        let messages;
+        const promptOpts = { toolCallStreamingMode: 'stop-on-client-tool' };
+        if (pauseKind === 'client_tool') {
+            // Forgery guard — every incoming tool-result id must be in the pending set.
+            const seen = new Set();
+            for (const r of clientToolResults) {
+                if (!pending.has(r.toolCallId)) {
+                    throw new Error(`[RudderJS AI] resumeAsTool: toolCallId "${r.toolCallId}" was not in the pending set.`);
+                }
+                if (seen.has(r.toolCallId)) {
+                    throw new Error(`[RudderJS AI] resumeAsTool: duplicate result for toolCallId "${r.toolCallId}".`);
+                }
+                seen.add(r.toolCallId);
             }
-            if (seen.has(r.toolCallId)) {
-                throw new Error(`[RudderJS AI] resumeAsTool: duplicate result for toolCallId "${r.toolCallId}".`);
+            // Append client tool-result messages to the snapshot, in incoming order.
+            messages = [...snapshot.messages];
+            for (const r of clientToolResults) {
+                messages.push({
+                    role: 'tool',
+                    content: typeof r.result === 'string' ? r.result : JSON.stringify(r.result),
+                    toolCallId: r.toolCallId,
+                });
             }
-            seen.add(r.toolCallId);
-        }
-        // Append client tool-result messages to the snapshot, in incoming order.
-        const messages = [...snapshot.messages];
-        for (const r of clientToolResults) {
-            messages.push({
-                role: 'tool',
-                content: typeof r.result === 'string' ? r.result : JSON.stringify(r.result),
-                toolCallId: r.toolCallId,
-            });
-        }
-        const result = await options.agent.prompt('', {
-            messages,
-            toolCallStreamingMode: 'stop-on-client-tool',
-        });
+        }
+        else {
+            // Approval-pause resume — clientToolResults must be empty; either an
+            // approval or a rejection must be supplied for the pending id.
+            if (clientToolResults.length > 0) {
+                throw new Error('[RudderJS AI] resumeAsTool: snapshot.pauseKind === "approval" but clientToolResults was non-empty. Pass `approvedToolCallIds` or `rejectedToolCallIds` instead.');
+            }
+            const approved = options.approvedToolCallIds ?? [];
+            const rejected = options.rejectedToolCallIds ?? [];
+            for (const id of approved) {
+                if (!pending.has(id)) {
+                    throw new Error(`[RudderJS AI] resumeAsTool: approvedToolCallId "${id}" was not in the pending set.`);
+                }
+            }
+            for (const id of rejected) {
+                if (!pending.has(id)) {
+                    throw new Error(`[RudderJS AI] resumeAsTool: rejectedToolCallId "${id}" was not in the pending set.`);
+                }
+            }
+            if (approved.length === 0 && rejected.length === 0) {
+                throw new Error('[RudderJS AI] resumeAsTool: snapshot.pauseKind === "approval" requires `approvedToolCallIds` or `rejectedToolCallIds`.');
+            }
+            messages = [...snapshot.messages];
+            if (approved.length > 0)
+                promptOpts.approvedToolCallIds = approved;
+            if (rejected.length > 0)
+                promptOpts.rejectedToolCallIds = rejected;
+        }
+        promptOpts.messages = messages;
+        const result = await options.agent.prompt('', promptOpts);
         if (result.finishReason === 'client_tool_calls' &&
             result.pendingClientToolCalls?.length) {
             const newSubRunId = generateSubRunId();
@@ -263,23 +331,50 @@ export class Agent {
                 pendingToolCallIds: result.pendingClientToolCalls.map((tc) => tc.id),
                 stepsSoFar: snapshot.stepsSoFar + result.steps.length,
                 tokensSoFar: snapshot.tokensSoFar + (result.usage?.totalTokens ?? 0),
+                pauseKind: 'client_tool',
                 ...(snapshot.meta !== undefined ? { meta: snapshot.meta } : {}),
             };
             await options.runStore.store(newSubRunId, newSnapshot);
             return {
                 kind: 'paused',
                 subRunId: newSubRunId,
+                pauseKind: 'client_tool',
                 pendingToolCallIds: newSnapshot.pendingToolCallIds,
             };
         }
+        if (result.finishReason === 'tool_approval_required' &&
+            result.pendingApprovalToolCall) {
+            const newSubRunId = generateSubRunId();
+            const { toolCall: pendingCall, isClientTool } = result.pendingApprovalToolCall;
+            const newSnapshot = {
+                messages: buildResumeSnapshotMessages(messages, result),
+                pendingToolCallIds: [pendingCall.id],
+                stepsSoFar: snapshot.stepsSoFar + result.steps.length,
+                tokensSoFar: snapshot.tokensSoFar + (result.usage?.totalTokens ?? 0),
+                pauseKind: 'approval',
+                pendingApprovalToolCall: { toolCall: pendingCall, isClientTool },
+                ...(snapshot.meta !== undefined ? { meta: snapshot.meta } : {}),
+            };
+            await options.runStore.store(newSubRunId, newSnapshot);
+            return {
+                kind: 'paused',
+                subRunId: newSubRunId,
+                pauseKind: 'approval',
+                pendingToolCallIds: newSnapshot.pendingToolCallIds,
+                toolCall: pendingCall,
+                isClientTool,
+            };
+        }
         return { kind: 'completed', response: result };
     }
 }
 /**
  * Default projection from inner-agent stream chunks to {@link SubAgentUpdate}
- * events. Emits one `tool_call` per inner `tool-call` chunk; everything
+ * events. Emits one `tool_call` per inner `tool-call` chunk and
+ * `agent_pending_approval` per inner `pending-approval` chunk; everything
  * else is suppressed (the wrapping execute emits the `agent_start` /
- * `agent_done` bookends and the suspend path emits `subagent_paused`).
+ * `agent_done` bookends and the suspend paths emit `subagent_paused` /
+ * `subagent_paused_approval`).
  *
  * Hosts wanting different cadence (e.g. surfacing `text-delta` previews
  * or per-step usage) pass `streaming: chunk => …` and own the discriminator.
@@ -292,6 +387,13 @@ function defaultSubAgentProjector(chunk) {
             ...(chunk.toolCall.arguments ? { args: chunk.toolCall.arguments } : {}),
         };
     }
+    if (chunk.type === 'pending-approval' && chunk.toolCall && chunk.toolCall.id && chunk.toolCall.name) {
+        return {
+            kind: 'agent_pending_approval',
+            toolCall: chunk.toolCall,
+            isClientTool: !!chunk.isClientTool,
+        };
+    }
     return null;
 }
 /**
@@ -753,6 +855,12 @@ function buildAgentResponse(loopCtx) {
         result.pendingApprovalToolCall = loopCtx.pendingApprovalToolCall;
     if (loopCtx.resumedToolMessages.length > 0)
         result.resumedToolMessages = loopCtx.resumedToolMessages;
+    // Internal — consumed by the handoff-aware wrapper, then stripped before
+    // surfacing to public callers.
+    if (loopCtx.pendingHandoff) {
+        result._pendingHandoff = loopCtx.pendingHandoff;
+        result._carriedMessages = loopCtx.messages;
+    }
     return result;
 }
 /**
@@ -775,7 +883,15 @@ async function* executeToolPhase(loopCtx, toolCalls, assistantMessage) {
     // agent-level override which defaults to `true`. Single-tool batches
     // route through the serial path either way (no parallelism to gain, and
     // serial preserves live `tool-update` streaming for that one tool).
-    const parallel = (options?.parallelTools ?? loopCtx.agent.parallelTools()) && toolCalls.length > 1;
+    //
+    // Handoffs always force serial dispatch — the parent loop has to halt
+    // immediately on the first handoff and synthesize "skipped" results for
+    // any sibling calls. Handling that across the parallel classify/replay
+    // phases is doable but adds complexity for negligible benefit (the model
+    // rarely emits parallel siblings alongside a handoff, and even then,
+    // running them while the agent is being torn down is wasted work).
+    const hasHandoff = toolCalls.some(tc => isHandoffTool(loopCtx.toolMap.get(tc.name)));
+    const parallel = (options?.parallelTools ?? loopCtx.agent.parallelTools()) && toolCalls.length > 1 && !hasHandoff;
     if (parallel) {
         yield* runToolPhaseParallel(loopCtx, toolCalls, toolResults);
     }
@@ -804,6 +920,50 @@ async function* runToolPhaseSerial(loopCtx, toolCalls, toolResults) {
             yield { type: 'tool-result', toolCall: tc, result: unknownResult };
             continue;
         }
+        // Handoff — detected before the no-execute (client tool) branch because
+        // a handoff tool also has no `execute`, but it has wholly different
+        // semantics: pivot control to a new agent instead of pausing for the
+        // browser. The first handoff in a step wins; any subsequent tool calls
+        // in the same step are skipped with a synthetic "skipped: handed off"
+        // tool result so the message log stays well-formed for replay.
+        if (loopCtx.stopForHandoff) {
+            const skippedResult = 'Skipped: parent agent handed off to another agent.';
+            toolResults.push({ toolCallId: tc.id, result: skippedResult });
+            messages.push({ role: 'tool', content: skippedResult, toolCallId: tc.id });
+            yield { type: 'tool-call', toolCall: tc };
+            yield { type: 'tool-result', toolCall: tc, result: skippedResult };
+            continue;
+        }
+        if (isHandoffTool(tool)) {
+            const spec = tool.__handoffSpec;
+            const validation = validateToolArgs(tool, tc.arguments);
+            // Handoff payload defaults to `{ message: string }`; custom schemas
+            // are accepted but the loop only uses `args.message` (string) as the
+            // transition prompt. Anything else surfaces in the conversation as
+            // the args of the synthetic tool-call.
+            const args = validation.ok ? validation.value : tc.arguments;
+            const transitionMessage = typeof args['message'] === 'string' ? args['message'] : '';
+            const handoffResult = `Handed off to ${spec.AgentClass.name}.`;
+            toolResults.push({ toolCallId: tc.id, result: handoffResult });
+            messages.push({ role: 'tool', content: handoffResult, toolCallId: tc.id });
+            yield { type: 'tool-call', toolCall: tc };
+            yield { type: 'tool-result', toolCall: tc, result: handoffResult };
+            yield {
+                type: 'handoff',
+                handoff: {
+                    from: loopCtx.agent.constructor.name,
+                    to: spec.AgentClass.name,
+                    ...(transitionMessage ? { message: transitionMessage } : {}),
+                },
+            };
+            loopCtx.pendingHandoff = { spec, transitionMessage, parentToolCallId: tc.id };
+            loopCtx.stopForHandoff = true;
+            // Do NOT break — keep iterating so any sibling tool calls in this
+            // step get their synthetic "skipped" tool results before the loop
+            // exits. This preserves message-log invariants for downstream
+            // persistence.
+            continue;
+        }
         if (!tool.execute) {
             // Client tool — no server-side handler.
             if (options?.toolCallStreamingMode === 'stop-on-client-tool') {
@@ -905,6 +1065,16 @@ async function* runToolPhaseSerial(loopCtx, toolCalls, toolResults) {
                     paused = true;
                     break;
                 }
+                if (isPauseForApprovalChunk(step.value)) {
+                    loopCtx.pendingApprovalToolCall = {
+                        toolCall: step.value.toolCall,
+                        isClientTool: step.value.isClientTool,
+                    };
+                    loopCtx.loopFinishReason = 'tool_approval_required';
+                    loopCtx.stopForApproval = true;
+                    paused = true;
+                    break;
+                }
                 const updateChunk = { type: 'tool-update', toolCall: tc, update: step.value };
                 if (middlewares.length > 0) {
                     const transformed = runOnChunk(middlewares, ctx, updateChunk);
@@ -1156,6 +1326,16 @@ async function runToolExecution(loopCtx, outcome) {
                 paused = true;
                 break;
             }
+            if (isPauseForApprovalChunk(step.value)) {
+                loopCtx.pendingApprovalToolCall = {
+                    toolCall: step.value.toolCall,
+                    isClientTool: step.value.isClientTool,
+                };
+                loopCtx.loopFinishReason = 'tool_approval_required';
+                loopCtx.stopForApproval = true;
+                paused = true;
+                break;
+            }
             const updateChunk = { type: 'tool-update', toolCall: outcome.tc, update: step.value };
             if (middlewares.length > 0) {
                 const transformed = runOnChunk(middlewares, ctx, updateChunk);
@@ -1228,6 +1408,7 @@ async function initializeLoop(a, input, options) {
         stopForApproval: false,
         resumedToolMessages: [],
         failoverAttempts: 0,
+        stopForHandoff: false,
     };
     // Resume server tools left pending by a previous approval round-trip.
     {
@@ -1289,7 +1470,195 @@ async function runIterationPrelude(loopCtx, iteration) {
     return { currentModel };
 }
 // ─── Agent Loop (non-streaming) ──────────────────────────
+/**
+ * Hard ceiling for the number of agent-to-agent handoffs in a single
+ * `prompt()` / `stream()` call. Most workflows hop once or twice (triage →
+ * specialist). Anything beyond this almost certainly means the agents are
+ * cycling — surfacing a clear error beats silently looping until token
+ * budgets explode.
+ */
+const MAX_HANDOFFS = 5;
+/**
+ * Public entry point for the non-streaming agent loop. Drives
+ * {@link runAgentLoopOnce} once, then — if the model called a {@link handoff}
+ * tool — constructs the target agent, carries the conversation forward, and
+ * recurses. Steps and usage from each hop are merged; the final `text` and
+ * `finishReason` come from the agent that produced the terminal answer.
+ * `handoffPath` records the chain of class names traversed.
+ */
 async function runAgentLoop(a, input, options) {
+    const onceResult = await runAgentLoopOnce(a, input, options);
+    if (!onceResult._pendingHandoff) {
+        return stripInternal(onceResult);
+    }
+    const merged = await driveHandoffs(a.constructor.name, onceResult, onceResult._pendingHandoff, onceResult._carriedMessages ?? [], options, 0);
+    return merged;
+}
+/**
+ * Streaming counterpart to {@link runAgentLoop}. Iterates handoffs and
+ * pivots the stream to the next agent each time the parent ends with a
+ * pending handoff. Chunks from every hop flow through the same returned
+ * `AsyncIterable`; the resolved `response` carries the merged final state.
+ */
+function runAgentLoopStreaming(a, input, options) {
+    let resolveResponse;
+    let rejectResponse;
+    const responsePromise = new Promise((resolve, reject) => {
+        resolveResponse = resolve;
+        rejectResponse = reject;
+    });
+    async function* generateStream() {
+        let currentAgent = a;
+        let currentInput = input;
+        let currentOpts = options;
+        const mergedSteps = [];
+        const mergedUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        const handoffPath = [];
+        let finalResponse;
+        for (let hop = 0; hop <= MAX_HANDOFFS; hop++) {
+            const onceStream = runAgentLoopStreamingOnce(currentAgent, currentInput, currentOpts);
+            // Attach a no-op handler so a rejection from the inner response
+            // promise (e.g. caller-supplied AbortSignal firing mid-stream) is
+            // already observed by the time the `for await` re-throws — without
+            // this, Node logs an unhandledRejection between the stream's throw
+            // and our outer `withRejectOnError`'s catch.
+            onceStream.response.catch(() => { });
+            for await (const chunk of onceStream.stream)
+                yield chunk;
+            const r = await onceStream.response;
+            mergedSteps.push(...r.steps);
+            addUsage(mergedUsage, r.usage);
+            if (r._pendingHandoff && hop < MAX_HANDOFFS) {
+                handoffPath.push(currentAgent.constructor.name);
+                const ChildClass = r._pendingHandoff.spec.AgentClass;
+                currentAgent = new ChildClass();
+                currentInput = r._pendingHandoff.transitionMessage;
+                currentOpts = buildHandoffChildOptions(options, r._carriedMessages ?? []);
+                continue;
+            }
+            if (r._pendingHandoff) {
+                throw new Error(`[RudderJS AI] Exceeded max handoffs (${MAX_HANDOFFS}). Likely a cycle between agents.`);
+            }
+            finalResponse = handoffPath.length === 0
+                ? stripInternal(r)
+                : mergeFinalHandoff(stripInternal(r), mergedSteps, mergedUsage, handoffPath, currentAgent.constructor.name);
+            break;
+        }
+        if (!finalResponse) {
+            throw new Error(`[RudderJS AI] Exceeded max handoffs (${MAX_HANDOFFS}). Likely a cycle between agents.`);
+        }
+        resolveResponse(finalResponse);
+    }
+    async function* withRejectOnError() {
+        try {
+            yield* generateStream();
+        }
+        catch (err) {
+            rejectResponse(err);
+            throw err;
+        }
+    }
+    return {
+        stream: withRejectOnError(),
+        response: responsePromise,
+    };
+}
+/**
+ * Iteratively drive pending handoffs, carrying steps + usage forward.
+ * Used by the non-streaming path. (Streaming has its own iterative driver
+ * inline in {@link runAgentLoopStreaming} so chunks can flow as each hop's
+ * loop runs.)
+ */
+async function driveHandoffs(rootName, rootResult, pending, carriedMessages, origOptions, startHopCount) {
+    const mergedSteps = [...rootResult.steps];
+    const mergedUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    addUsage(mergedUsage, rootResult.usage);
+    const handoffPath = [rootName];
+    let currentPending = pending;
+    let currentCarried = carriedMessages;
+    let hopCount = startHopCount;
+    for (;;) {
+        if (hopCount >= MAX_HANDOFFS) {
+            throw new Error(`[RudderJS AI] Exceeded max handoffs (${MAX_HANDOFFS}). Likely a cycle between agents.`);
+        }
+        const ChildClass = currentPending.spec.AgentClass;
+        handoffPath.push(ChildClass.name);
+        const child = new ChildClass();
+        const childOpts = buildHandoffChildOptions(origOptions, currentCarried);
+        const childOnce = await runAgentLoopOnce(child, currentPending.transitionMessage, childOpts);
+        mergedSteps.push(...childOnce.steps);
+        addUsage(mergedUsage, childOnce.usage);
+        if (childOnce._pendingHandoff) {
+            currentPending = childOnce._pendingHandoff;
+            currentCarried = childOnce._carriedMessages ?? [];
+            hopCount++;
+            continue;
+        }
+        return {
+            ...stripInternal(childOnce),
+            steps: mergedSteps,
+            usage: mergedUsage,
+            handoffPath,
+        };
+    }
+}
+/** Merge the terminal hop's response with carried steps / usage / path. */
+function mergeFinalHandoff(terminal, mergedSteps, mergedUsage, pathPrefix, terminalName) {
+    return {
+        ...terminal,
+        steps: mergedSteps,
+        usage: mergedUsage,
+        handoffPath: [...pathPrefix, terminalName],
+    };
+}
+/**
+ * Build the {@link AgentPromptOptions} for a child agent invoked via
+ * handoff. The parent's carried message log replaces the child's input
+ * (so the child sees the full conversation up to the handoff point) but
+ * the child still prepends its own `instructions()` as the system message
+ * during {@link initializeLoop}, so we drop the parent's leading system
+ * message to avoid double-prefixing.
+ *
+ * Per-call options that make sense to carry across (signal, attachments,
+ * tool/middleware overrides) are preserved; `messages` and `history` are
+ * deliberately overridden.
+ */
+function buildHandoffChildOptions(parentOptions, carriedMessages) {
+    const stripped = carriedMessages.length > 0 && carriedMessages[0]?.role === 'system'
+        ? carriedMessages.slice(1)
+        : carriedMessages;
+    // We append the model's transition message as the next user message so
+    // the child has something concrete to respond to (it's also passed as
+    // `currentInput` below — but feeding it via `messages` mode keeps the
+    // history coherent and prevents `initializeLoop` from also prepending
+    // an `input` user message).
+    return {
+        ...(parentOptions ?? {}),
+        messages: stripped,
+    };
+}
+/** Strip the internal `_pendingHandoff` / `_carriedMessages` fields before surfacing the response to public callers. */
+function stripInternal(r) {
+    const out = {
+        text: r.text,
+        steps: r.steps,
+        usage: r.usage,
+    };
+    if (r.conversationId !== undefined)
+        out.conversationId = r.conversationId;
+    if (r.finishReason !== undefined)
+        out.finishReason = r.finishReason;
+    if (r.pendingClientToolCalls !== undefined)
+        out.pendingClientToolCalls = r.pendingClientToolCalls;
+    if (r.pendingApprovalToolCall !== undefined)
+        out.pendingApprovalToolCall = r.pendingApprovalToolCall;
+    if (r.resumedToolMessages !== undefined)
+        out.resumedToolMessages = r.resumedToolMessages;
+    if (r.handoffPath !== undefined)
+        out.handoffPath = r.handoffPath;
+    return out;
+}
+async function runAgentLoopOnce(a, input, options) {
     const { loopCtx, stopConditions } = await initializeLoop(a, input, options);
     const { ctx, middlewares, messages, steps, totalUsage } = loopCtx;
     try {
@@ -1333,7 +1702,7 @@ async function runAgentLoop(a, input, options) {
                 };
                 steps.push(step);
                 emitObserverStepCompleted(loopCtx, iteration, false);
-                if (loopCtx.stopForClientTools || loopCtx.stopForApproval)
+                if (loopCtx.stopForClientTools || loopCtx.stopForApproval || loopCtx.stopForHandoff)
                     break;
                 const shouldStop = stopConditions.some(cond => cond({ steps, iteration, lastMessage: response.message }));
                 if (shouldStop || response.finishReason !== 'tool_calls') {
@@ -1357,7 +1726,7 @@ async function runAgentLoop(a, input, options) {
     return result;
 }
 // ─── Agent Loop (streaming) ──────────────────────────────
-function runAgentLoopStreaming(a, input, options) {
+function runAgentLoopStreamingOnce(a, input, options) {
     let resolveResponse;
     let rejectResponse;
     const responsePromise = new Promise((resolve, reject) => {
@@ -1463,7 +1832,7 @@ function runAgentLoopStreaming(a, input, options) {
                     };
                     steps.push(step);
                     emitObserverStepCompleted(loopCtx, iteration, true);
-                    if (loopCtx.stopForClientTools || loopCtx.stopForApproval)
+                    if (loopCtx.stopForClientTools || loopCtx.stopForApproval || loopCtx.stopForHandoff)
                         break;
                     const shouldStop = stopConditions.some(cond => cond({ steps, iteration, lastMessage: step.message }));
                     if (shouldStop || finishReason !== 'tool_calls')