@rudderjs/ai 1.6.0 → 1.6.2

package/dist/agent.js

@@ -1,14 +1,16 @@
 import { z } from 'zod';
 import { AiRegistry } from './registry.js';
-import { isPauseForApprovalChunk, isPauseForClientToolsChunk, pauseForApproval, pauseForClientTools, toolDefinition, toolToSchema } from './tool.js';
-import { isHandoffTool } from './handoff.js';
+import { pauseForApproval, pauseForClientTools, toolDefinition, toolToSchema } from './tool.js';
 import { attachmentsToContentParts, getMessageText } from './attachment.js';
 import { QueuedPromptBuilder } from './queue-job.js';
 import { resolveAutoPersistSpec, runWithPersistence, runWithPersistenceStreaming, } from './conversation-persistence.js';
 import { resolveRemembersSpec } from './memory.js';
 import { withMemoryInject } from './memory-inject.js';
 import { withMemoryExtract } from './memory-extract.js';
-import { runOnConfig, runOnChunk, runOnBeforeToolCall, runOnAfterToolCall, runSequential, runOnUsage, runOnAbort, runOnError, } from './middleware.js';
+import { runOnConfig, runOnChunk, runSequential, runOnUsage, runOnAbort, runOnError, } from './middleware.js';
+import { executeToolPhase } from './tool-execution.js';
+import { resumePendingToolCalls } from './resume-approval.js';
+import { buildHandoffChildOptions, driveHandoffs, MAX_HANDOFFS, mergeFinalHandoff, stripInternal, } from './handoffs-driver.js';
 // ─── AI Observer (lazy accessor) ─────────────────────────
 function _getAiObservers() {
     return globalThis['__rudderjs_ai_observers__'] ?? null;
@@ -669,10 +671,11 @@ function runStreamWithMaybeAutoPersist(a, input, options) {
     return { stream: outer(), response: responsePromise };
 }
 // ─── Helpers ─────────────────────────────────────────────
+function hasToolsMethod(a) {
+    return 'tools' in a && typeof a.tools === 'function';
+}
 function getTools(a) {
-    return 'tools' in a && typeof a.tools === 'function'
-        ? a.tools()
-        : [];
+    return hasToolsMethod(a) ? a.tools() : [];
 }
 /**
  * Internal symbol used to plumb auto-installed middlewares (today:
@@ -682,10 +685,11 @@ function getTools(a) {
  * just appends them to the user's `agent.middleware()` array.
  */
 const EXTRA_MIDDLEWARES = Symbol.for('rudderjs.ai.extraMiddlewares');
+function hasMiddlewareMethod(a) {
+    return 'middleware' in a && typeof a.middleware === 'function';
+}
 function getMiddleware(a, options) {
-    const own = 'middleware' in a && typeof a.middleware === 'function'
-        ? a.middleware()
-        : [];
+    const own = hasMiddlewareMethod(a) ? a.middleware() : [];
     const extras = options?.[EXTRA_MIDDLEWARES] ?? [];
     return extras.length > 0 ? [...own, ...extras] : own;
 }
@@ -965,499 +969,6 @@ function buildAgentResponse(loopCtx) {
     }
     return result;
 }
