@rudderjs/ai 0.0.1

package/dist/agent.js

@@ -0,0 +1,1070 @@
+import { AiRegistry } from './registry.js';
+import { isPauseForClientToolsChunk, toolToSchema } from './tool.js';
+import { attachmentsToContentParts, getMessageText } from './attachment.js';
+import { QueuedPromptBuilder } from './queue-job.js';
+import { runOnConfig, runOnChunk, runOnBeforeToolCall, runOnAfterToolCall, runSequential, runOnUsage, runOnAbort, runOnError, } from './middleware.js';
+// ─── Stop Condition Combinators ──────────────────────────
+/** Stop after N steps */
+export function stepCountIs(n) {
+    return ({ steps }) => steps.length >= n;
+}
+/** Stop when a specific tool is called in the latest step */
+export function hasToolCall(toolName) {
+    return ({ steps }) => {
+        const last = steps[steps.length - 1];
+        return last?.toolCalls.some(tc => tc.name === toolName) ?? false;
+    };
+}
+// ─── Agent Base Class ────────────────────────────────────
+export class Agent {
+    /** Model string (e.g. 'anthropic/claude-sonnet-4-5'). Defaults to registry default. */
+    model() { return undefined; }
+    /** Failover provider/model strings */
+    failover() { return []; }
+    /** Maximum iterations for the tool loop (default: 20) */
+    maxSteps() { return 20; }
+    /** Stop conditions — combine with array (OR logic) */
+    stopWhen() {
+        return stepCountIs(this.maxSteps());
+    }
+    /** Temperature (0-1) */
+    temperature() { return undefined; }
+    /** Max tokens for response */
+    maxTokens() { return undefined; }
+    /** Run the agent with a prompt (non-streaming) */
+    async prompt(input, options) {
+        return runAgentLoop(this, input, options);
+    }
+    /** Run the agent with a prompt (streaming) */
+    stream(input, options) {
+        return runAgentLoopStreaming(this, input, options);
+    }
+    /** Queue the prompt for background execution */
+    queue(input, options) {
+        return new QueuedPromptBuilder(this, input, options);
+    }
+    /** Set the user scope for conversation persistence */
+    forUser(userId) {
+        return new ConversableAgent(this).forUser(userId);
+    }
+    /** Continue an existing conversation */
+    continue(conversationId) {
+        return new ConversableAgent(this).continue(conversationId);
+    }
+}
+// ─── Conversable Agent (conversation persistence) ───────
+/**
+ * Wraps an Agent to add conversation memory.
+ * Created via `agent.forUser(id)` or `agent.continue(id)`.
+ */
+export class ConversableAgent {
+    agent;
+    _userId;
+    _conversationId;
+    constructor(agent) {
+        this.agent = agent;
+    }
+    forUser(userId) {
+        this._userId = userId;
+        return this;
+    }
+    continue(conversationId) {
+        this._conversationId = conversationId;
+        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 };
+    }
+    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 };
+    }
+}
+// ─── Anonymous Agent ─────────────────────────────────────
+class AnonymousAgent extends Agent {
+    _instructions;
+    _tools;
+    _model;
+    _middleware;
+    constructor(options) {
+        super();
+        this._instructions = options.instructions;
+        this._tools = options.tools ?? [];
+        this._model = options.model;
+        this._middleware = options.middleware ?? [];
+    }
+    instructions() { return this._instructions; }
+    model() { return this._model; }
+    tools() { return this._tools; }
+    middleware() { return this._middleware; }
+}
+/**
+ * Create an anonymous agent inline.
+ *
+ * @example
+ * const response = await agent('You are helpful.').prompt('Hello')
+ *
+ * @example
+ * const response = await agent({
+ *   instructions: 'You are a search assistant.',
+ *   tools: [searchTool],
+ *   model: 'anthropic/claude-sonnet-4-5',
+ * }).prompt('Find users named John')
+ */
+export function agent(instructionsOrOptions) {
+    const options = typeof instructionsOrOptions === 'string'
+        ? { instructions: instructionsOrOptions }
+        : instructionsOrOptions;
+    return new AnonymousAgent(options);
+}
+// ─── Helpers ─────────────────────────────────────────────
+// ─── Conversation Store Registry ────────────────────────
+let _conversationStore;
+/** Set the global conversation store (called by service provider or manually) */
+export function setConversationStore(store) {
+    _conversationStore = store;
+}
+function resolveConversationStore() {
+    return _conversationStore;
+}
+// ─── Helpers ─────────────────────────────────────────────
+function getTools(a) {
+    return 'tools' in a && typeof a.tools === 'function'
+        ? a.tools()
+        : [];
+}
+function getMiddleware(a) {
+    return 'middleware' in a && typeof a.middleware === 'function'
+        ? a.middleware()
+        : [];
+}
+function createMiddlewareContext(messages, model, tools, iteration) {
+    const [provider] = AiRegistry.parseModelString(model);
+    let aborted = false;
+    let abortReason = '';
+    return {
+        requestId: typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `req-${Date.now()}`,
+        iteration,
+        chunkIndex: 0,
+        messages,
+        model,
+        provider,
+        toolNames: tools.map(t => t.definition.name),
+        abort(reason) {
+            aborted = true;
+            abortReason = reason ?? 'Aborted by middleware';
+        },
+        get _aborted() { return aborted; },
+        get _abortReason() { return abortReason; },
+    };
+}
+function buildUserMessage(input, attachments) {
+    if (!attachments?.length)
+        return { role: 'user', content: input };
+    const parts = [
+        { type: 'text', text: input },
+        ...attachmentsToContentParts(attachments),
+    ];
+    return { role: 'user', content: parts };
+}
+function buildToolSchemas(tools) {
+    return tools.filter(t => !t.definition.lazy).map(toolToSchema);
+}
+function buildToolMap(tools) {
+    const map = new Map();
+    for (const t of tools)
+        map.set(t.definition.name, t);
+    return map;
+}
+function addUsage(total, step) {
+    total.promptTokens += step.promptTokens;
+    total.completionTokens += step.completionTokens;
+    total.totalTokens += step.totalTokens;
+}
+function buildMiddlewareConfig(messages, a) {
+    const config = { messages };
+    const temp = a.temperature();
+    const maxTok = a.maxTokens();
+    if (temp !== undefined)
+        config.temperature = temp;
+    if (maxTok !== undefined)
+        config.maxTokens = maxTok;
+    return config;
+}
+// ─── Agent Loop (non-streaming) ──────────────────────────
+async function runAgentLoop(a, input, options) {
+    const modelString = a.model() ?? AiRegistry.getDefault();
+    const tools = getTools(a);
+    const middlewares = getMiddleware(a);
+    const toolSchemas = buildToolSchemas(tools);
+    const toolMap = buildToolMap(tools);
+    const messages = options?.messages
+        ? [{ role: 'system', content: a.instructions() }, ...options.messages]
+        : [
+            { role: 'system', content: a.instructions() },
+            ...(options?.history ?? []),
+            buildUserMessage(input, options?.attachments),
+        ];
+    const steps = [];
+    const stopConditions = normalizeStopConditions(a.stopWhen());
+    const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    // State for client-tool-stopping and approval-stopping
+    const pendingClientToolCalls = [];
+    let pendingApprovalToolCall;
+    let loopFinishReason;
+    let stopForClientTools = false;
+    let stopForApproval = false;
+    let resumedToolMessages = []; // eslint-disable-line no-useless-assignment
+    // Resume server tools left pending by a previous approval round-trip.
+    // (Must run before middleware context creation since `messages` may grow.)
+    {
+        const resume = await resumePendingToolCalls({ messages, toolMap, options });
+        resumedToolMessages = resume.resumed;
+        if (resume.approvalStillRequired) {
+            pendingApprovalToolCall = resume.approvalStillRequired;
+            loopFinishReason = 'tool_approval_required';
+            stopForApproval = true;
+        }
+    }
+    // Create middleware context
+    const ctx = createMiddlewareContext(messages, modelString, tools, 0);
+    // onConfig — init phase
+    if (middlewares.length > 0) {
+        const configResult = runOnConfig(middlewares, ctx, buildMiddlewareConfig(messages, a), 'init');
+        if (configResult.messages)
+            messages.splice(0, messages.length, ...configResult.messages);
+    }
+    // onStart
+    if (middlewares.length > 0)
+        await runSequential(middlewares, 'onStart', ctx);
+    try {
+        if (stopForApproval) {
+            // Approval is still required from the resume — skip the model loop.
+        }
+        else {
+            for (let iteration = 0; iteration < a.maxSteps(); iteration++) {
+                ctx.iteration = iteration;
+                // Check if middleware aborted
+                if (ctx._aborted) {
+                    await runOnAbort(middlewares, ctx, ctx._abortReason);
+                    break;
+                }
+                // onIteration
+                if (middlewares.length > 0)
+                    await runSequential(middlewares, 'onIteration', ctx);
+                let currentModel = modelString;
+                const currentToolSchemas = toolSchemas;
+                // prepareStep hook
+                if (a.prepareStep) {
+                    const prep = await a.prepareStep({ stepNumber: iteration, steps, messages });
+                    if (prep.model)
+                        currentModel = prep.model;
+                    if (prep.messages)
+                        messages.splice(0, messages.length, ...prep.messages);
+                    if (prep.system)
+                        messages[0] = { role: 'system', content: prep.system };
+                }
+                // onConfig — beforeModel phase
+                if (middlewares.length > 0) {
+                    const configResult = runOnConfig(middlewares, ctx, buildMiddlewareConfig(messages, a), 'beforeModel');
+                    if (configResult.messages)
+                        messages.splice(0, messages.length, ...configResult.messages);
+                }
+                const failoverModels = [currentModel, ...a.failover().filter(m => m !== currentModel)];
+                let response;
+                let lastError;
+                for (const tryModel of failoverModels) {
+                    try {
+                        const adapter = AiRegistry.resolve(tryModel);
+                        const [, modelId] = AiRegistry.parseModelString(tryModel);
+                        const reqOptions = {
+                            model: modelId,
+                            messages,
+                            tools: currentToolSchemas.length > 0 ? currentToolSchemas : undefined,
+                            temperature: a.temperature(),
+                            maxTokens: a.maxTokens(),
+                        };
+                        response = await adapter.generate(reqOptions);
+                        break;
+                    }
+                    catch (err) {
+                        lastError = err instanceof Error ? err : new Error(String(err));
+                        if (tryModel === failoverModels[failoverModels.length - 1])
+                            throw lastError;
+                    }
+                }
+                if (!response)
+                    throw lastError ?? new Error('No provider available');
+                addUsage(totalUsage, response.usage);
+                // onUsage
+                if (middlewares.length > 0)
+                    await runOnUsage(middlewares, ctx, response.usage);
+                const toolCalls = response.message.toolCalls ?? [];
+                const toolResults = [];
+                if (toolCalls.length > 0) {
+                    messages.push(response.message);
+                    for (const tc of toolCalls) {
+                        const tool = toolMap.get(tc.name);
+                        if (!tool) {
+                            toolResults.push({ toolCallId: tc.id, result: `Error: Unknown tool "${tc.name}"` });
+                            messages.push({ role: 'tool', content: `Error: Unknown tool "${tc.name}"`, toolCallId: tc.id });
+                            continue;
+                        }
+                        if (!tool.execute) {
+                            // Client tool — no server-side handler.
+                            if (options?.toolCallStreamingMode === 'stop-on-client-tool') {
+                                pendingClientToolCalls.push(tc);
+                                loopFinishReason = 'client_tool_calls';
+                                stopForClientTools = true;
+                                continue;
+                            }
+                            toolResults.push({ toolCallId: tc.id, result: '[client tool — execute on client]' });
+                            messages.push({ role: 'tool', content: '[client tool — execute on client]', toolCallId: tc.id });
+                            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 });
+                            continue;
+                        }
+                        if (approvalDecision === 'pending') {
+                            pendingApprovalToolCall = { toolCall: tc, isClientTool: false };
+                            loopFinishReason = 'tool_approval_required';
+                            stopForApproval = true;
+                            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 });
+                                    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;
+                                }
+                            }
+                        }
+                        try {
+                            // Drain generator yields silently in the non-streaming loop —
+                            // the same tool definition must work in both prompt() and stream().
+                            // Exception: a `pause_for_client_tools` control chunk yield
+                            // halts iteration, propagates the nested calls to the parent's
+                            // pending list, and skips tool_result recording (see tool.ts
+                            // `pauseForClientTools` for rationale).
+                            const execGen = executeMaybeStreaming(tool, toolArgs, { 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) {
+                                        pendingClientToolCalls.push(pending);
+                                    }
+                                    loopFinishReason = 'client_tool_calls';
+                                    stopForClientTools = true;
+                                    paused = true;
+                                    break;
+                                }
+                                // Plain tool-update yields are silently dropped in the
+                                // non-streaming loop — only the final return value matters.
+                            }
+                            if (paused)
+                                continue; // skip toolResults + message push for this tc
+                            // toolResults preserves the ORIGINAL value; only the tool message
+                            // pushed onto `messages` (what the next model step sees) is
+                            // narrowed by toModelOutput.
+                            toolResults.push({ toolCallId: tc.id, result });
+                            const resultStr = await applyToModelOutput(tool, result, middlewares.length > 0 ? (e) => runOnError(middlewares, ctx, e) : undefined);
+                            messages.push({ role: 'tool', content: resultStr, toolCallId: tc.id });
+                            // onAfterToolCall
+                            if (middlewares.length > 0)
+                                await runOnAfterToolCall(middlewares, ctx, tc.name, toolArgs, result);
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            toolResults.push({ toolCallId: tc.id, result: `Error: ${msg}` });
+                            messages.push({ role: 'tool', content: `Error: ${msg}`, toolCallId: tc.id });
+                            // onAfterToolCall (error case)
+                            if (middlewares.length > 0)
+                                await runOnAfterToolCall(middlewares, ctx, tc.name, toolArgs, `Error: ${msg}`);
+                        }
+                    }
+                    // onToolPhaseComplete
+                    if (middlewares.length > 0)
+                        await runSequential(middlewares, 'onToolPhaseComplete', ctx);
+                }
+                else {
+                    messages.push(response.message);
+                }
+                const step = {
+                    message: response.message,
+                    toolCalls,
+                    toolResults,
+                    usage: response.usage,
+                    finishReason: response.finishReason,
+                };
+                steps.push(step);
+                if (stopForClientTools || stopForApproval)
+                    break;
+                const shouldStop = stopConditions.some(cond => cond({ steps, iteration, lastMessage: response.message }));
+                if (shouldStop || response.finishReason !== 'tool_calls') {
+                    break;
+                }
+            }
+        } // close `else` (skip-loop-when-resume-needs-approval)
+    }
+    catch (err) {
+        // onError
+        if (middlewares.length > 0)
+            await runOnError(middlewares, ctx, err);
+        throw err;
+    }
+    // onFinish
+    if (middlewares.length > 0)
+        await runSequential(middlewares, 'onFinish', ctx);
+    const lastStep = steps[steps.length - 1];
+    const result = {
+        text: lastStep ? getMessageText(lastStep.message.content) : '',
+        steps,
+        usage: totalUsage,
+    };
+    if (loopFinishReason)
+        result.finishReason = loopFinishReason;
+    if (pendingClientToolCalls.length > 0)
+        result.pendingClientToolCalls = pendingClientToolCalls;
+    if (pendingApprovalToolCall)
+        result.pendingApprovalToolCall = pendingApprovalToolCall;
+    if (resumedToolMessages.length > 0)
+        result.resumedToolMessages = resumedToolMessages;
+    return result;
+}
+// ─── Agent Loop (streaming) ──────────────────────────────
+function runAgentLoopStreaming(a, input, options) {
+    let resolveResponse;
+    const responsePromise = new Promise((resolve) => { resolveResponse = resolve; });
+    async function* generateStream() {
+        const modelString = a.model() ?? AiRegistry.getDefault();
+        const tools = getTools(a);
+        const middlewares = getMiddleware(a);
+        const toolSchemas = buildToolSchemas(tools);
+        const toolMap = buildToolMap(tools);
+        const messages = options?.messages
+            ? [{ role: 'system', content: a.instructions() }, ...options.messages]
+            : [
+                { role: 'system', content: a.instructions() },
+                ...(options?.history ?? []),
+                buildUserMessage(input, options?.attachments),
+            ];
+        const steps = [];
+        const stopConditions = normalizeStopConditions(a.stopWhen());
+        const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        // State for client-tool-stopping and approval-stopping
+        const pendingClientToolCalls = [];
+        let pendingApprovalToolCall;
+        let loopFinishReason;
+        let stopForClientTools = false;
+        let stopForApproval = false;
+        let resumedToolMessages = []; // eslint-disable-line no-useless-assignment
+        // Resume server tools left pending by a previous approval round-trip.
+        {
+            const resume = await resumePendingToolCalls({ messages, toolMap, options });
+            resumedToolMessages = resume.resumed;
+            if (resume.approvalStillRequired) {
+                pendingApprovalToolCall = resume.approvalStillRequired;
+                loopFinishReason = 'tool_approval_required';
+                stopForApproval = true;
+            }
+        }
+        // Create middleware context
+        const ctx = createMiddlewareContext(messages, modelString, tools, 0);
+        // onConfig — init phase
+        if (middlewares.length > 0) {
+            const configResult = runOnConfig(middlewares, ctx, buildMiddlewareConfig(messages, a), 'init');
+            if (configResult.messages)
+                messages.splice(0, messages.length, ...configResult.messages);
+        }
+        // onStart
+        if (middlewares.length > 0)
+            await runSequential(middlewares, 'onStart', ctx);
+        try {
+            if (stopForApproval) {
+                // Resume detected unfulfilled approval — skip the model loop entirely.
+            }
+            else {
+                for (let iteration = 0; iteration < a.maxSteps(); iteration++) {
+                    ctx.iteration = iteration;
+                    ctx.chunkIndex = 0;
+                    // Check if middleware aborted
+                    if (ctx._aborted) {
+                        await runOnAbort(middlewares, ctx, ctx._abortReason);
+                        break;
+                    }
+                    // onIteration
+                    if (middlewares.length > 0)
+                        await runSequential(middlewares, 'onIteration', ctx);
+                    let currentModel = modelString;
+                    if (a.prepareStep) {
+                        const prep = await a.prepareStep({ stepNumber: iteration, steps, messages });
+                        if (prep.model)
+                            currentModel = prep.model;
+                        if (prep.messages)
+                            messages.splice(0, messages.length, ...prep.messages);
+                        if (prep.system)
+                            messages[0] = { role: 'system', content: prep.system };
+                    }
+                    // onConfig — beforeModel phase
+                    if (middlewares.length > 0) {
+                        const configResult = runOnConfig(middlewares, ctx, buildMiddlewareConfig(messages, a), 'beforeModel');
+                        if (configResult.messages)
+                            messages.splice(0, messages.length, ...configResult.messages);
+                    }
+                    const failoverModels = [currentModel, ...a.failover().filter(m => m !== currentModel)];
+                    let streamSource;
+                    let lastError;
+                    for (const tryModel of failoverModels) {
+                        try {
+                            const adapter = AiRegistry.resolve(tryModel);
+                            const [, modelId] = AiRegistry.parseModelString(tryModel);
+                            const opts = {
+                                model: modelId,
+                                messages,
+                                tools: toolSchemas.length > 0 ? toolSchemas : undefined,
+                                temperature: a.temperature(),
+                                maxTokens: a.maxTokens(),
+                            };
+                            streamSource = adapter.stream(opts);
+                            break;
+                        }
+                        catch (err) {
+                            lastError = err instanceof Error ? err : new Error(String(err));
+                            if (tryModel === failoverModels[failoverModels.length - 1])
+                                throw lastError;
+                        }
+                    }
+                    if (!streamSource)
+                        throw lastError ?? new Error('No provider available');
+                    let text = '';
+                    let currentToolCalls = [];
+                    let stepUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+                    let finishReason = 'stop';
+                    const partialToolCalls = new Map();
+                    for await (const chunk of streamSource) {
+                        // onChunk — middleware can transform or drop chunks
+                        let processedChunk = chunk;
+                        if (middlewares.length > 0) {
+                            processedChunk = runOnChunk(middlewares, ctx, chunk);
+                            ctx.chunkIndex++;
+                        }
+                        if (processedChunk)
+                            yield processedChunk;
+                        // Always process the original chunk for state tracking
+                        if (chunk.type === 'text-delta' && chunk.text) {
+                            text += chunk.text;
+                        }
+                        else if (chunk.type === 'tool-call-delta' && chunk.toolCall?.id) {
+                            partialToolCalls.set(chunk.toolCall.id, {
+                                id: chunk.toolCall.id,
+                                name: chunk.toolCall.name ?? '',
+                                argChunks: [],
+                            });
+                        }
+                        else if (chunk.type === 'tool-call-delta' && chunk.text) {
+                            // Accumulate argument JSON chunks to the last partial tool call
+                            const last = Array.from(partialToolCalls.values()).pop();
+                            if (last)
+                                last.argChunks.push(chunk.text);
+                        }
+                        else if (chunk.type === 'tool-call' && chunk.toolCall) {
+                            const tc = chunk.toolCall;
+                            currentToolCalls.push(tc);
+                        }
+                        else if (chunk.type === 'usage' && chunk.usage) {
+                            stepUsage = chunk.usage;
+                        }
+                        else if (chunk.type === 'finish') {
+                            if (chunk.usage)
+                                stepUsage = chunk.usage;
+                            finishReason = chunk.finishReason ?? 'stop';
+                        }
+                    }
+                    // Finalize partial tool calls
+                    for (const [, partial] of partialToolCalls) {
+                        try {
+                            const args = JSON.parse(partial.argChunks.join(''));
+                            currentToolCalls.push({ id: partial.id, name: partial.name, arguments: args });
+                        }
+                        catch {
+                            currentToolCalls.push({ id: partial.id, name: partial.name, arguments: {} });
+                        }
+                    }
+                    addUsage(totalUsage, stepUsage);
+                    // onUsage
+                    if (middlewares.length > 0)
+                        await runOnUsage(middlewares, ctx, stepUsage);
+                    const toolResults = [];
+                    if (currentToolCalls.length > 0) {
+                        const assistantMsg = { role: 'assistant', content: text, toolCalls: currentToolCalls };
+                        messages.push(assistantMsg);
+                        for (const tc of currentToolCalls) {
+                            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;
+                            }
+                            if (!tool.execute) {
+                                // Client tool — no server-side handler.
+                                if (options?.toolCallStreamingMode === 'stop-on-client-tool') {
+                                    pendingClientToolCalls.push(tc);
+                                    loopFinishReason = 'client_tool_calls';
+                                    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') {
+                                pendingApprovalToolCall = { toolCall: tc, isClientTool: false };
+                                loopFinishReason = 'tool_approval_required';
+                                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;
+                                    }
+                                }
+                            }
+                            try {
+                                // Emit the tool-call marker before execution so the UI sees
+                                // 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, toolArgs, { 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) {
+                                            pendingClientToolCalls.push(pending);
+                                        }
+                                        loopFinishReason = 'client_tool_calls';
+                                        stopForClientTools = 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
+                                // The streamed `tool-result` chunk and `step.toolResults`
+                                // both carry the ORIGINAL value; only the message content
+                                // pushed onto `messages` (next-step model input) is narrowed
+                                // by toModelOutput.
+                                toolResults.push({ toolCallId: tc.id, result });
+                                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 msg = err instanceof Error ? err.message : String(err);
+                                const errResult = `Error: ${msg}`;
+                                toolResults.push({ toolCallId: tc.id, result: errResult });
+                                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);
+                            }
+                        }
+                        // onToolPhaseComplete
+                        if (middlewares.length > 0)
+                            await runSequential(middlewares, 'onToolPhaseComplete', ctx);
+                    }
+                    else {
+                        messages.push({ role: 'assistant', content: text });
+                    }
+                    const step = {
+                        message: { role: 'assistant', content: text, ...(currentToolCalls.length > 0 ? { toolCalls: currentToolCalls } : {}) },
+                        toolCalls: currentToolCalls,
+                        toolResults,
+                        usage: stepUsage,
+                        finishReason,
+                    };
+                    steps.push(step);
+                    if (stopForClientTools || stopForApproval)
+                        break;
+                    const shouldStop = stopConditions.some(cond => cond({ steps, iteration, lastMessage: step.message }));
+                    if (shouldStop || finishReason !== 'tool_calls')
+                        break;
+                    // Reset for next iteration
+                    text = '';
+                    currentToolCalls = [];
+                }
+            } // close `else` (skip-loop-when-resume-needs-approval)
+        }
+        catch (err) {
+            // onError
+            if (middlewares.length > 0)
+                await runOnError(middlewares, ctx, err);
+            throw err;
+        }
+        // onFinish
+        if (middlewares.length > 0)
+            await runSequential(middlewares, 'onFinish', ctx);
+        // Emit pending state to consumers via dedicated chunk types
+        if (pendingClientToolCalls.length > 0) {
+            yield { type: 'pending-client-tools', toolCalls: pendingClientToolCalls };
+        }
+        if (pendingApprovalToolCall) {
+            yield { type: 'pending-approval', toolCall: pendingApprovalToolCall.toolCall, isClientTool: pendingApprovalToolCall.isClientTool };
+        }
+        const lastStep = steps[steps.length - 1];
+        const result = {
+            text: lastStep ? getMessageText(lastStep.message.content) : '',
+            steps,
+            usage: totalUsage,
+        };
+        if (loopFinishReason)
+            result.finishReason = loopFinishReason;
+        if (pendingClientToolCalls.length > 0)
+            result.pendingClientToolCalls = pendingClientToolCalls;
+        if (pendingApprovalToolCall)
+            result.pendingApprovalToolCall = pendingApprovalToolCall;
+        if (resumedToolMessages.length > 0)
+            result.resumedToolMessages = resumedToolMessages;
+        resolveResponse(result);
+    }
+    return {
+        stream: generateStream(),
+        response: responsePromise,
+    };
+}
+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;
+        }
+        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, tc.arguments, { 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;
+}
+/**
+ * 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