whale-code 6.4.0

package/dist/server/lib/server-agent-loop.js

@@ -0,0 +1,667 @@
+/**
+ * Unified Server Agent Loop — single source of truth for server-side agentic reasoning.
+ *
+ * Used by:
+ * - handleAgentChat (SSE streaming to clients)
+ * - setAgentExecutor (workflow "agent" step type)
+ *
+ * Consolidates: streaming, prompt caching, context management betas, compaction,
+ * loop detection, parallel tool execution, subagent delegation, retry, cost tracking.
+ */
+import { LoopDetector, getContextManagement, getMaxOutputTokens, getThinkingConfig, addPromptCaching, estimateCostUsd, isRetryableError, sanitizeError, routeModel, resolveToolChoice, COMPACTION_TRIGGER_TOKENS, COMPACTION_TOTAL_BUDGET, DEFAULT_SESSION_COST_BUDGET_USD, } from "../../shared/agent-core.js";
+import { processStreamWithCallbacks } from "../../shared/sse-parser.js";
+import { MODELS } from "../../shared/constants.js";
+import { dispatchTools, buildAssistantContent } from "../../shared/tool-dispatch.js";
+import { getCachedToolDefs, getFullToolSchemas } from "../tool-router.js";
+import { DELEGATE_TASK_TOOL_DEF, runServerSubagent, } from "./server-subagent.js";
+import { handleTranscribe } from "../handlers/transcription.js";
+import { preCompact } from "./compaction-service.js";
+import { providerFailover } from "./provider-failover.js";
+import { saveCheckpoint } from "./session-checkpoint.js";
+import { createLogger } from "./logger.js";
+const log = createLogger("agent-loop");
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const MAX_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_CONCURRENT_TOOLS = 7;
+// ============================================================================
+// TOOL CHOICE MAPPING — convert ToolChoice to provider-specific format
+// ============================================================================
+/**
+ * Map ToolChoice to Anthropic API `tool_choice` format.
+ * Returns undefined if tools should be omitted entirely.
+ */
+function mapToolChoiceForAnthropic(tc) {
+    if (tc === "auto")
+        return { toolChoice: { type: "auto" } };
+    if (tc === "any")
+        return { toolChoice: { type: "any" } };
+    if (tc === "none")
+        return { omitTools: true };
+    if (typeof tc === "object" && tc.type === "tool") {
+        return { toolChoice: { type: "tool", name: tc.name } };
+    }
+    return { toolChoice: { type: "auto" } };
+}
+// ============================================================================
+// UNIFIED AGENT LOOP
+// ============================================================================
+export async function runServerAgentLoop(opts) {
+    const { anthropic, model, systemPrompt, messages, tools: inputTools, maxTurns, temperature, enableDelegation = true, enablePromptCaching = true, enableStreaming = true, maxConcurrentTools = DEFAULT_MAX_CONCURRENT_TOOLS, maxCostUsd = DEFAULT_SESSION_COST_BUDGET_USD, onText, onToolStart, onCitation, documents, clientDisconnected = { value: false }, startedAt = Date.now(), maxDurationMs = 5 * 60 * 1000, } = opts;
+    // Auto-inject delegate_task for all models (subagents always use Claude Haiku/Sonnet)
+    // activeTools is mutable — discover_tools adds to it during the session
+    const activeTools = [...inputTools];
+    if (enableDelegation) {
+        if (!activeTools.some((t) => t.name === "delegate_task")) {
+            activeTools.push(DELEGATE_TASK_TOOL_DEF);
+        }
+    }
+    // Per-conversation tracking of discovered tools — accumulates tool names
+    // activated via discover_tools so they persist across turns within this session.
+    // If extendedTools were provided (from a previous session or pre-load), we
+    // don't inject them yet (that defeats lazy loading), but we keep the full
+    // list available for the executor to reference.
+    const discoveredToolNames = new Set();
+    // Alias for backward compat within this function
+    const tools = activeTools;
+    const loopDetector = new LoopDetector();
+    // Model routing: extract first user message for complexity estimation
+    const firstUserMsg = messages.find((m) => m.role === "user");
+    const firstUserText = firstUserMsg
+        ? typeof firstUserMsg.content === "string"
+            ? firstUserMsg.content
+            : Array.isArray(firstUserMsg.content)
+                ? firstUserMsg.content
+                    .filter((b) => b.type === "text" && b.text)
+                    .map((b) => b.text)
+                    .join(" ")
+                : ""
+        : "";
+    // Pre-computed tool defs — reused across turns, only rebuilt when tools array changes
+    let cachedToolDefsForSession = getCachedToolDefs(tools);
+    let lastToolCount = tools.length;
+    // Accumulators
+    let turnCount = 0;
+    let toolCallCount = 0;
+    let totalIn = 0;
+    let totalOut = 0;
+    let cacheCreationTokens = 0;
+    let cacheReadTokens = 0;
+    let sessionCostUsd = 0;
+    let compactionCount = 0;
+    let finalResponse = "";
+    const allTextResponses = [];
+    const allToolNames = [];
+    const allCitations = [];
+    const turnMetrics = [];
+    while (turnCount < maxTurns) {
+        // Abort checks
+        if (clientDisconnected.value) {
+            log.info("client disconnected, stopping");
+            break;
+        }
+        if (Date.now() - startedAt > maxDurationMs) {
+            onText?.("[Request timeout exceeded]");
+            break;
+        }
+        // Cost budget enforcement — prevent runaway spending (skip if unlimited)
+        if (isFinite(maxCostUsd) && sessionCostUsd >= maxCostUsd) {
+            log.warn({ sessionCostUsd, maxCostUsd }, "cost budget exceeded");
+            onText?.(`\n[Session cost budget reached ($${sessionCostUsd.toFixed(2)}/$${maxCostUsd.toFixed(2)}). Wrapping up.]`);
+            break;
+        }
+        turnCount++;
+        loopDetector.resetTurn();
+        // Route model on the FIRST turn only — subsequent turns use the requested model
+        // since the conversation may have become complex after tool results.
+        const effectiveModel = turnCount === 1
+            ? routeModel(firstUserText, model)
+            : model;
+        if (turnCount === 1 && effectiveModel !== model) {
+            log.info({ from: model, to: effectiveModel }, "model routed");
+        }
+        // Per-turn model config — uses effectiveModel so routed models get correct settings
+        const maxTokens = opts.maxTokens ?? getMaxOutputTokens(effectiveModel);
+        const ctxMgmt = getContextManagement(effectiveModel);
+        const thinkingCfg = getThinkingConfig(effectiveModel, true);
+        // Prepare tool definitions — use pre-computed cache, only rebuild when tools change
+        // (discover_tools can add tools mid-session, detected via length change)
+        if (tools.length !== lastToolCount) {
+            cachedToolDefsForSession = getCachedToolDefs(tools);
+            lastToolCount = tools.length;
+        }
+        // Pre-compaction: mechanically strip redundant data before LLM call
+        // Runs every turn but only modifies messages when there's significant bloat
+        const { messages: preCompacted, bytesRemoved } = preCompact(messages);
+        if (bytesRemoved > 10000) {
+            log.info({ bytesRemoved, bytesRemovedKB: Math.round(bytesRemoved / 1024) }, "pre-compaction applied");
+            // Replace messages in-place so the outer array reference stays valid
+            messages.length = 0;
+            messages.push(...preCompacted);
+        }
+        // Prompt caching: tools + turn boundary
+        let finalToolDefs = cachedToolDefsForSession;
+        let finalMessages = messages;
+        if (enablePromptCaching) {
+            const cached = addPromptCaching(cachedToolDefsForSession, messages);
+            finalToolDefs = cached.tools;
+            finalMessages = cached.messages;
+        }
+        // System prompt: cached block + dynamic cost context (skip cost line if unlimited budget)
+        const costContext = isFinite(maxCostUsd)
+            ? `Session cost: $${sessionCostUsd.toFixed(2)} / $${maxCostUsd.toFixed(2)}`
+            : `Session cost: $${sessionCostUsd.toFixed(2)}`;
+        const system = enablePromptCaching
+            ? [
+                { type: "text", text: systemPrompt, cache_control: { type: "ephemeral" } },
+                { type: "text", text: costContext },
+            ]
+            : [
+                { type: "text", text: systemPrompt },
+                { type: "text", text: costContext },
+            ];
+        // Resolve tool_choice for this turn
+        const recentToolUses = turnMetrics.slice(-3).flatMap(t => t.toolsUsed);
+        const resolvedToolChoice = resolveToolChoice({
+            toolChoice: opts.toolChoice,
+            turnCount,
+            recentToolUses,
+            availableToolNames: tools.map(t => t.name),
+            userMessage: firstUserText,
+        });
+        const { toolChoice: anthropicToolChoice, omitTools } = mapToolChoiceForAnthropic(resolvedToolChoice);
+        if (omitTools) {
+            log.info({ turn: turnCount, resolvedToolChoice }, "tool_choice=none — omitting tools");
+        }
+        // Provider failover check — route to healthy provider (capability-aware)
+        const failoverResult = providerFailover.getActiveProvider(effectiveModel, opts.requiredCapabilities);
+        const activeModel = failoverResult.model;
+        const activeProvider = failoverResult.provider;
+        let turnFailoverInfo;
+        if (failoverResult.failedOver) {
+            turnFailoverInfo = {
+                originalProvider: failoverResult.originalProvider,
+                activeProvider: failoverResult.provider,
+                model: failoverResult.model,
+            };
+            // Re-compute model config for the failover model
+            // (context management, thinking, max tokens may differ)
+        }
+        // API call with retry
+        if (enableStreaming) {
+            // ---- STREAMING PATH ----
+            let stream = null;
+            for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    // Cast through unknown: context_management.edits is Record<string, unknown>[]
+                    // from getContextManagement() but SDK expects specific edit union types
+                    const streamBetas = [...ctxMgmt.betas];
+                    if (thinkingCfg.beta)
+                        streamBetas.push(thinkingCfg.beta);
+                    // Citations API: add beta when source documents are provided
+                    if (documents?.length && !streamBetas.includes("citations-2025-04-15")) {
+                        streamBetas.push("citations-2025-04-15");
+                    }
+                    stream = await anthropic.beta.messages.create({
+                        model: activeModel,
+                        max_tokens: maxTokens,
+                        temperature: thinkingCfg.thinking.type !== "disabled" ? 1 : temperature,
+                        system,
+                        ...(omitTools ? {} : { tools: finalToolDefs }),
+                        ...(anthropicToolChoice && !omitTools ? { tool_choice: anthropicToolChoice } : {}),
+                        messages: finalMessages,
+                        stream: true,
+                        thinking: thinkingCfg.thinking,
+                        betas: streamBetas,
+                        context_management: ctxMgmt.config,
+                        ...(documents?.length ? { documents } : {}),
+                    });
+                    providerFailover.recordSuccess(activeProvider);
+                    break;
+                }
+                catch (err) {
+                    providerFailover.recordFailure(activeProvider);
+                    if (attempt < MAX_RETRIES && isRetryableError(err)) {
+                        const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+                        log.warn({ attempt: attempt + 1, maxRetries: MAX_RETRIES, delayMs: delay, err: sanitizeError(err) }, "retrying API call");
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (!stream)
+                throw new Error("Failed to get response after retries");
+            // Process stream events via unified parser
+            const streamResult = await processStreamWithCallbacks(stream, { onText, onToolStart, onCitation });
+            const currentText = streamResult.text;
+            const toolUseBlocks = streamResult.toolUseBlocks;
+            const compactionContent = streamResult.compactionContent;
+            // Accumulate citations from this turn
+            if (streamResult.citations.length > 0) {
+                allCitations.push(...streamResult.citations);
+            }
+            // Accumulate per-turn tokens into session totals
+            const turnIn = streamResult.usage.inputTokens;
+            const turnOut = streamResult.usage.outputTokens;
+            const turnCacheRead = streamResult.usage.cacheReadTokens;
+            const turnCacheCreation = streamResult.usage.cacheCreationTokens;
+            totalIn += turnIn;
+            totalOut += turnOut;
+            cacheCreationTokens += turnCacheCreation;
+            cacheReadTokens += turnCacheRead;
+            // Update cost (include cache tokens for accurate pricing)
+            sessionCostUsd = estimateCostUsd(totalIn, totalOut, model, 0, cacheReadTokens, cacheCreationTokens);
+            // Record per-turn metrics for observability
+            const turnToolNames = toolUseBlocks.map(b => b.name);
+            turnMetrics.push({
+                turn: turnCount,
+                inputTokens: turnIn,
+                outputTokens: turnOut,
+                cacheRead: turnCacheRead,
+                cacheCreation: turnCacheCreation,
+                toolsUsed: turnToolNames,
+                costUsd: estimateCostUsd(turnIn, turnOut, model, 0, turnCacheRead, turnCacheCreation),
+                ...(turnFailoverInfo ? { failover: turnFailoverInfo } : {}),
+            });
+            if (currentText)
+                allTextResponses.push(currentText);
+            // Compaction handling — API paused after generating summary.
+            // Preserve last 2 messages (1 user + 1 assistant turn) for continuity,
+            // then resume. This is NOT a new turn — just context compression.
+            if (streamResult.stopReason === "compaction" && compactionContent) {
+                compactionCount++;
+                log.info({ compactionCount }, "compaction — preserving last 2 messages, resuming");
+                // Budget enforcement: if cumulative compaction cost exceeds budget, force wrap-up
+                if (compactionCount * COMPACTION_TRIGGER_TOKENS >= COMPACTION_TOTAL_BUDGET) {
+                    log.warn({ compactionCount, triggerTokens: COMPACTION_TRIGGER_TOKENS, estimatedTokens: compactionCount * COMPACTION_TRIGGER_TOKENS }, "compaction budget exhausted");
+                    onText?.("\n[Context budget reached — wrapping up.]");
+                    // Rebuild messages: compaction summary + wrap-up instruction
+                    const compactedMessages = [
+                        { role: "assistant", content: [{ type: "compaction", content: compactionContent }] },
+                        { role: "user", content: [{ type: "text", text: "You have reached the context budget. Please wrap up your current work and provide a final summary of what was accomplished and what remains." }] },
+                    ];
+                    messages.length = 0;
+                    messages.push(...compactedMessages);
+                    continue;
+                }
+                // Normal compaction: preserve last 2 messages for continuity
+                const preserved = messages.slice(-2);
+                const compactedMessages = [
+                    { role: "assistant", content: [{ type: "compaction", content: compactionContent }] },
+                    ...preserved,
+                ];
+                messages.length = 0;
+                messages.push(...compactedMessages);
+                turnCount--; // Don't count compaction as a turn
+                continue;
+            }
+            // No tool calls — check if truncated at max_tokens
+            if (toolUseBlocks.length === 0) {
+                if (streamResult.stopReason === "max_tokens") {
+                    const assistantContent = buildAssistantContent({ text: currentText, toolUseBlocks: [], compactionContent });
+                    messages.push({ role: "assistant", content: assistantContent });
+                    messages.push({ role: "user", content: [{ type: "text", text: "[Your response was truncated due to length. Please continue where you left off.]" }] });
+                    continue;
+                }
+                finalResponse = currentText;
+                break;
+            }
+            // Execute tools and build messages for next turn
+            const subagentTokens = { input: 0, output: 0, costUsd: 0 };
+            const executor = makeToolExecutor(opts, tools, allToolNames, subagentTokens, discoveredToolNames);
+            const { results: toolResults } = await dispatchTools(toolUseBlocks, executor, {
+                loopDetector,
+                maxConcurrent: maxConcurrentTools,
+                // maxResultChars removed — Anthropic context_management handles limits
+                transcribeAudio: opts.storeId
+                    ? async (base64, mediaType) => {
+                        const result = await handleTranscribe(opts.supabase, opts.storeId, base64, mediaType);
+                        if (!result.success || !result.transcript) {
+                            throw new Error(result.error || "Transcription returned no transcript");
+                        }
+                        return result.transcript;
+                    }
+                    : undefined,
+            });
+            toolCallCount += toolUseBlocks.length;
+            // Aggregate subagent tokens into parent totals
+            totalIn += subagentTokens.input;
+            totalOut += subagentTokens.output;
+            sessionCostUsd = estimateCostUsd(totalIn, totalOut, model, 0, cacheReadTokens, cacheCreationTokens) + subagentTokens.costUsd;
+            const assistantContent = buildAssistantContent({ text: currentText, toolUseBlocks, compactionContent });
+            messages.push({ role: "assistant", content: assistantContent });
+            messages.push({ role: "user", content: toolResults });
+            // Session checkpoint — fire-and-forget, never blocks the loop
+            if (opts.conversationId) {
+                saveCheckpoint(opts.supabase, opts.conversationId, turnCount, messages, { input: totalIn, output: totalOut, cacheRead: cacheReadTokens, cacheCreation: cacheCreationTokens }, sessionCostUsd, allToolNames).catch(() => { }); // swallow — saveCheckpoint already logs internally
+            }
+        }
+        else {
+            // ---- NON-STREAMING PATH ----
+            let response = null;
+            for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+                try {
+                    // Cast through unknown: context_management.edits is Record<string, unknown>[]
+                    // from getContextManagement() but SDK expects specific edit union types
+                    const nsBetas = [...ctxMgmt.betas];
+                    if (thinkingCfg.beta)
+                        nsBetas.push(thinkingCfg.beta);
+                    // Citations API: add beta when source documents are provided
+                    if (documents?.length && !nsBetas.includes("citations-2025-04-15")) {
+                        nsBetas.push("citations-2025-04-15");
+                    }
+                    response = await anthropic.beta.messages.create({
+                        model: activeModel,
+                        max_tokens: maxTokens,
+                        temperature: thinkingCfg.thinking.type !== "disabled" ? 1 : temperature,
+                        system,
+                        ...(omitTools ? {} : { tools: finalToolDefs }),
+                        ...(anthropicToolChoice && !omitTools ? { tool_choice: anthropicToolChoice } : {}),
+                        messages: finalMessages,
+                        thinking: thinkingCfg.thinking,
+                        betas: nsBetas,
+                        context_management: ctxMgmt.config,
+                        ...(documents?.length ? { documents } : {}),
+                    });
+                    providerFailover.recordSuccess(activeProvider);
+                    break;
+                }
+                catch (err) {
+                    providerFailover.recordFailure(activeProvider);
+                    if (attempt < MAX_RETRIES && isRetryableError(err)) {
+                        const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+                        log.warn({ attempt: attempt + 1, maxRetries: MAX_RETRIES, delayMs: delay, err: sanitizeError(err) }, "retrying API call");
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            if (!response)
+                throw new Error("Failed to get response after retries");
+            // Track tokens
+            const nsTurnIn = response.usage?.input_tokens || 0;
+            const nsTurnOut = response.usage?.output_tokens || 0;
+            const nsTurnCacheCreation = response.usage?.cache_creation_input_tokens ?? 0;
+            const nsTurnCacheRead = response.usage?.cache_read_input_tokens ?? 0;
+            totalIn += nsTurnIn;
+            totalOut += nsTurnOut;
+            cacheCreationTokens += nsTurnCacheCreation;
+            cacheReadTokens += nsTurnCacheRead;
+            // Extract text, tool_use, cite, and compaction blocks
+            let currentText = "";
+            let nsCompactionContent = null;
+            const toolUseBlocks = [];
+            for (const block of response.content) {
+                if (block.type === "text") {
+                    currentText += block.text;
+                    onText?.(block.text);
+                }
+                else if (block.type === "tool_use") {
+                    toolUseBlocks.push({
+                        id: block.id,
+                        name: block.name,
+                        input: block.input,
+                    });
+                    onToolStart?.(block.name, block.input);
+                }
+                else if (block.type === "cite") {
+                    const citeBlock = block;
+                    const citation = {
+                        type: "cite",
+                        cited_text: citeBlock.cited_text ?? "",
+                        document_index: citeBlock.document_index ?? 0,
+                        start_char_index: citeBlock.start_char_index ?? 0,
+                        end_char_index: citeBlock.end_char_index ?? 0,
+                        ...(citeBlock.document_title ? { document_title: citeBlock.document_title } : {}),
+                    };
+                    allCitations.push(citation);
+                    onCitation?.(citation);
+                }
+                else if (block.type === "compaction") {
+                    nsCompactionContent = block.content || "";
+                }
+            }
+            sessionCostUsd = estimateCostUsd(totalIn, totalOut, model, 0, cacheReadTokens, cacheCreationTokens);
+            // Record per-turn metrics (non-streaming)
+            const nsTurnToolNames = toolUseBlocks.map(b => b.name);
+            turnMetrics.push({
+                turn: turnCount,
+                inputTokens: nsTurnIn,
+                outputTokens: nsTurnOut,
+                cacheRead: nsTurnCacheRead,
+                cacheCreation: nsTurnCacheCreation,
+                toolsUsed: nsTurnToolNames,
+                costUsd: estimateCostUsd(nsTurnIn, nsTurnOut, model, 0, nsTurnCacheRead, nsTurnCacheCreation),
+                ...(turnFailoverInfo ? { failover: turnFailoverInfo } : {}),
+            });
+            if (currentText)
+                allTextResponses.push(currentText);
+            // Compaction handling (non-streaming) — same logic as streaming path
+            if (response.stop_reason === "compaction" && nsCompactionContent !== null) {
+                compactionCount++;
+                log.info({ compactionCount, streaming: false }, "compaction — preserving last 2 messages");
+                if (compactionCount * COMPACTION_TRIGGER_TOKENS >= COMPACTION_TOTAL_BUDGET) {
+                    onText?.("\n[Context budget reached — wrapping up.]");
+                    const compactedMessages = [
+                        { role: "assistant", content: [{ type: "compaction", content: nsCompactionContent }] },
+                        { role: "user", content: [{ type: "text", text: "You have reached the context budget. Please wrap up your current work and provide a final summary." }] },
+                    ];
+                    messages.length = 0;
+                    messages.push(...compactedMessages);
+                    continue;
+                }
+                const preserved = messages.slice(-2);
+                const compactedMessages = [
+                    { role: "assistant", content: [{ type: "compaction", content: nsCompactionContent }] },
+                    ...preserved,
+                ];
+                messages.length = 0;
+                messages.push(...compactedMessages);
+                turnCount--;
+                continue;
+            }
+            // No tool calls — check if truncated at max_tokens
+            if (toolUseBlocks.length === 0) {
+                if (response.stop_reason === "max_tokens") {
+                    const assistantContent = buildAssistantContent({ text: currentText, toolUseBlocks: [] });
+                    messages.push({ role: "assistant", content: assistantContent });
+                    messages.push({ role: "user", content: [{ type: "text", text: "[Your response was truncated due to length. Please continue where you left off.]" }] });
+                    continue;
+                }
+                finalResponse = currentText;
+                break;
+            }
+            // Execute tools
+            const nonStreamSubTokens = { input: 0, output: 0, costUsd: 0 };
+            const nsExecutor = makeToolExecutor(opts, tools, allToolNames, nonStreamSubTokens, discoveredToolNames);
+            const { results: toolResults } = await dispatchTools(toolUseBlocks, nsExecutor, {
+                loopDetector,
+                maxConcurrent: maxConcurrentTools,
+                // maxResultChars removed — Anthropic context_management handles limits
+            });
+            toolCallCount += toolUseBlocks.length;
+            // Aggregate subagent tokens into parent totals
+            totalIn += nonStreamSubTokens.input;
+            totalOut += nonStreamSubTokens.output;
+            sessionCostUsd = estimateCostUsd(totalIn, totalOut, model, 0, cacheReadTokens, cacheCreationTokens) + nonStreamSubTokens.costUsd;
+            const assistantContent = buildAssistantContent({ text: currentText, toolUseBlocks });
+            messages.push({ role: "assistant", content: assistantContent });
+            messages.push({ role: "user", content: toolResults });
+            // Session checkpoint — fire-and-forget, never blocks the loop
+            if (opts.conversationId) {
+                saveCheckpoint(opts.supabase, opts.conversationId, turnCount, messages, { input: totalIn, output: totalOut, cacheRead: cacheReadTokens, cacheCreation: cacheCreationTokens }, sessionCostUsd, allToolNames).catch(() => { }); // swallow — saveCheckpoint already logs internally
+            }
+        }
+    }
+    const fullText = allTextResponses.join("\n\n") || finalResponse;
+    return {
+        finalText: fullText,
+        allTextResponses,
+        turnCount,
+        toolCallCount,
+        toolsUsed: [...new Set(allToolNames)],
+        tokens: {
+            input: totalIn,
+            output: totalOut,
+            cacheCreation: cacheCreationTokens,
+            cacheRead: cacheReadTokens,
+        },
+        costUsd: sessionCostUsd,
+        loopDetectorStats: loopDetector.getSessionStats(),
+        turns: turnMetrics,
+        citations: allCitations,
+    };
+}
+// ============================================================================
+// TOOL EXECUTOR FACTORY — creates executor for dispatchTools with delegation
+// ============================================================================
+function makeToolExecutor(opts, tools, allToolNames, subagentTokens, discoveredToolNames) {
+    const { anthropic, supabase, storeId, traceId, userId, userEmail, conversationId, agentId, executeTool, onToolResult, onToolProgress, onSubagentProgress, clientDisconnected = { value: false }, startedAt = Date.now(), maxDurationMs = 5 * 60 * 1000, } = opts;
+    return async (name, input) => {
+        allToolNames.push(name);
+        // Subagent delegation
+        if (name === "delegate_task") {
+            const subPrompt = String(input.prompt || "");
+            const subModelInput = String(input.model || "haiku");
+            const subModel = (subModelInput === "opus" ? "opus" :
+                subModelInput === "sonnet" ? "sonnet" : "haiku");
+            const subMaxTurns = Math.min(Math.max(1, Number(input.max_turns) || 6), 12);
+            const subTools = tools.filter((t) => t.name !== "delegate_task");
+            const subId = `sub-${Date.now().toString(36)}`;
+            onSubagentProgress?.({ subagentId: subId, event: "started", model: subModel });
+            const subStartTime = Date.now();
+            const subResult = await runServerSubagent({
+                anthropic, supabase, storeId, prompt: subPrompt, model: subModel,
+                maxTurns: subMaxTurns, tools: subTools,
+                executeTool: async (toolName, args) => executeTool(toolName, args, "server_subagent"),
+                onProgress: onSubagentProgress, clientDisconnected, startedAt, maxDurationMs,
+            });
+            onSubagentProgress?.({ subagentId: subId, event: "done", output: subResult.output });
+            // Audit log
+            const subDurationMs = Date.now() - subStartTime;
+            const subModelId = subModel === "opus" ? MODELS.OPUS
+                : subModel === "sonnet" ? MODELS.SONNET : MODELS.HAIKU;
+            try {
+                const subEndTime = Date.now();
+                const subBytes = new Uint8Array(8);
+                crypto.getRandomValues(subBytes);
+                const subSpanId = Array.from(subBytes).map(b => b.toString(16).padStart(2, "0")).join("");
+                await supabase.from("audit_logs").insert({
+                    action: "chat.subagent_complete", severity: "info",
+                    store_id: storeId || null, resource_type: "chat_subagent",
+                    resource_id: agentId || null, request_id: traceId || null,
+                    conversation_id: conversationId || null, source: "server_subagent",
+                    user_id: userId || null, user_email: userEmail || null,
+                    input_tokens: subResult.tokensUsed.input, output_tokens: subResult.tokensUsed.output,
+                    total_cost: subResult.costUsd, model: subModelId, duration_ms: subDurationMs,
+                    // OTEL fields
+                    trace_id: traceId || null,
+                    span_id: subSpanId,
+                    span_kind: "INTERNAL",
+                    service_name: "agent-server",
+                    status_code: subResult.success ? "OK" : "ERROR",
+                    start_time: new Date(subEndTime - subDurationMs).toISOString(),
+                    end_time: new Date(subEndTime).toISOString(),
+                    details: {
+                        subagent_model: subModel, turn_count: subResult.turnCount,
+                        tool_calls: subResult.toolsUsed.length, tool_names: subResult.toolsUsed,
+                        cost_usd: subResult.costUsd, success: subResult.success,
+                        prompt_preview: subPrompt.substring(0, 200),
+                        // gen_ai fields for SwiftUI cost display
+                        "gen_ai.request.model": subModelId,
+                        "gen_ai.usage.input_tokens": subResult.tokensUsed.input,
+                        "gen_ai.usage.output_tokens": subResult.tokensUsed.output,
+                        "gen_ai.usage.cost": subResult.costUsd,
+                    },
+                });
+            }
+            catch (err) {
+                log.error({ err: err.message }, "failed to log subagent delegation audit");
+            }
+            subagentTokens.input += subResult.tokensUsed.input;
+            subagentTokens.output += subResult.tokensUsed.output;
+            subagentTokens.costUsd += subResult.costUsd;
+            allToolNames.push(...subResult.toolsUsed);
+            return { success: subResult.success, output: subResult.output };
+        }
+        // Regular tool execution — pass onToolProgress for streaming tools (kali)
+        const result = await executeTool(name, input, undefined, onToolProgress);
+        onToolResult?.(name, result.success, result.success ? result.data : result.error);
+        // discover_tools: dynamically add discovered tools to the active set
+        if (name === "discover_tools" && result.success && result.data) {
+            const refreshRequested = !!input.refresh;
+            const discovered = result.data?.tools;
+            // If refresh requested, remove previously-discovered tools so they can be re-loaded
+            // with fresh schemas from DB. Core tools and delegate_task are never removed.
+            if (refreshRequested) {
+                const coreNames = new Set((opts.tools || []).map(t => t.name));
+                coreNames.add("delegate_task");
+                for (let i = tools.length - 1; i >= 0; i--) {
+                    if (discoveredToolNames.has(tools[i].name) && !coreNames.has(tools[i].name)) {
+                        tools.splice(i, 1);
+                    }
+                }
+                discoveredToolNames.clear();
+                log.info("discover_tools refresh — cleared previously discovered tools");
+            }
+            if (Array.isArray(discovered)) {
+                // Use getFullToolSchemas as authoritative source — supplements handler response
+                // with any schemas the handler returned, ensuring we have complete definitions.
+                const discoveredNames = discovered.filter((t) => t.name).map((t) => t.name);
+                const fullSchemas = getFullToolSchemas(discoveredNames);
+                // Build a map for O(1) lookup: prefer full schemas from cache, fall back to handler data
+                const schemaMap = new Map();
+                for (const t of discovered) {
+                    if (t.name && t.input_schema) {
+                        schemaMap.set(t.name, { name: t.name, description: t.description || t.name, input_schema: t.input_schema });
+                    }
+                }
+                for (const t of fullSchemas) {
+                    schemaMap.set(t.name, t); // Full cache schemas override handler data (more complete)
+                }
+                const activated = [];
+                const alreadyActive = [];
+                for (const [toolName, toolDef] of schemaMap) {
+                    // Track as discovered regardless of whether already active
+                    discoveredToolNames.add(toolName);
+                    if (!tools.some(existing => existing.name === toolName)) {
+                        tools.push(toolDef);
+                        activated.push(toolName);
+                    }
+                    else if (refreshRequested) {
+                        // Re-add after refresh cleared it, or update existing schema
+                        tools.push(toolDef);
+                        activated.push(toolName);
+                    }
+                    else {
+                        alreadyActive.push(toolName);
+                    }
+                }
+                if (activated.length > 0) {
+                    log.info({ activatedTools: activated, refreshed: refreshRequested }, "discover_tools activated");
+                }
+                // Return a cleaner message to the model
+                return {
+                    success: true,
+                    output: JSON.stringify({
+                        activated,
+                        already_active: alreadyActive,
+                        refreshed: refreshRequested,
+                        message: activated.length > 0
+                            ? `Activated ${activated.length} tool(s): ${activated.join(", ")}. You can now use them.`
+                            : "Requested tools were already active.",
+                        total_discovered: discoveredToolNames.size,
+                    }),
+                };
+            }
+        }
+        return {
+            success: result.success,
+            output: JSON.stringify(result.success ? result.data : { error: result.error }),
+        };
+    };
+}