-/**
- * Execute the tool phase for a single agent step. Yields the same
- * `StreamChunk` sequence (`tool-call` → `tool-update*` → `tool-result`) that
- * the streaming caller surfaces to consumers. Non-streaming callers iterate
- * via `.next()` and discard yields — the side effects (message pushes,
- * pending-state mutations on `loopCtx`) are identical regardless of whether
- * the chunks reach a consumer.
- *
- * Returns the step's `ToolResult[]`. The caller passes the assistant message
- * to push before iteration so the AgentStep shape (response.message) and the
- * final `messages` array stay in sync with the loop variant.
- */
-async function* executeToolPhase(loopCtx, toolCalls, assistantMessage) {
-    const { messages, middlewares, options, ctx } = loopCtx;
-    const toolResults = [];
-    messages.push(assistantMessage);
-    // Resolve parallelism setting. Per-call option wins; falls back to the
-    // 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).
-    //
-    // 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);
-    }
-    else {
-        yield* runToolPhaseSerial(loopCtx, toolCalls, toolResults);
-    }
-    // onToolPhaseComplete
-    if (middlewares.length > 0)
-        await runSequential(middlewares, 'onToolPhaseComplete', ctx);
-    return toolResults;
-}
-/**
- * Serial tool execution — the original behavior. Runs each tool call's
- * prelude (approval, before-middleware, validation) and `execute()`
- * one-after-another, streaming `tool-update` chunks live as the tool
- * emits them.
- */
-async function* runToolPhaseSerial(loopCtx, toolCalls, toolResults) {
-    const { messages, middlewares, toolMap, options, ctx } = loopCtx;
-    for (const tc of toolCalls) {
-        const tool = toolMap.get(tc.name);
-        if (!tool) {
-            const unknownResult = `Error: Unknown tool "${tc.name}"`;
-            toolResults.push({ toolCallId: tc.id, result: unknownResult });
-            messages.push({ role: 'tool', content: unknownResult, toolCallId: tc.id });
-            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') {
-                loopCtx.pendingClientToolCalls.push(tc);
-                loopCtx.loopFinishReason = 'client_tool_calls';
-                loopCtx.stopForClientTools = true;
-                yield { type: 'tool-call', toolCall: tc };
-                continue;
-            }
-            const placeholder = '[client tool — execute on client]';
-            toolResults.push({ toolCallId: tc.id, result: placeholder });
-            messages.push({ role: 'tool', content: placeholder, toolCallId: tc.id });
-            yield { type: 'tool-call', toolCall: tc };
-            yield { type: 'tool-result', toolCall: tc, result: placeholder };
-            continue;
-        }
-        // needsApproval enforcement
-        const approvalDecision = await evaluateApproval(tool, tc, options);
-        if (approvalDecision === 'rejected') {
-            const rejectionResult = { rejected: true, reason: 'User rejected this tool call' };
-            toolResults.push({ toolCallId: tc.id, result: rejectionResult });
-            messages.push({ role: 'tool', content: JSON.stringify(rejectionResult), toolCallId: tc.id });
-            yield { type: 'tool-result', toolCall: tc, result: rejectionResult };
-            continue;
-        }
-        if (approvalDecision === 'pending') {
-            loopCtx.pendingApprovalToolCall = { toolCall: tc, isClientTool: false };
-            loopCtx.loopFinishReason = 'tool_approval_required';
-            loopCtx.stopForApproval = true;
-            yield { type: 'tool-call', toolCall: tc };
-            break;
-        }
-        // onBeforeToolCall
-        let toolArgs = tc.arguments;
-        if (middlewares.length > 0) {
-            const beforeResult = await runOnBeforeToolCall(middlewares, ctx, tc.name, toolArgs);
-            if (beforeResult) {
-                if (beforeResult.type === 'skip') {
-                    const resultStr = typeof beforeResult.result === 'string' ? beforeResult.result : JSON.stringify(beforeResult.result);
-                    toolResults.push({ toolCallId: tc.id, result: beforeResult.result });
-                    messages.push({ role: 'tool', content: resultStr, toolCallId: tc.id });
-                    yield { type: 'tool-result', toolCall: tc, result: beforeResult.result };
-                    await runOnAfterToolCall(middlewares, ctx, tc.name, toolArgs, beforeResult.result);
-                    continue;
-                }
-                if (beforeResult.type === 'abort') {
-                    await runOnAbort(middlewares, ctx, beforeResult.reason);
-                    break;
-                }
-                if (beforeResult.type === 'transformArgs') {
-                    toolArgs = beforeResult.args;
-                }
-            }
-        }
-        // Validate args against the tool's inputSchema. Runs after middleware
-        // transforms so transforms can reshape malformed model output before
-        // it is judged. The tool-call chunk is emitted even on validation
-        // failure so streaming UIs see a paired tool-call → tool-result(error)
-        // sequence; non-streaming callers discard the chunk.
-        const validation = validateToolArgs(tool, toolArgs);
-        if (!validation.ok) {
-            yield { type: 'tool-call', toolCall: tc };
-            toolResults.push({ toolCallId: tc.id, result: validation.error });
-            messages.push({ role: 'tool', content: JSON.stringify(validation.error), toolCallId: tc.id });
-            yield { type: 'tool-result', toolCall: tc, result: validation.error };
-            if (middlewares.length > 0)
-                await runOnAfterToolCall(middlewares, ctx, tc.name, toolArgs, validation.error);
-            continue;
-        }
-        const validatedArgs = validation.value;
-        const toolStart = performance.now();
-        try {
-            // Emit the tool-call marker before execution so streaming UIs see
-            // tool-call → tool-update* → tool-result in order. Async-generator
-            // executes stream their yields as tool-update chunks live; plain
-            // executes yield nothing here.
-            //
-            // Pause detection: a yielded `pause_for_client_tools` control chunk
-            // halts iteration, propagates the nested calls to the parent's
-            // pending list, and SKIPS the tool_result emission — the yielding
-            // tool's own call stays orphaned in the parent message history
-            // until the caller resolves it on resume.
-            yield { type: 'tool-call', toolCall: tc };
-            const execGen = executeMaybeStreaming(tool, validatedArgs, { toolCallId: tc.id });
-            let result;
-            let paused = false;
-            while (true) {
-                const step = await execGen.next();
-                if (step.done) {
-                    result = step.value;
-                    break;
-                }
-                if (isPauseForClientToolsChunk(step.value)) {
-                    for (const pending of step.value.toolCalls) {
-                        loopCtx.pendingClientToolCalls.push(pending);
-                    }
-                    loopCtx.loopFinishReason = 'client_tool_calls';
-                    loopCtx.stopForClientTools = true;
-                    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);
-                    if (transformed)
-                        yield transformed;
-                }
-                else {
-                    yield updateChunk;
-                }
-            }
-            if (paused)
-                continue; // skip tool_result emission + message push for this tc
-            const duration = performance.now() - toolStart;
-            // toolResults preserves the ORIGINAL value; only the message content
-            // pushed onto `messages` (next-step model input) is narrowed by
-            // toModelOutput. The streamed `tool-result` chunk also carries the
-            // ORIGINAL value.
-            toolResults.push({ toolCallId: tc.id, result, duration });
-            const resultStr = await applyToModelOutput(tool, result, middlewares.length > 0 ? (e) => runOnError(middlewares, ctx, e) : undefined);
-            messages.push({ role: 'tool', content: resultStr, toolCallId: tc.id });
-            yield { type: 'tool-result', toolCall: tc, result };
-            // onAfterToolCall
-            if (middlewares.length > 0)
-                await runOnAfterToolCall(middlewares, ctx, tc.name, toolArgs, result);
-        }
-        catch (err) {
-            const duration = performance.now() - toolStart;
-            const msg = err instanceof Error ? err.message : String(err);
-            const errResult = `Error: ${msg}`;
-            toolResults.push({ toolCallId: tc.id, result: errResult, duration });
-            messages.push({ role: 'tool', content: errResult, toolCallId: tc.id });
-            yield { type: 'tool-result', toolCall: tc, result: errResult };
-            // onAfterToolCall (error case)
-            if (middlewares.length > 0)
-                await runOnAfterToolCall(middlewares, ctx, tc.name, toolArgs, errResult);
-        }
-    }
-}
-/**
- * Parallel tool execution — three phases:
- *
- * 1. **Prelude (serial, in tool-call order):** classify each call. Approval
- *    decisions, `onBeforeToolCall` middleware, and arg validation all
- *    resolve here; the next phase only sees calls that cleared every
- *    gate. `pending-approval` and `mw-abort` short-circuit the prelude
- *    exactly as they do in serial mode — later calls are never dispatched.
- *
- * 2. **Execution (parallel):** for every `ready` outcome, drive
- *    `executeMaybeStreaming` to completion concurrently. `tool-update`
- *    chunks (and any pause-for-client-tools mutations to `loopCtx`) are
- *    captured per-call into a buffer.
- *
- * 3. **Replay (serial, in tool-call order):** for each outcome, emit its
- *    chunks (including buffered `tool-update`s for ready calls), push
- *    tool messages, and run `onAfterToolCall`. This is the only phase
- *    that yields chunks to consumers, so streamed output stays
- *    deterministic regardless of which `execute()` finished first.
- */
-async function* runToolPhaseParallel(loopCtx, toolCalls, toolResults) {
-    const { messages, middlewares, ctx } = loopCtx;
-    // ─── Phase 1: prelude ──────────────────────────────────
-    const outcomes = await classifyToolCalls(loopCtx, toolCalls);
-    // ─── Phase 2: dispatch ready executions concurrently ──
-    const ready = outcomes.filter((o) => o.kind === 'ready');
-    const executions = await Promise.all(ready.map(o => runToolExecution(loopCtx, o)));
-    const executionByCallId = new Map();
-    for (let i = 0; i < ready.length; i++) {
-        executionByCallId.set(ready[i].tc.id, executions[i]);
-    }
-    // ─── Phase 3: replay chunks + side-effects in order ───
-    for (const outcome of outcomes) {
-        if (outcome.kind === 'unknown-tool') {
-            toolResults.push({ toolCallId: outcome.tc.id, result: outcome.result });
-            messages.push({ role: 'tool', content: outcome.result, toolCallId: outcome.tc.id });
-            yield { type: 'tool-result', toolCall: outcome.tc, result: outcome.result };
-            continue;
-        }
-        if (outcome.kind === 'client-tool-stop') {
-            // loopCtx mutations already applied during the prelude.
-            yield { type: 'tool-call', toolCall: outcome.tc };
-            continue;
-        }
-        if (outcome.kind === 'client-tool-placeholder') {
-            toolResults.push({ toolCallId: outcome.tc.id, result: outcome.result });
-            messages.push({ role: 'tool', content: outcome.result, toolCallId: outcome.tc.id });
-            yield { type: 'tool-call', toolCall: outcome.tc };
-            yield { type: 'tool-result', toolCall: outcome.tc, result: outcome.result };
-            continue;
-        }
-        if (outcome.kind === 'rejected') {
-            toolResults.push({ toolCallId: outcome.tc.id, result: outcome.result });
-            messages.push({ role: 'tool', content: JSON.stringify(outcome.result), toolCallId: outcome.tc.id });
-            yield { type: 'tool-result', toolCall: outcome.tc, result: outcome.result };
-            continue;
-        }
-        if (outcome.kind === 'pending-approval') {
-            // loopCtx mutations already applied during the prelude.
-            yield { type: 'tool-call', toolCall: outcome.tc };
-            // Phase 1 stops classifying after pending-approval, so this is the
-            // last outcome — but `break` keeps the intent explicit.
-            break;
-        }
-        if (outcome.kind === 'mw-skip') {
-            const resultStr = typeof outcome.result === 'string' ? outcome.result : JSON.stringify(outcome.result);
-            toolResults.push({ toolCallId: outcome.tc.id, result: outcome.result });
-            messages.push({ role: 'tool', content: resultStr, toolCallId: outcome.tc.id });
-            yield { type: 'tool-result', toolCall: outcome.tc, result: outcome.result };
-            if (middlewares.length > 0)
-                await runOnAfterToolCall(middlewares, ctx, outcome.tc.name, outcome.toolArgs, outcome.result);
-            continue;
-        }
-        if (outcome.kind === 'validation-error') {
-            yield { type: 'tool-call', toolCall: outcome.tc };
-            toolResults.push({ toolCallId: outcome.tc.id, result: outcome.error });
-            messages.push({ role: 'tool', content: JSON.stringify(outcome.error), toolCallId: outcome.tc.id });
-            yield { type: 'tool-result', toolCall: outcome.tc, result: outcome.error };
-            if (middlewares.length > 0)
-                await runOnAfterToolCall(middlewares, ctx, outcome.tc.name, outcome.toolArgs, outcome.error);
-            continue;
-        }
-        // outcome.kind === 'ready'
-        const exec = executionByCallId.get(outcome.tc.id);
-        yield { type: 'tool-call', toolCall: outcome.tc };
-        for (const chunk of exec.updates)
-            yield chunk;
-        if (exec.kind === 'paused') {
-            // Pause-for-client-tools propagated its calls onto `loopCtx` during
-            // execution. Skip tool_result emission + message push — the call
-            // stays orphaned until resume.
-            continue;
-        }
-        if (exec.kind === 'error') {
-            const errResult = `Error: ${exec.error.message}`;
-            toolResults.push({ toolCallId: outcome.tc.id, result: errResult, duration: exec.duration });
-            messages.push({ role: 'tool', content: errResult, toolCallId: outcome.tc.id });
-            yield { type: 'tool-result', toolCall: outcome.tc, result: errResult };
-            if (middlewares.length > 0)
-                await runOnAfterToolCall(middlewares, ctx, outcome.tc.name, outcome.toolArgs, errResult);
-            continue;
-        }
-        // exec.kind === 'ok'
-        toolResults.push({ toolCallId: outcome.tc.id, result: exec.result, duration: exec.duration });
-        const resultStr = await applyToModelOutput(outcome.tool, exec.result, middlewares.length > 0 ? (e) => runOnError(middlewares, ctx, e) : undefined);
-        messages.push({ role: 'tool', content: resultStr, toolCallId: outcome.tc.id });
-        yield { type: 'tool-result', toolCall: outcome.tc, result: exec.result };
-        if (middlewares.length > 0)
-            await runOnAfterToolCall(middlewares, ctx, outcome.tc.name, outcome.toolArgs, exec.result);
-    }
-}
-/**
- * Walk `toolCalls` in order and decide each call's fate. Mutations to
- * `loopCtx` for client-tool-stop, pending-approval, and middleware-abort
- * happen here so the rest of the parallel flow sees the same state the
- * serial path would. `pending-approval` and `mw-abort` stop the walk —
- * later calls are not classified and are silently dropped.
- */
-async function classifyToolCalls(loopCtx, toolCalls) {
-    const { middlewares, toolMap, options, ctx } = loopCtx;
-    const outcomes = [];
-    for (const tc of toolCalls) {
-        const tool = toolMap.get(tc.name);
-        if (!tool) {
-            outcomes.push({ kind: 'unknown-tool', tc, result: `Error: Unknown tool "${tc.name}"` });
-            continue;
-        }
-        if (!tool.execute) {
-            if (options?.toolCallStreamingMode === 'stop-on-client-tool') {
-                loopCtx.pendingClientToolCalls.push(tc);
-                loopCtx.loopFinishReason = 'client_tool_calls';
-                loopCtx.stopForClientTools = true;
-                outcomes.push({ kind: 'client-tool-stop', tc });
-                continue;
-            }
-            outcomes.push({ kind: 'client-tool-placeholder', tc, result: '[client tool — execute on client]' });
-            continue;
-        }
-        const approvalDecision = await evaluateApproval(tool, tc, options);
-        if (approvalDecision === 'rejected') {
-            outcomes.push({ kind: 'rejected', tc, result: { rejected: true, reason: 'User rejected this tool call' } });
-            continue;
-        }
-        if (approvalDecision === 'pending') {
-            loopCtx.pendingApprovalToolCall = { toolCall: tc, isClientTool: false };
-            loopCtx.loopFinishReason = 'tool_approval_required';
-            loopCtx.stopForApproval = true;
-            outcomes.push({ kind: 'pending-approval', tc });
-            break;
-        }
-        let toolArgs = tc.arguments;
-        if (middlewares.length > 0) {
-            const beforeResult = await runOnBeforeToolCall(middlewares, ctx, tc.name, toolArgs);
-            if (beforeResult) {
-                if (beforeResult.type === 'skip') {
-                    outcomes.push({ kind: 'mw-skip', tc, toolArgs, result: beforeResult.result });
-                    continue;
-                }
-                if (beforeResult.type === 'abort') {
-                    await runOnAbort(middlewares, ctx, beforeResult.reason);
-                    // Drop any prior outcomes too? No — serial mode emits prior
-                    // outcomes' chunks before hitting abort, so we keep them in the
-                    // outcomes list and Phase 3 emits them up to (but not including)
-                    // this call. Stop classifying further.
-                    break;
-                }
-                if (beforeResult.type === 'transformArgs') {
-                    toolArgs = beforeResult.args;
-                }
-            }
-        }
-        const validation = validateToolArgs(tool, toolArgs);
-        if (!validation.ok) {
-            outcomes.push({ kind: 'validation-error', tc, toolArgs, error: validation.error });
-            continue;
-        }
-        outcomes.push({ kind: 'ready', tc, tool, toolArgs, validatedArgs: validation.value });
-    }
-    return outcomes;
-}
-/**
- * Drive a single tool's `executeMaybeStreaming` to completion. Buffers
- * `tool-update` chunks for replay in tool-call order; pause-for-client-tools
- * mutations to `loopCtx` apply immediately and the call returns `paused`.
- *
- * `ctx` is shared across concurrent invocations. Middleware that writes
- * through `ctx` during `runOnChunk` (uncommon — most use it read-only for
- * telemetry) may observe interleaved updates from sibling tool calls;
- * apps with such middleware should opt out via `parallelTools: false`.
- */
-async function runToolExecution(loopCtx, outcome) {
-    const { middlewares, ctx } = loopCtx;
-    const updates = [];
-    const toolStart = performance.now();
-    try {
-        const execGen = executeMaybeStreaming(outcome.tool, outcome.validatedArgs, { toolCallId: outcome.tc.id });
-        let result;
-        let paused = false;
-        while (true) {
-            const step = await execGen.next();
-            if (step.done) {
-                result = step.value;
-                break;
-            }
-            if (isPauseForClientToolsChunk(step.value)) {
-                for (const pending of step.value.toolCalls) {
-                    loopCtx.pendingClientToolCalls.push(pending);
-                }
-                loopCtx.loopFinishReason = 'client_tool_calls';
-                loopCtx.stopForClientTools = true;
-                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);
-                if (transformed)
-                    updates.push(transformed);
-            }
-            else {
-                updates.push(updateChunk);
-            }
-        }
-        const duration = performance.now() - toolStart;
-        if (paused)
-            return { kind: 'paused', updates, duration };
-        return { kind: 'ok', result, updates, duration };
-    }
-    catch (err) {
-        const duration = performance.now() - toolStart;
-        return { kind: 'error', error: err instanceof Error ? err : new Error(String(err)), updates, duration };
-    }
-}
 /**
  * Build the shared `LoopContext` for a `prompt()` / `stream()` call, run
  * approval-resume, and fire `onConfig(init)` + `onStart`. After this returns,
@@ -1572,14 +1083,6 @@ 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}
@@ -1593,7 +1096,7 @@ async function runAgentLoop(a, input, options) {
     if (!onceResult._pendingHandoff) {
         return stripInternal(onceResult);
     }
-    const merged = await driveHandoffs(a.constructor.name, onceResult, onceResult._pendingHandoff, onceResult._carriedMessages ?? [], options, 0);
+    const merged = await driveHandoffs(a.constructor.name, onceResult, onceResult._pendingHandoff, onceResult._carriedMessages ?? [], options, 0, runAgentLoopOnce);
     return merged;
 }
 /**
@@ -1665,101 +1168,6 @@ function runAgentLoopStreaming(a, input, options) {
         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;
@@ -1960,7 +1368,11 @@ function runAgentLoopStreamingOnce(a, input, options) {
             yield { type: 'pending-client-tools', toolCalls: loopCtx.pendingClientToolCalls };
         }
         if (loopCtx.pendingApprovalToolCall) {
-            yield { type: 'pending-approval', toolCall: loopCtx.pendingApprovalToolCall.toolCall, isClientTool: loopCtx.pendingApprovalToolCall.isClientTool };
+            yield {
+                type: 'pending-approval',
+                toolCall: loopCtx.pendingApprovalToolCall.toolCall,
+                isClientTool: loopCtx.pendingApprovalToolCall.isClientTool,
+            };
         }
         const result = buildAgentResponse(loopCtx);
         emitObserverCompleted(loopCtx, result, true);
@@ -1987,216 +1399,4 @@ function runAgentLoopStreamingOnce(a, input, options) {
 function normalizeStopConditions(cond) {
     return Array.isArray(cond) ? cond : [cond];
 }
-/**
- * When continuing a chat after a stop-on-approval round-trip, the supplied
- * `messages` array ends with an `assistant` message whose `toolCalls` were
- * never fulfilled (the loop paused before executing them). Most providers
- * (Anthropic in particular) reject such conversations because every
- * `tool_use` block must be followed by a matching `tool_result`.
- *
- * This helper detects that case, executes the pending **server** tool calls
- * (honoring `approvedToolCallIds` / `rejectedToolCallIds`), appends the
- * resulting tool messages to `messages` in place, and returns them. The
- * caller can attach the returned list to `AgentResponse.resumedToolMessages`
- * so that the panels dispatcher persists them in the conversation store.
- *
- * Client tools (no `execute`) must come back from the browser with their
- * tool result already in the conversation, so the trailing assistant message
- * will not have unmatched `toolCalls` for them — they're handled outside.
- */
-async function resumePendingToolCalls(deps) {
-    const { messages, toolMap, options } = deps;
-    const last = messages[messages.length - 1];
-    if (!last || last.role !== 'assistant' || !last.toolCalls || last.toolCalls.length === 0) {
-        return { resumed: [], approvalStillRequired: undefined };
-    }
-    const resumed = [];
-    let approvalStillRequired;
-    for (const tc of last.toolCalls) {
-        const tool = toolMap.get(tc.name);
-        if (!tool) {
-            const err = `Error: Unknown tool "${tc.name}"`;
-            const m = { role: 'tool', content: err, toolCallId: tc.id };
-            messages.push(m);
-            resumed.push(m);
-            continue;
-        }
-        if (!tool.execute) {
-            // Client tool whose result is missing from the supplied messages.
-            // Surface an error so the model can recover instead of hanging.
-            const err = `Error: client tool "${tc.name}" was not executed by the browser`;
-            const m = { role: 'tool', content: err, toolCallId: tc.id };
-            messages.push(m);
-            resumed.push(m);
-            continue;
-        }
-        const decision = await evaluateApproval(tool, tc, options);
-        if (decision === 'rejected') {
-            const rej = { rejected: true, reason: 'User rejected this tool call' };
-            const m = { role: 'tool', content: JSON.stringify(rej), toolCallId: tc.id };
-            messages.push(m);
-            resumed.push(m);
-            continue;
-        }
-        if (decision === 'pending') {
-            // Still pending — the user has not yet approved this call. Re-emit
-            // the pending state and stop processing further tools.
-            approvalStillRequired = { toolCall: tc, isClientTool: false };
-            break;
-        }
-        // Validate args before executing on resume. Approval-resume bypasses
-        // middleware so we use the raw tc.arguments. On failure, feed the
-        // structured error to the model so it can correct itself.
-        const validation = validateToolArgs(tool, tc.arguments);
-        if (!validation.ok) {
-            const m = { role: 'tool', content: JSON.stringify(validation.error), toolCallId: tc.id };
-            messages.push(m);
-            resumed.push(m);
-            continue;
-        }
-        try {
-            // Drain generator yields silently — approval-resume runs outside the
-            // stream, so any preliminary updates are discarded; only the final
-            // return value is captured.
-            const execGen = executeMaybeStreaming(tool, validation.value, { toolCallId: tc.id });
-            let result;
-            while (true) {
-                const step = await execGen.next();
-                if (step.done) {
-                    result = step.value;
-                    break;
-                }
-            }
-            // Approval-resume has no middleware context here, so toModelOutput
-            // errors fall back silently to default stringification (R6).
-            const content = await applyToModelOutput(tool, result);
-            const m = { role: 'tool', content, toolCallId: tc.id };
-            messages.push(m);
-            resumed.push(m);
-        }
-        catch (err) {
-            const errMsg = `Error: ${err instanceof Error ? err.message : String(err)}`;
-            const m = { role: 'tool', content: errMsg, toolCallId: tc.id };
-            messages.push(m);
-            resumed.push(m);
-        }
-    }
-    return { resumed, approvalStillRequired };
-}
-/**
- * Detect an async generator (the value returned by `async function*` or any
- * object implementing the AsyncGenerator protocol). We use a structural check
- * because the executor may not be authored as a literal `async function*`
- * (e.g. wrapped or returned from a factory).
- */
-function isAsyncGenerator(value) {
-    if (value === null || typeof value !== 'object')
-        return false;
-    const v = value;
-    return typeof v.next === 'function'
-        && typeof v.return === 'function'
-        && typeof v[Symbol.asyncIterator] === 'function';
-}
-/**
- * Uniformly iterate a tool's `execute`, whether it returns a value, a
- * promise, or an async generator.
- *
- * The helper is itself an async generator: each `yield` is a preliminary
- * tool-update payload (only generator-style executes produce these), and the
- * generator's `return` value is the final tool result.
- *
- * Streaming callers iterate and emit `tool-update` chunks live as updates
- * arrive. Non-streaming callers iterate and discard yields, capturing only
- * the final return value — same tool definition works in both modes.
- */
-async function* executeMaybeStreaming(tool, args, ctx) {
-    const execute = tool.execute;
-    if (!execute) {
-        throw new Error('Tool has no execute function');
-    }
-    const ret = execute(args, ctx);
-    if (isAsyncGenerator(ret)) {
-        while (true) {
-            const step = await ret.next();
-            if (step.done)
-                return step.value;
-            yield step.value;
-        }
-    }
-    return await ret;
-}
-/**
- * Validate a tool call's arguments against the tool's `inputSchema`. On
- * success, the parsed value is returned — zod transforms (`.transform`,
- * `.default`, type coercion) are applied, so `execute` receives the
- * canonical shape the schema describes. On failure, a structured error
- * suitable for feeding back to the model is returned.
- */
-function validateToolArgs(tool, args) {
-    const parsed = tool.definition.inputSchema.safeParse(args);
-    if (parsed.success) {
-        return { ok: true, value: parsed.data };
-    }
-    return {
-        ok: false,
-        error: {
-            error: 'invalid_arguments',
-            message: `Tool "${tool.definition.name}" received arguments that did not match its inputSchema.`,
-            issues: parsed.error.issues.map(i => ({
-                path: i.path.map(seg => String(seg)).join('.'),
-                message: i.message,
-            })),
-        },
-    };
-}
-/**
- * Default stringification used for the `tool` role message content when a
- * tool has no `toModelOutput` transform: pass through strings, JSON-encode
- * everything else.
- */
-function defaultStringify(value) {
-    return typeof value === 'string' ? value : JSON.stringify(value);
-}
-/**
- * Convert a tool's structured `result` into the string the **model** will
- * see on its next step. Honors `tool.toModelOutput` when present, falling
- * back to {@link defaultStringify}.
- *
- * Per R6 in the ai-loop-parity plan: a throwing `toModelOutput` MUST NOT
- * crash the loop. We swallow the error, route it through `onError`
- * middleware so it stays observable, and use the default stringification
- * as a safety net.
- */
-async function applyToModelOutput(tool, result, onError) {
-    if (tool.toModelOutput) {
-        try {
-            return await tool.toModelOutput(result);
-        }
-        catch (err) {
-            if (onError)
-                await onError(err);
-        }
-    }
-    return defaultStringify(result);
-}
-/**
- * Resolve `needsApproval` for a tool call, taking into account the
- * client-supplied `approvedToolCallIds` / `rejectedToolCallIds` lists.
- *
- * Returns:
- * - `'allow'`     — execute the tool normally (default; also when approved)
- * - `'pending'`   — needsApproval is truthy and the call has not been approved
- * - `'rejected'`  — the call appears in `rejectedToolCallIds`
- */
-async function evaluateApproval(tool, tc, options) {
-    const needs = tool.definition.needsApproval;
-    const requires = typeof needs === 'function' ? await needs(tc.arguments) : !!needs;
-    if (!requires)
-        return 'allow';
-    if (options?.rejectedToolCallIds?.includes(tc.id))
-        return 'rejected';
-    if (options?.approvedToolCallIds?.includes(tc.id))
-        return 'allow';
-    return 'pending';
-}
 //# sourceMappingURL=agent.js.map