@rudderjs/ai 1.3.0 → 1.5.0

package/dist/agent.js

@@ -1,8 +1,10 @@
 import { z } from 'zod';
 import { AiRegistry } from './registry.js';
-import { isPauseForClientToolsChunk, 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';
 import { runOnConfig, runOnChunk, runOnBeforeToolCall, runOnAfterToolCall, runSequential, runOnUsage, runOnAbort, runOnError, } from './middleware.js';
 // ─── AI Observer (lazy accessor) ─────────────────────────
 function _getAiObservers() {
@@ -79,6 +81,36 @@ export class Agent {
      * }
      */
     cacheable() { return undefined; }
+    /**
+     * Opt into auto-persisted conversation behavior. Override on a subclass
+     * to declare *which* user owns the thread and (optionally) which
+     * specific thread, and the framework will load history before each
+     * `prompt()`/`stream()` call and append the new turn after it — without
+     * any caller having to remember `forUser()` / `continue()`.
+     *
+     * Returning `false` (the default) disables auto-persist; the agent runs
+     * stateless. Returning a {@link ConversationalSpec} opts in:
+     *
+     * @example
+     * class ChatAgent extends Agent {
+     *   conversational() {
+     *     return { user: Auth.user()?.id }   // null user → falsy → opt-out
+     *   }
+     * }
+     *
+     * await new ChatAgent().prompt('Hi')          // auto-loads + auto-saves
+     *
+     * **Precedence (high → low):**
+     * 1. Explicit `agent.forUser(id).prompt()` / `agent.continue(id).prompt()`
+     * 2. Per-call `prompt(input, { conversation: false | {...} })`
+     * 3. This method's return value
+     *
+     * Async returns are supported — useful when the user identity is fetched
+     * from an async DI binding.
+     */
+    conversational() {
+        return false;
+    }
     /**
      * Default for `AgentPromptOptions.parallelTools`. When `true` (default),
      * multiple tool calls within a single step run their `execute()` functions
@@ -88,11 +120,15 @@ export class Agent {
     parallelTools() { return true; }
     /** Run the agent with a prompt (non-streaming) */
     async prompt(input, options) {
+        const spec = await resolveAutoPersistSpec(() => this.conversational(), options?.conversation);
+        if (spec) {
+            return runWithPersistence(spec, this.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoop(this, input, effOptions));
+        }
         return runAgentLoop(this, input, options);
     }
     /** Run the agent with a prompt (streaming) */
     stream(input, options) {
-        return runAgentLoopStreaming(this, input, options);
+        return runStreamWithMaybeAutoPersist(this, input, options);
     }
     /** Queue the prompt for background execution */
     queue(input, options) {
@@ -107,17 +143,302 @@ export class Agent {
         return new ConversableAgent(this).continue(conversationId);
     }
     asTool(options) {
+        if (options.suspendable && !options.streaming) {
+            throw new Error('[RudderJS AI] asTool: `suspendable` requires `streaming: true` (or a projector). Silent suspend would leave the parent UI with no progress signal between sub-agent invocations.');
+        }
         const schema = options.inputSchema ?? z.object({ prompt: z.string() });
         const promptOf = options.prompt ?? ((input) => input.prompt);
         const modelOutput = options.modelOutput ?? ((response) => response.text);
+        if (!options.streaming) {
+            // 1.2.0 zero-config path — single prompt() call, single AgentResponse out.
+            return toolDefinition({
+                name: options.name,
+                description: options.description,
+                inputSchema: schema,
+            })
+                .server((input) => this.prompt(promptOf(input)))
+                .modelOutput(modelOutput);
+        }
+        const project = options.streaming === true ? defaultSubAgentProjector : options.streaming;
+        const innerAgent = this; // eslint-disable-line @typescript-eslint/no-this-alias
+        const agentName = options.name;
+        const suspendable = options.suspendable;
+        const generatorExecute = async function* (input) {
+            const userPrompt = promptOf(input);
+            yield { kind: 'agent_start', agentName };
+            const streamOpts = suspendable
+                ? { toolCallStreamingMode: 'stop-on-client-tool' }
+                : undefined;
+            const { stream, response } = innerAgent.stream(userPrompt, streamOpts);
+            for await (const chunk of stream) {
+                const update = project(chunk);
+                if (update)
+                    yield update;
+            }
+            const result = await response;
+            if (suspendable &&
+                result.finishReason === 'client_tool_calls' &&
+                result.pendingClientToolCalls?.length) {
+                const subRunId = generateSubRunId();
+                const snapshot = {
+                    messages: buildSubAgentSnapshotMessages(userPrompt, result),
+                    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 };
+                yield pauseForClientTools(result.pendingClientToolCalls, subRunId);
+                // 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,
+                tokens: result.usage?.totalTokens ?? 0,
+            };
+            return result;
+        };
         return toolDefinition({
             name: options.name,
             description: options.description,
             inputSchema: schema,
         })
-            .server((input) => this.prompt(promptOf(input)))
+            .server(generatorExecute)
             .modelOutput(modelOutput);
     }
+    /**
+     * 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:
+     *
+     * - **`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, 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  Client-tool resume
+     * const r = await Agent.resumeAsTool(subRunId, browserResults, { runStore, agent: subAgent })
+     *
+     * @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.`);
+        }
+        const pauseKind = snapshot.pauseKind ?? 'client_tool';
+        const pending = new Set(snapshot.pendingToolCallIds);
+        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);
+            }
+            // 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,
+                });
+            }
+        }
+        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();
+            const newSnapshot = {
+                messages: buildResumeSnapshotMessages(messages, result),
+                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 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 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.
+ */
+function defaultSubAgentProjector(chunk) {
+    if (chunk.type === 'tool-call' && chunk.toolCall?.name) {
+        return {
+            kind: 'tool_call',
+            tool: chunk.toolCall.name,
+            ...(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;
+}
+/**
+ * Reconstruct the inner-agent message history at the point the loop
+ * paused, so a subsequent {@link Agent.resumeAsTool} can rerun the loop
+ * with the appended client tool results. The shape is `[user, …(message
+ * + serverToolResults)*]` — system messages are omitted because the
+ * `messages` mode of the agent loop prepends `system` itself.
+ *
+ * Each step's `message` includes ALL `toolCalls` (server + client).
+ * Server-side `toolResults` are interleaved; client-side calls remain
+ * unfulfilled until resume appends their results.
+ */
+function buildSubAgentSnapshotMessages(userPrompt, response) {
+    const out = [{ role: 'user', content: userPrompt }];
+    for (const step of response.steps) {
+        out.push(step.message);
+        for (const tr of step.toolResults) {
+            const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
+            out.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
+        }
+    }
+    return out;
+}
+/**
+ * Snapshot reconstruction for a resume-time pause. The `priorMessages`
+ * already include the original user prompt + every step prior to the
+ * resume call. Append the freshly-completed steps' messages and any
+ * server-side tool results so the next resume sees the full history.
+ */
+function buildResumeSnapshotMessages(priorMessages, response) {
+    const out = [...priorMessages];
+    for (const step of response.steps) {
+        out.push(step.message);
+        for (const tr of step.toolResults) {
+            const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
+            out.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
+        }
+    }
+    return out;
+}
+function generateSubRunId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function')
+        return globalThis.crypto.randomUUID();
+    return `sub-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
 }
 // ─── Conversable Agent (conversation persistence) ───────
 /**
@@ -140,84 +461,35 @@ export class ConversableAgent {
         return this;
     }
     async prompt(input, options) {
-        const store = resolveConversationStore();
-        if (!store)
-            throw new Error('[RudderJS AI] No ConversationStore registered. Register one via the DI container with key "ai.conversations".');
-        // Load or create conversation
-        let history = options?.history ?? [];
-        if (this._conversationId) {
-            history = [...(await store.load(this._conversationId)), ...history];
-        }
-        else {
-            const meta = this._userId ? { userId: this._userId } : undefined;
-            this._conversationId = await store.create(undefined, meta);
-        }
-        const response = await runAgentLoop(this.agent, input, { ...options, history });
-        // Persist messages
-        const newMessages = [
-            { role: 'user', content: input },
-            ...response.steps.flatMap(s => {
-                const msgs = [s.message];
-                for (const tr of s.toolResults) {
-                    const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
-                    msgs.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
-                }
-                return msgs;
-            }),
-        ];
-        await store.append(this._conversationId, newMessages);
-        return { text: response.text, steps: response.steps, usage: response.usage, conversationId: this._conversationId };
+        const spec = this.toSpec();
+        return runWithPersistence(spec, this.agent.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoop(this.agent, input, effOptions)).then((r) => {
+            // Track the resolved id back on the wrapper so a subsequent
+            // `wrapper.prompt()` call resumes the same thread.
+            if (r.conversationId)
+                this._conversationId = r.conversationId;
+            return r;
+        });
     }
     stream(input, options) {
-        const store = resolveConversationStore();
-        if (!store)
-            throw new Error('[RudderJS AI] No ConversationStore registered. Register one via the DI container with key "ai.conversations".');
-        // We need to handle async setup, so wrap the streaming
-        let resolveReady;
-        const ready = new Promise(r => { resolveReady = r; });
-        let loadedHistory = [];
-        let convId = this._conversationId;
-        // Kick off async setup
-        const setupPromise = (async () => {
-            if (convId) {
-                loadedHistory = await store.load(convId);
-            }
-            else {
-                const meta = this._userId ? { userId: this._userId } : undefined;
-                convId = await store.create(undefined, meta);
-                this._conversationId = convId;
-            }
-            resolveReady();
-        })();
-        let resolveResponse;
-        const responsePromise = new Promise(r => { resolveResponse = r; });
-        const self = this; // eslint-disable-line @typescript-eslint/no-this-alias
-        const storeRef = store;
-        async function* generateStream() {
-            await setupPromise;
-            const history = [...loadedHistory, ...(options?.history ?? [])];
-            const inner = runAgentLoopStreaming(self.agent, input, { ...options, history });
-            for await (const chunk of inner.stream) {
-                yield chunk;
-            }
-            const response = await inner.response;
-            // Persist messages
-            const newMessages = [
-                { role: 'user', content: input },
-                ...response.steps.flatMap(s => {
-                    const msgs = [s.message];
-                    for (const tr of s.toolResults) {
-                        const resultStr = typeof tr.result === 'string' ? tr.result : JSON.stringify(tr.result);
-                        msgs.push({ role: 'tool', content: resultStr, toolCallId: tr.toolCallId });
-                    }
-                    return msgs;
-                }),
-            ];
-            await storeRef.append(convId, newMessages);
-            const result = { text: response.text, steps: response.steps, usage: response.usage, conversationId: convId };
-            resolveResponse(result);
-        }
-        return { stream: generateStream(), response: responsePromise };
+        const spec = this.toSpec();
+        const persisted = runWithPersistenceStreaming(spec, this.agent.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoopStreaming(this.agent, input, effOptions));
+        // Update the wrapper's id once the run completes.
+        persisted.response.then((r) => { if (r.conversationId)
+            this._conversationId = r.conversationId; }, () => { });
+        return persisted;
+    }
+    /**
+     * Translate the wrapper's explicit-form state (`forUser` / `continue`)
+     * into a {@link ConversationalSpec}. The explicit chain bypasses the
+     * agent's `conversational()` declaration entirely — `forUser` always
+     * wins over class defaults.
+     */
+    toSpec() {
+        if (this._conversationId)
+            return { user: this._userId ?? '', id: this._conversationId };
+        if (this._userId)
+            return { user: this._userId };
+        throw new Error('[RudderJS AI] ConversableAgent requires forUser() or continue() to be called before prompt().');
     }
 }
 // ─── Anonymous Agent ─────────────────────────────────────
@@ -267,6 +539,76 @@ export function setConversationStore(store) {
 function resolveConversationStore() {
     return _conversationStore;
 }
+/**
+ * Streaming counterpart of `Agent.prompt`'s auto-persist branch. The spec
+ * resolution is async (since `conversational()` may return a Promise), so
+ * we defer the decision into the outer wrapper that handles the inner
+ * stream's setup the same way `runWithPersistenceStreaming` does for the
+ * persisted path.
+ */
+function runStreamWithMaybeAutoPersist(a, input, options) {
+    // Synchronous fast path — most agents don't override `conversational()`,
+    // so we'd pay an extra microtask boundary on every streaming call. Bail
+    // out cheaply when we can prove the call is stateless.
+    const declared = a.conversational();
+    const isFast = (options?.conversation === false ||
+        (declared === false && (options?.conversation === undefined)));
+    if (isFast) {
+        return runAgentLoopStreaming(a, input, options);
+    }
+    // Async path — resolve the spec, then dispatch to the persisted or plain stream.
+    let resolveResp;
+    let rejectResp;
+    const responsePromise = new Promise((res, rej) => { resolveResp = res; rejectResp = rej; });
+    async function* outer() {
+        let spec;
+        try {
+            spec = await resolveAutoPersistSpec(() => a.conversational(), options?.conversation);
+        }
+        catch (err) {
+            rejectResp(err);
+            throw err;
+        }
+        if (!spec) {
+            const inner = runAgentLoopStreaming(a, input, options);
+            try {
+                for await (const chunk of inner.stream)
+                    yield chunk;
+            }
+            catch (err) {
+                rejectResp(err);
+                throw err;
+            }
+            try {
+                const r = await inner.response;
+                resolveResp(r);
+            }
+            catch (err) {
+                rejectResp(err);
+                throw err;
+            }
+            return;
+        }
+        const persisted = runWithPersistenceStreaming(spec, a.constructor.name, resolveConversationStore, input, options, (effOptions) => runAgentLoopStreaming(a, input, effOptions));
+        try {
+            for await (const chunk of persisted.stream)
+                yield chunk;
+        }
+        catch (err) {
+            rejectResp(err);
+            throw err;
+        }
+        try {
+            const r = await persisted.response;
+            resolveResp(r);
+        }
+        catch (err) {
+            rejectResp(err);
+            throw err;
+        }
+    }
+    return { stream: outer(), response: responsePromise };
+}
 // ─── Helpers ─────────────────────────────────────────────
 function getTools(a) {
     return 'tools' in a && typeof a.tools === 'function'
@@ -513,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;
 }
 /**
@@ -535,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);
     }
@@ -564,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') {
@@ -665,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);
@@ -916,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);
@@ -988,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.
     {
@@ -1049,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 {
@@ -1093,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') {
@@ -1117,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) => {
@@ -1223,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')