osborn 0.5.3 → 0.5.5

package/dist/fast-brain.js

@@ -1,32 +1,34 @@
 /**
- * Fast Brain Agent — Middle-tier intelligence for the Voice AI System
+ * Fast Brain — Central Orchestrator for the Voice AI System
  *
- * A fast intermediary between the realtime voice model and the Claude SDK agent.
- * Uses direct API calls for ~2 second responses.
+ * The sole intelligence layer between the user and all backend capabilities.
+ * The realtime voice model is a thin teleprompter — it speaks what this module returns.
  *
  * Capabilities:
  * - Read/write session files (spec.md + library/)
  * - Web search for quick factual lookups
  * - Record user decisions and preferences into spec.md
- * - Post-research: synthesize findings into spec.md
- * - Escalate to ask_agent when deeper research is needed
+ * - Trigger deep research (via callbacks to index.ts)
+ * - Generate teleprompter scripts for ALL voice output
+ * - Post-research: synthesize findings from JSONL into spec.md + voice scripts
+ * - Generate visual documents (comparison, diagram, analysis, summary)
  *
- * Key constraint: The fast brain NEVER calls ask_agent. The realtime model is always the router.
+ * Central function: askFastBrain() — ALL user questions route here.
+ * It returns a FastBrainResponse with a teleprompter script the voice model reads verbatim.
  *
  * Auth chain (tried in order):
  * 1. ANTHROPIC_API_KEY env var → Anthropic SDK (Haiku)
  * 2. ANTHROPIC_AUTH_TOKEN env var → Anthropic SDK (Haiku)
  * 3. GOOGLE_API_KEY env var → Gemini Flash fallback
- *
- * Note: Claude Code OAuth (macOS Keychain) was tested but Anthropic's Messages API
- * rejects OAuth tokens with 401 "OAuth authentication is currently not supported."
  */
 import Anthropic from '@anthropic-ai/sdk';
+import { query as sdkQuery, tool as sdkTool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
 import { GoogleGenAI } from '@google/genai';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
 import { dirname, basename } from 'path';
+import { z } from 'zod';
 import { getSessionWorkspace, readSessionSpec, listLibraryFiles } from './config.js';
-import { FAST_BRAIN_SYSTEM_PROMPT, CHUNK_PROCESS_SYSTEM, REFINEMENT_PROCESS_SYSTEM, AUGMENT_RESULT_SYSTEM, CONTEXTUALIZE_UPDATE_SYSTEM, PROACTIVE_PROMPT_SYSTEM, VISUAL_DOCUMENT_SYSTEM } from './prompts.js';
+import { FAST_BRAIN_SYSTEM_PROMPT, CHUNK_PROCESS_SYSTEM, REFINEMENT_PROCESS_SYSTEM, AUGMENT_RESULT_SYSTEM, CONTEXTUALIZE_UPDATE_SYSTEM, PROACTIVE_PROMPT_SYSTEM, VISUAL_DOCUMENT_SYSTEM, RESEARCH_COMPLETION_SYSTEM, buildFastBrainSdkPrompt } from './prompts.js';
 import { getRecentToolResults, readSessionHistory, getSubagentTranscripts, getConversationText, getSessionTranscripts, searchSessionJsonl, getSessionStats } from './session-access.js';
 // ============================================================
 // Content extraction — pulls useful snippets from tool responses
@@ -70,55 +72,81 @@ let initialized = false;
 // Model IDs — configurable per provider
 const ANTHROPIC_FAST_MODEL = 'claude-haiku-4-5-20251001';
 const GEMINI_FAST_MODEL = 'gemini-2.0-flash';
-/** No-op — history is now sourced live from agent.chatCtx, passed per-call */
+// Agent SDK session tracking — resume across voice questions for context continuity
+let fastBrainSessionId = null;
+// Gemini Chat session — persists across voice questions for context continuity.
+// The Chat object auto-manages full conversation history (messages + tool calls).
+// Cleared on disconnect/reconnect/session switch via clearFastBrainSession().
+let geminiChat = null;
+const MAX_FAST_BRAIN_HISTORY = 30;
+let fastBrainHistory = [];
+/** Clear fast brain session state — call on disconnect/reconnect/session switch */
+export function clearFastBrainSession() {
+    fastBrainSessionId = null;
+    geminiChat = null;
+    fastBrainHistory = [];
+    console.log('🧠 Fast brain: session cleared (SDK + Gemini chat + Anthropic history)');
+}
+/** @deprecated Use clearFastBrainSession() instead */
 export function clearFastBrainHistory() {
-    console.log('🧠 Fast brain: conversation history cleared (no-op — sourced from chatCtx)');
+    clearFastBrainSession();
 }
 function initProvider() {
     if (initialized)
         return;
     initialized = true;
-    // 1. ANTHROPIC_API_KEY
+    // Initialize fallback clients (Gemini for fallback, Anthropic direct API if key available)
+    const googleKey = process.env.GOOGLE_API_KEY;
+    if (googleKey) {
+        geminiClient = new GoogleGenAI({ apiKey: googleKey });
+    }
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (apiKey) {
         anthropicClient = new Anthropic({ apiKey });
-        provider = 'anthropic';
-        console.log('🧠 Fast brain: using Anthropic API (ANTHROPIC_API_KEY)');
-        return;
     }
-    // 2. ANTHROPIC_AUTH_TOKEN (if user sets it explicitly)
-    const authToken = process.env.ANTHROPIC_AUTH_TOKEN;
-    if (authToken) {
-        anthropicClient = new Anthropic({ authToken });
-        provider = 'anthropic';
-        console.log('🧠 Fast brain: using Anthropic API (ANTHROPIC_AUTH_TOKEN)');
-        return;
+    else {
+        const authToken = process.env.ANTHROPIC_AUTH_TOKEN;
+        if (authToken) {
+            anthropicClient = new Anthropic({ authToken });
+        }
     }
-    // NOTE: Claude Code OAuth (macOS Keychain) was tested but Anthropic's Messages API
-    // returns 401 "OAuth authentication is currently not supported." — cannot reuse it.
-    // 3. Gemini Flash fallback (uses GOOGLE_API_KEY already in .env)
-    const googleKey = process.env.GOOGLE_API_KEY;
-    if (googleKey) {
-        geminiClient = new GoogleGenAI({ apiKey: googleKey });
+    // PRIMARY: Gemini Flash — fastest (~1-2s), handles 1M tokens, no cold start.
+    // Agent SDK Haiku is too slow (~10-15s) due to CLI process spawn + session overhead.
+    if (geminiClient) {
         provider = 'gemini';
-        console.log(`🧠 Fast brain: using Gemini Flash fallback (${GEMINI_FAST_MODEL})`);
-        return;
+        console.log(`🧠 Fast brain: using Gemini Flash (primary) — fastest response time`);
+        if (anthropicClient) {
+            console.log(`🧠 Fast brain: Direct Anthropic API available as fallback`);
+        }
+    }
+    else if (anthropicClient) {
+        provider = 'anthropic';
+        console.log(`🧠 Fast brain: using Anthropic API (primary) — no Gemini key available`);
+    }
+    else {
+        // Last resort: Agent SDK is slow but functional
+        provider = 'agent-sdk';
+        console.log(`🧠 Fast brain: using Claude Agent SDK (fallback) — no API keys available`);
     }
-    // No provider available
-    provider = 'none';
-    console.error('⚠️ Fast brain: no API key available — fast brain disabled');
-    console.error('   Set ANTHROPIC_API_KEY or GOOGLE_API_KEY in agent/.env');
 }
 // ============================================================
 // Tool execution (shared across providers)
 // ============================================================
-function executeTool(toolName, toolInput, workspace, sessionId, workingDir) {
+// Track whether send_to_chat was called during a fast brain conversation.
+// If the LLM calls send_to_chat but returns no text, we use a fallback
+// instead of "No answer found."
+let sendToChatCalledThisTurn = false;
+function executeTool(toolName, toolInput, workspace, sessionId, workingDir, sendToChat) {
     try {
         switch (toolName) {
             case 'read_file': {
                 const relPath = toolInput.path;
                 if (relPath.includes('..'))
                     return 'Error: path traversal not allowed';
+                const ext = relPath.toLowerCase().split('.').pop() || '';
+                const BINARY_EXTS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'pdf', 'mp3', 'wav', 'mp4', 'mov'];
+                if (BINARY_EXTS.includes(ext))
+                    return `Binary file (${ext}) — cannot read as text.`;
                 const fullPath = `${workspace}/${relPath}`;
                 if (!existsSync(fullPath))
                     return `File not found: ${relPath}`;
@@ -273,6 +301,18 @@ ${toolList}`;
                 }
                 return output;
             }
+            case 'send_to_chat': {
+                const text = toolInput.text;
+                if (!text)
+                    return 'Error: text is required';
+                if (sendToChat) {
+                    console.log(`💬 [fast brain] send_to_chat: ${text.substring(0, 80)}...`);
+                    sendToChat(text);
+                    sendToChatCalledThisTurn = true;
+                    return `Sent to chat successfully. Now return a brief spoken summary — do NOT repeat the content you just sent.`;
+                }
+                return 'Error: chat sending not available';
+            }
             default:
                 return `Unknown tool: ${toolName}`;
         }
@@ -389,6 +429,17 @@ function buildAnthropicTools() {
             name: 'deep_read_text',
             description: 'Read ALL agent reasoning and analysis across the ENTIRE session — not just recent messages. Returns every piece of thinking, synthesis, comparison, and recommendation the agent produced. Use this for generating comprehensive overviews or when the user asks for detailed explanations of what the agent found.',
             input_schema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'send_to_chat',
+            description: 'Send formatted content to the user\'s chat panel. Use for URLs, links, lists, prices, code snippets, or anything that\'s better read than spoken. The content appears as a chat message in the frontend. You should STILL speak a brief summary — use this tool for the detailed/visual content.',
+            input_schema: {
+                type: 'object',
+                properties: {
+                    text: { type: 'string', description: 'The formatted text to display in chat. Supports markdown.' }
+                },
+                required: ['text']
+            }
         }
     ];
 }
@@ -521,6 +572,17 @@ function buildGeminiTools() {
                     name: 'deep_read_text',
                     description: 'Read ALL agent reasoning across the ENTIRE session. For comprehensive overviews or detailed explanations of what the agent found throughout the session.',
                     parameters: { type: 'object', properties: {} }
+                },
+                {
+                    name: 'send_to_chat',
+                    description: 'Send formatted content to the user\'s chat panel. Use for URLs, links, lists, prices, code snippets, or anything better read than spoken. Still speak a brief summary — use this for the detailed/visual content.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            text: { type: 'string', description: 'The formatted text to display in chat. Supports markdown.' }
+                        },
+                        required: ['text']
+                    }
                 }
             ]
         }
@@ -549,23 +611,150 @@ async function geminiWebSearch(query) {
     }
 }
 // ============================================================
-// Anthropic Q&A implementation
+// Agent SDK Q&A implementation — replaces direct Anthropic API for Q&A
 // ============================================================
-async function askViaAnthropic(question, workspace, researchContext, sessionId, workingDir, chatHistory) {
+/**
+ * Create an in-process MCP server with the send_to_chat tool for the Agent SDK fast brain.
+ */
+function createFastBrainMcpServer(sendToChat) {
+    const tools = [];
+    if (sendToChat) {
+        tools.push(sdkTool('send_to_chat', 'Send formatted content to the user\'s chat panel. Use for URLs, links, lists, prices, code snippets, tables, or anything better read than spoken. Supports markdown. You should STILL speak a brief summary — the chat content is supplementary.', { text: z.string().describe('The formatted text to display in chat. Supports markdown.') }, async ({ text }) => {
+            sendToChat(text);
+            sendToChatCalledThisTurn = true;
+            return { content: [{ type: 'text', text: 'Sent to chat. Now give a brief spoken summary of what you sent.' }] };
+        }));
+    }
+    return createSdkMcpServer({
+        name: 'osborn-fast-brain',
+        version: '1.0.0',
+        tools,
+    });
+}
+/**
+ * Ask via Claude Agent SDK — the agent traverses JSONL files natively using Read/Grep/Glob.
+ * Falls back to Gemini on timeout or error.
+ */
+async function askViaAgentSdk(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat, sessionBaseDir) {
+    sendToChatCalledThisTurn = false;
+    // Build the prompt with conversation context
+    let prompt = question;
+    if (researchContext) {
+        prompt += `\n\n[LIVE RESEARCH CONTEXT — the deep research agent is currently working]\n${researchContext}`;
+    }
+    if (chatHistory && chatHistory.length > 0) {
+        const historyStr = chatHistory.slice(-15).map(t => `${t.role}: ${t.text}`).join('\n');
+        prompt = `[Recent voice conversation]\n${historyStr}\n\n[Current question]\n${prompt}`;
+    }
+    // Create MCP server for send_to_chat
+    const mcpServer = createFastBrainMcpServer(sendToChat);
+    // Build system prompt with computed paths
+    const systemPrompt = buildFastBrainSdkPrompt(workingDir || workspace, sessionId || '', sessionBaseDir || workingDir || workspace);
+    // Tools: Read/Write/Edit for files, Grep/Glob for search, WebSearch/WebFetch for web
+    const toolNames = ['Read', 'Write', 'Edit', 'Grep', 'Glob', 'WebSearch', 'WebFetch'];
+    const mcpToolPatterns = sendToChat ? ['mcp__osborn-fast-brain__*'] : [];
+    const options = {
+        model: ANTHROPIC_FAST_MODEL,
+        cwd: workingDir,
+        systemPrompt,
+        maxTurns: 8,
+        tools: toolNames,
+        allowedTools: [...toolNames, ...mcpToolPatterns],
+        mcpServers: { 'osborn-fast-brain': mcpServer },
+    };
+    if (fastBrainSessionId) {
+        options.resume = fastBrainSessionId;
+    }
+    // Run with 15s timeout — falls back to Gemini on timeout
+    const TIMEOUT_MS = 15000;
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error('fast-brain-timeout')), TIMEOUT_MS);
+    });
+    const queryPromise = (async () => {
+        let result = '';
+        try {
+            for await (const message of sdkQuery({ prompt, options })) {
+                if (message.type === 'result') {
+                    result = message.result || '';
+                }
+                // Capture session ID eagerly — even if we timeout, next call can resume
+                if (message.type === 'assistant' && message.session_id) {
+                    const sid = message.session_id;
+                    if (sid !== fastBrainSessionId) {
+                        fastBrainSessionId = sid;
+                        console.log(`🧠 Fast brain session: ${sid.substring(0, 12)}... (${options.resume ? 'resumed' : 'new'})`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.error('❌ Agent SDK query error:', err);
+            throw err;
+        }
+        clearTimeout(timeoutHandle);
+        return result;
+    })();
+    try {
+        const result = await Promise.race([queryPromise, timeoutPromise]);
+        if (!result || result.trim().length === 0) {
+            if (sendToChatCalledThisTurn)
+                return "I've sent the details to your chat panel.";
+            return 'No answer found.';
+        }
+        console.log(`🧠 Agent SDK fast brain: ${result.length} chars (session: ${fastBrainSessionId?.substring(0, 8) || 'new'})`);
+        return result;
+    }
+    catch (err) {
+        clearTimeout(timeoutHandle);
+        if (err.message === 'fast-brain-timeout') {
+            console.log('⏱️ Agent SDK fast brain timed out (15s), falling back to Gemini');
+        }
+        else {
+            console.error('❌ Agent SDK fast brain error:', err.message || err);
+        }
+        // Fall back to Gemini if available
+        if (geminiClient) {
+            console.log('🔄 Falling back to Gemini fast brain');
+            return askViaGemini(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat);
+        }
+        // Fall back to direct Anthropic API if no Gemini
+        if (anthropicClient) {
+            console.log('🔄 Falling back to direct Anthropic API');
+            return askViaAnthropic(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat);
+        }
+        return 'Fast brain unavailable. Try asking me to research it.';
+    }
+}
+// ============================================================
+// Direct Anthropic API Q&A — kept as fallback for Agent SDK failures
+// ============================================================
+async function askViaAnthropic(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat) {
     const client = anthropicClient;
     const tools = buildAnthropicTools();
+    sendToChatCalledThisTurn = false;
     const userContent = researchContext
         ? `${question}\n\n[LIVE RESEARCH CONTEXT — the research agent is currently working]\n${researchContext}`
         : question;
-    // Build messages from live voice conversation history (from agent.chatCtx)
+    // Build messages: persistent fast brain history + live voice history + current question
     const messages = [];
+    // 1. Inject persistent fast brain history (prior exchanges from this session)
+    for (const exchange of fastBrainHistory) {
+        messages.push({ role: 'user', content: exchange.question });
+        messages.push({ role: 'assistant', content: exchange.answer });
+    }
+    // 2. Inject live voice conversation history (from agent.chatCtx — what user/model actually said)
     if (chatHistory && chatHistory.length > 0) {
         for (const turn of chatHistory) {
             messages.push({ role: turn.role, content: turn.text });
         }
     }
+    // 3. Current question
     messages.push({ role: 'user', content: userContent });
     const allTools = [...tools, ANTHROPIC_WEB_SEARCH];
+    const noAnswerFallback = () => sendToChatCalledThisTurn
+        ? "I've sent the details to your chat panel."
+        : 'No answer found.';
     for (let i = 0; i < 10; i++) {
         const response = await client.messages.create({
             model: ANTHROPIC_FAST_MODEL,
@@ -576,70 +765,97 @@ async function askViaAnthropic(question, workspace, researchContext, sessionId,
         });
         if (response.stop_reason === 'end_turn') {
             const textBlock = response.content.find((b) => b.type === 'text');
-            return textBlock?.text || 'No answer found.';
+            const answer = textBlock?.text || noAnswerFallback();
+            // Persist this exchange for future calls
+            fastBrainHistory.push({ question: userContent, answer });
+            if (fastBrainHistory.length > MAX_FAST_BRAIN_HISTORY)
+                fastBrainHistory.shift();
+            return answer;
         }
         const toolUseBlocks = response.content.filter((b) => b.type === 'tool_use');
         if (toolUseBlocks.length === 0 && response.stop_reason !== 'tool_use') {
             const textBlock = response.content.find((b) => b.type === 'text');
-            return textBlock?.text || 'No answer found.';
+            const answer = textBlock?.text || noAnswerFallback();
+            fastBrainHistory.push({ question: userContent, answer });
+            if (fastBrainHistory.length > MAX_FAST_BRAIN_HISTORY)
+                fastBrainHistory.shift();
+            return answer;
         }
         messages.push({ role: 'assistant', content: response.content });
         if (toolUseBlocks.length > 0) {
             const toolResults = toolUseBlocks.map(toolUse => ({
                 type: 'tool_result',
                 tool_use_id: toolUse.id,
-                content: executeTool(toolUse.name, toolUse.input, workspace, sessionId, workingDir),
+                content: executeTool(toolUse.name, toolUse.input, workspace, sessionId, workingDir, sendToChat),
             }));
             messages.push({ role: 'user', content: toolResults });
         }
     }
+    if (sendToChatCalledThisTurn) {
+        const answer = "I've sent the full details to your chat. Let me know if you want to dive deeper into anything.";
+        fastBrainHistory.push({ question: userContent, answer });
+        if (fastBrainHistory.length > MAX_FAST_BRAIN_HISTORY)
+            fastBrainHistory.shift();
+        return answer;
+    }
     return 'Fast brain reached maximum tool iterations. Try ask_agent for a deeper search.';
 }
 // ============================================================
 // Gemini Q&A implementation
 // ============================================================
-async function askViaGemini(question, workspace, researchContext, sessionId, workingDir, chatHistory) {
+async function askViaGemini(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat, sessionBaseDir) {
     const ai = geminiClient;
     const tools = buildGeminiTools();
+    sendToChatCalledThisTurn = false;
     const userContent = researchContext
         ? `${question}\n\n[LIVE RESEARCH CONTEXT — the research agent is currently working]\n${researchContext}`
         : question;
-    // Build contents from live voice conversation history (from agent.chatCtx)
-    const contents = [];
-    if (chatHistory && chatHistory.length > 0) {
-        for (const turn of chatHistory) {
-            contents.push({
-                role: turn.role === 'assistant' ? 'model' : 'user',
-                parts: [{ text: turn.text }],
-            });
+    // Create or reuse persistent Gemini Chat session.
+    // The Chat object auto-manages full conversation history (messages + tool calls).
+    // Cleared on disconnect/reconnect/session switch via clearFastBrainSession().
+    if (!geminiChat) {
+        // Seed with live voice conversation history so Gemini knows what user/model said
+        const history = [];
+        if (chatHistory && chatHistory.length > 0) {
+            for (const turn of chatHistory) {
+                history.push({
+                    role: turn.role === 'assistant' ? 'model' : 'user',
+                    parts: [{ text: turn.text }],
+                });
+            }
         }
-    }
-    contents.push({ role: 'user', parts: [{ text: userContent }] });
-    for (let i = 0; i < 10; i++) {
-        const response = await ai.models.generateContent({
+        geminiChat = ai.chats.create({
             model: GEMINI_FAST_MODEL,
-            contents,
             config: {
                 systemInstruction: FAST_BRAIN_SYSTEM_PROMPT,
                 tools,
-            }
+            },
+            history,
         });
+        console.log(`🧠 Gemini fast brain: new chat session (history: ${history.length} turns)`);
+    }
+    // Send user message via the persistent chat — history accumulates automatically.
+    // The Chat object tracks all messages + tool calls internally.
+    let response = await geminiChat.sendMessage({ message: userContent });
+    // Tool call loop: execute tools and send results back, up to 10 rounds
+    for (let i = 0; i < 10; i++) {
         const functionCalls = response.functionCalls;
         if (!functionCalls || functionCalls.length === 0) {
-            return response.text || 'No answer found.';
+            const text = response.text;
+            if (text)
+                return text;
+            if (sendToChatCalledThisTurn)
+                return "I've sent the details to your chat panel.";
+            return 'No answer found.';
         }
-        // Add model response to conversation
-        if (response.candidates?.[0]?.content) {
-            contents.push(response.candidates[0].content);
-        }
-        // Execute tools and send results back (web_search is async, others are sync)
+        // Execute tools
         const functionResponses = await Promise.all(functionCalls.map(async (call) => {
             let result;
             if (call.name === 'web_search') {
                 result = await geminiWebSearch(call.args?.query || question);
             }
             else {
-                result = executeTool(call.name, call.args || {}, workspace, sessionId, workingDir);
+                result = executeTool(call.name, call.args || {}, workspace, sessionId, workingDir, sendToChat);
             }
             return {
                 functionResponse: {
@@ -648,7 +864,11 @@ async function askViaGemini(question, workspace, researchContext, sessionId, wor
                 }
             };
         }));
-        contents.push({ role: 'user', parts: functionResponses });
+        // Send tool results back — chat auto-tracks the full exchange
+        response = await geminiChat.sendMessage({ message: functionResponses });
+    }
+    if (sendToChatCalledThisTurn) {
+        return "I've sent the full details to your chat. Let me know if you want to dive deeper into anything.";
     }
     return 'Fast brain reached maximum tool iterations. Try ask_agent for a deeper search.';
 }
@@ -664,19 +884,181 @@ async function askViaGemini(question, workspace, researchContext, sessionId, wor
  * @param researchContext - Optional snapshot of the live research log.
  * ~2 second response time for most queries.
  */
-export async function askHaiku(workingDir, sessionId, question, researchContext, chatHistory) {
+export async function askHaiku(workingDir, sessionId, question, researchContext, chatHistory, sendToChat, sessionBaseDir) {
     initProvider();
-    if (provider === 'none') {
-        return 'NEEDS_DEEPER_RESEARCH: Fast brain unavailable (no API key). Try ask_agent instead.';
+    // workspace uses sessionBaseDir (Osborn install dir) for spec.md/library
+    // workingDir is for JSONL access (matches Claude SDK cwd)
+    const wsDir = sessionBaseDir || workingDir;
+    const workspace = getSessionWorkspace(wsDir, sessionId);
+    // Primary: Gemini Flash (~1-2s) with pre-loaded JSONL context
+    // Fallback: Anthropic direct API or Agent SDK (slower but functional)
+    if (provider === 'gemini') {
+        return askViaGemini(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat, wsDir);
     }
-    const workspace = getSessionWorkspace(workingDir, sessionId);
-    if (provider === 'anthropic') {
-        return askViaAnthropic(question, workspace, researchContext, sessionId, workingDir, chatHistory);
+    else if (provider === 'anthropic' || provider === 'agent-sdk') {
+        return askViaAgentSdk(question, workspace, researchContext, sessionId, workingDir, chatHistory, sendToChat, wsDir);
     }
     else {
-        return askViaGemini(question, workspace, researchContext, sessionId, workingDir, chatHistory);
+        return 'NEEDS_DEEPER_RESEARCH: Fast brain unavailable (no API key or CLI auth). Try ask_agent instead.';
     }
 }
+let researchTaskCounter = 0;
+/**
+ * Central orchestrator — ALL user questions from the realtime model come here.
+ * Routes to: direct answer, research triggering, decision recording, or document generation.
+ * Returns a teleprompter script the voice model reads verbatim.
+ */
+export async function askFastBrain(workingDir, sessionId, question, opts) {
+    const { chatHistory, researchContext, callbacks } = opts;
+    const wsDir = opts.sessionBaseDir || workingDir;
+    // Detect document generation requests
+    const docMatch = detectDocumentRequest(question);
+    if (docMatch) {
+        try {
+            const result = await generateVisualDocument(workingDir, sessionId, question, docMatch, wsDir);
+            if (result) {
+                const fullPath = `${wsDir}/.osborn/sessions/${sessionId}/library/${result.fileName}`;
+                callbacks.sendToFrontend({
+                    type: 'research_artifact_updated',
+                    filePath: fullPath,
+                    fileName: result.fileName,
+                });
+                return {
+                    script: `I've created a ${docMatch} document called ${result.fileName}. You can see it in the files panel.`,
+                    type: 'answer',
+                };
+            }
+        }
+        catch (err) {
+            console.error('❌ askFastBrain: document generation failed:', err);
+        }
+        // Fall through to regular handling if document gen fails
+    }
+    // Create sendToChat wrapper that sends assistant_response to frontend
+    const sendToChat = (text) => {
+        callbacks.sendToFrontend({ type: 'assistant_response', text });
+    };
+    // Core: ask the fast brain LLM
+    const answer = await askHaiku(workingDir, sessionId, question, researchContext, chatHistory, sendToChat, wsDir);
+    // Parse the response to determine routing
+    if (answer.startsWith('RECORDED:') || answer.includes('\nRECORDED:')) {
+        // Decision was recorded — extract the confirmation
+        const recordedLine = answer.split('\n').find(l => l.startsWith('RECORDED:'));
+        const confirmation = recordedLine
+            ? recordedLine.replace('RECORDED:', '').trim()
+            : 'Got it, noted.';
+        // Notify frontend about spec update
+        const specPath = `${wsDir}/.osborn/sessions/${sessionId}/spec.md`;
+        callbacks.sendToFrontend({
+            type: 'research_artifact_updated',
+            filePath: specPath,
+            fileName: 'spec.md',
+        });
+        return { script: confirmation, type: 'recorded' };
+    }
+    // Handle ASK_USER — questions directed at the user (not research tasks)
+    if (answer.startsWith('ASK_USER:') || answer.includes('\nASK_USER:')) {
+        const askLine = answer.split('\n').find(l => l.includes('ASK_USER:'));
+        const userQuestion = askLine
+            ? askLine.replace(/^ASK_USER:\s*/, '').trim()
+            : answer.replace(/^ASK_USER:\s*/, '').trim();
+        return { script: userQuestion, type: 'question' };
+    }
+    if (answer.includes('NEEDS_DEEPER_RESEARCH')) {
+        // Extract the research task context
+        const needsLine = answer.split('\n').find(l => l.includes('NEEDS_DEEPER_RESEARCH'));
+        const contextLine = answer.split('\n').find(l => l.startsWith('CONTEXT:'));
+        const researchTask = needsLine
+            ? needsLine.replace(/^(PARTIAL:\s*)?NEEDS_DEEPER_RESEARCH:\s*/, '').trim()
+            : question;
+        const contextStr = contextLine ? contextLine.replace('CONTEXT:', '').trim() : '';
+        // Safety check: if the "research task" looks like a question for the user
+        // (ends with ?, asks about preferences/needs, is very short), treat it as ASK_USER instead.
+        // This catches the common Gemini bug where clarification questions are formatted as research tasks.
+        const taskLower = researchTask.toLowerCase();
+        const looksLikeUserQuestion = (researchTask.endsWith('?') && (taskLower.includes('would you') ||
+            taskLower.includes('do you') ||
+            taskLower.includes('could you') ||
+            taskLower.includes('what kind of') ||
+            taskLower.includes('which') ||
+            taskLower.includes('your needs') ||
+            taskLower.includes('your preference') ||
+            taskLower.includes('more details') ||
+            taskLower.includes('clarif') ||
+            taskLower.includes('specify') ||
+            taskLower.includes('interested in') ||
+            researchTask.length < 80 // Very short "tasks" ending in ? are almost always user questions
+        ));
+        if (looksLikeUserQuestion) {
+            console.log(`🧠 [fast brain] Caught question-as-research-task, redirecting to ASK_USER: "${researchTask.substring(0, 100)}"`);
+            return { script: researchTask, type: 'question' };
+        }
+        const fullTask = contextStr ? `${researchTask}\n\nContext: ${contextStr}` : researchTask;
+        // Extract any partial answer (spoken script before NEEDS_DEEPER_RESEARCH)
+        const partialMatch = answer.match(/^PARTIAL:\s*([\s\S]*?)(?=\nNEEDS_DEEPER_RESEARCH)/m);
+        const partialScript = partialMatch ? partialMatch[1].trim() : '';
+        // Generate a task ID for frontend tracking
+        researchTaskCounter++;
+        const taskId = `research-${researchTaskCounter}-${Date.now()}`;
+        // Trigger research in background
+        callbacks.triggerResearch(fullTask);
+        callbacks.sendToFrontend({
+            type: 'research_task_started',
+            task: researchTask.substring(0, 200),
+            taskId,
+        });
+        // Generate acknowledgment script
+        let script;
+        if (partialScript) {
+            script = `${partialScript} Let me dig deeper on the rest.`;
+        }
+        else {
+            // Generate a contextual ack based on conversation flow
+            script = generateResearchAck(question, chatHistory);
+        }
+        return { script, type: 'research_started' };
+    }
+    // Direct answer — the response IS the teleprompter script
+    return { script: answer, type: 'answer' };
+}
+/** Detect if the user's question is an EXPLICIT document generation request.
+ * Must be very specific — don't catch general questions about analysis or comparisons.
+ * Only triggers when the user explicitly asks for a written document/artifact. */
+function detectDocumentRequest(question) {
+    const q = question.toLowerCase();
+    // Only match explicit document requests — "create a comparison", "make a diagram", "write a summary"
+    // Do NOT match: "compare X and Y", "analyze the code", "give me an overview"
+    const docVerbs = /(create|make|generate|write|build|produce|draw)\s+(a\s+|an\s+|the\s+)?/;
+    if (!docVerbs.test(q))
+        return null;
+    if (q.includes('comparison') || q.includes('comparison table') || q.includes('comparison document'))
+        return 'comparison';
+    if (q.includes('diagram') || q.includes('flow chart') || q.includes('architecture diagram'))
+        return 'diagram';
+    if (q.includes('analysis document') || q.includes('tradeoff document'))
+        return 'analysis';
+    if (q.includes('summary document') || q.includes('overview document'))
+        return 'summary';
+    return null;
+}
+/** Generate a natural research acknowledgment based on conversation context */
+function generateResearchAck(question, chatHistory) {
+    // Use simple heuristics for a natural ack — no LLM call needed
+    const q = question.toLowerCase();
+    if (q.includes('how') && (q.includes('work') || q.includes('implement'))) {
+        return "Let me look into how that works. I'll have the details for you shortly.";
+    }
+    if (q.includes('what') && (q.includes('option') || q.includes('available') || q.includes('choice'))) {
+        return "Let me research the options for you.";
+    }
+    if (q.includes('why') || q.includes('explain')) {
+        return "Good question. Let me dig into that.";
+    }
+    if (q.includes('find') || q.includes('search') || q.includes('look')) {
+        return "On it. Give me a moment to look into that.";
+    }
+    return "Let me research that for you. I'll have findings shortly.";
+}
 // ============================================================
 // processResearchChunk — Incremental content processing during research
 // ============================================================
@@ -686,7 +1068,7 @@ export async function askHaiku(workingDir, sessionId, question, researchContext,
  *
  * @param isRefinement - true for the final post-research consolidation pass (higher token budget)
  */
-export async function processResearchChunk(workingDir, sessionId, task, contentChunks, isRefinement) {
+export async function processResearchChunk(workingDir, sessionId, task, contentChunks, isRefinement, sessionBaseDir) {
     initProvider();
     if (provider === 'none')
         return null;
@@ -698,8 +1080,9 @@ export async function processResearchChunk(workingDir, sessionId, task, contentC
         return null;
     }
     specUpdateInProgress = true;
+    const wsDir = sessionBaseDir || workingDir;
     try {
-        const workspace = getSessionWorkspace(workingDir, sessionId);
+        const workspace = getSessionWorkspace(wsDir, sessionId);
         const specPath = `${workspace}/spec.md`;
         if (!existsSync(specPath)) {
             console.log('⚠️ processResearchChunk: spec.md not found, skipping');
@@ -711,7 +1094,7 @@ export async function processResearchChunk(workingDir, sessionId, task, contentC
         // Mid-research: skip library entirely to stay fast and avoid file proliferation
         let existingSection = '';
         if (isRefinement) {
-            const existingFiles = listLibraryFiles(workingDir, sessionId);
+            const existingFiles = listLibraryFiles(wsDir, sessionId);
             const existingContents = [];
             for (const file of existingFiles) {
                 const filePath = `${libraryDir}/${file}`;
@@ -744,7 +1127,7 @@ ${chunksText}
 
 Return ONLY valid JSON — no code fences, no explanation.`;
         let responseText = null;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             const response = await anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: isRefinement ? 20000 : 10000,
@@ -753,7 +1136,7 @@ Return ONLY valid JSON — no code fences, no explanation.`;
             });
             responseText = response.content[0].type === 'text' ? response.content[0].text : null;
         }
-        else {
+        else if (geminiClient) {
             const response = await geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
@@ -886,7 +1269,7 @@ ${specSection}${libSection}
 
 Augment the agent's findings with relevant context from the spec. Pass ALL details through verbatim.`;
         let responseText = null;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             const response = await anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: 16000,
@@ -895,7 +1278,7 @@ Augment the agent's findings with relevant context from the spec. Pass ALL detai
             });
             responseText = response.content[0].type === 'text' ? response.content[0].text : null;
         }
-        else {
+        else if (geminiClient) {
             const response = await geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
@@ -931,7 +1314,7 @@ Augment the agent's findings with relevant context from the spec. Pass ALL detai
  *
  * Returns { spec, libraryFiles } or null if update failed.
  */
-export async function updateSpecFromJSONL(workingDir, sessionId, task, researchLog) {
+export async function updateSpecFromJSONL(workingDir, sessionId, task, researchLog, sessionBaseDir) {
     initProvider();
     if (provider === 'none')
         return null;
@@ -983,7 +1366,7 @@ export async function updateSpecFromJSONL(workingDir, sessionId, task, researchL
         const totalChars = contentChunks.reduce((sum, c) => sum + c.length, 0);
         console.log(`📖 updateSpecFromJSONL: read ${toolResults.length} tool results, ${agentTexts.length} agent messages, ${subagents.length} sub-agents (${totalChars} total chars)`);
         // 3. Pass to processResearchChunk with isRefinement=true
-        return processResearchChunk(workingDir, sessionId, task, contentChunks, true);
+        return processResearchChunk(workingDir, sessionId, task, contentChunks, true, sessionBaseDir);
     }
     catch (err) {
         console.error('❌ updateSpecFromJSONL failed:', err);
@@ -1027,7 +1410,7 @@ Rules:
 - Output ONLY the full spec.md content or the word SKIP — nothing else`;
         const userMessage = `Current spec.md:\n\`\`\`\n${currentSpec}\n\`\`\`\n\nNew user question to track:\n"${question}"`;
         let responseText = null;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             const response = await anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: 8000,
@@ -1036,7 +1419,7 @@ Rules:
             });
             responseText = response.content[0].type === 'text' ? response.content[0].text : null;
         }
-        else {
+        else if (geminiClient) {
             const response = await geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
@@ -1123,7 +1506,7 @@ Rules:
         const truncatedOutput = output.length > 15000 ? output.substring(0, 15000) + '\n[... truncated]' : output;
         const userMessage = `Current spec.md:\n\`\`\`\n${currentSpec}\n\`\`\`\n\nAgent output (${outputType}):\n\`\`\`\n${truncatedOutput}\n\`\`\``;
         let responseText = null;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             const response = await anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: 8000,
@@ -1132,7 +1515,7 @@ Rules:
             });
             responseText = response.content[0].type === 'text' ? response.content[0].text : null;
         }
-        else {
+        else if (geminiClient) {
             const response = await geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
@@ -1168,12 +1551,13 @@ Rules:
  * Returns a natural 1-2 sentence update, or null if nothing interesting to say.
  * 3-second timeout — returns null if the LLM is too slow.
  */
-export async function contextualizeResearchUpdate(workingDir, sessionId, task, batchEvents, researchLog) {
+export async function contextualizeResearchUpdate(workingDir, sessionId, task, batchEvents, researchLog, chatHistory, sessionBaseDir) {
     initProvider();
     if (provider === 'none')
         return null;
+    const wsDir = sessionBaseDir || workingDir;
     try {
-        const specContent = readSessionSpec(workingDir, sessionId);
+        const specContent = readSessionSpec(wsDir, sessionId);
         const specTruncated = specContent ? specContent.substring(0, 1500) : '';
         // Read last 5 tool results for what was just found
         const recentResults = getRecentToolResults(sessionId, workingDir, 5);
@@ -1194,7 +1578,7 @@ ${resultsSummary}
 ${specTruncated ? `Spec context:\n${specTruncated}` : ''}`;
         const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(null), 3000));
         let responsePromise;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             responsePromise = anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: 200,
@@ -1202,13 +1586,16 @@ ${specTruncated ? `Spec context:\n${specTruncated}` : ''}`;
                 messages: [{ role: 'user', content: userMessage }]
             }).then(r => r.content[0].type === 'text' ? r.content[0].text : null);
         }
-        else {
+        else if (geminiClient) {
             responsePromise = geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
                 config: { systemInstruction: CONTEXTUALIZE_UPDATE_SYSTEM }
             }).then(r => r.text || null);
         }
+        else {
+            return null;
+        }
         const result = await Promise.race([responsePromise, timeoutPromise]);
         if (!result || result.trim() === 'NOTHING')
             return null;
@@ -1230,12 +1617,13 @@ ${specTruncated ? `Spec context:\n${specTruncated}` : ''}`;
  * Returns null/NOTHING if nothing interesting to say.
  * 3-second timeout.
  */
-export async function generateProactivePrompt(workingDir, sessionId, task, researchLog, previousPrompts) {
+export async function generateProactivePrompt(workingDir, sessionId, task, researchLog, previousPrompts, sessionBaseDir) {
     initProvider();
     if (provider === 'none')
         return null;
+    const wsDir = sessionBaseDir || workingDir;
     try {
-        const specContent = readSessionSpec(workingDir, sessionId);
+        const specContent = readSessionSpec(wsDir, sessionId);
         const specTruncated = specContent ? specContent.substring(0, 2000) : '';
         // Read recent discoveries from JSONL
         const recentResults = getRecentToolResults(sessionId, workingDir, 8);
@@ -1269,7 +1657,7 @@ Previous things already said (DO NOT repeat):
 ${previousPrompts.length > 0 ? previousPrompts.join('\n') : '(none yet)'}`;
         const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(null), 3000));
         let responsePromise;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             responsePromise = anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: 200,
@@ -1277,13 +1665,16 @@ ${previousPrompts.length > 0 ? previousPrompts.join('\n') : '(none yet)'}`;
                 messages: [{ role: 'user', content: userMessage }]
             }).then(r => r.content[0].type === 'text' ? r.content[0].text : null);
         }
-        else {
+        else if (geminiClient) {
             responsePromise = geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
                 config: { systemInstruction: PROACTIVE_PROMPT_SYSTEM }
             }).then(r => r.text || null);
         }
+        else {
+            return null;
+        }
         const result = await Promise.race([responsePromise, timeoutPromise]);
         if (!result || result.trim() === 'NOTHING')
             return null;
@@ -1304,14 +1695,15 @@ ${previousPrompts.length > 0 ? previousPrompts.join('\n') : '(none yet)'}`;
  * Reads spec.md, JSONL results, and library for context.
  * Writes the result to library/ and returns the filename + content.
  */
-export async function generateVisualDocument(workingDir, sessionId, request, documentType) {
+export async function generateVisualDocument(workingDir, sessionId, request, documentType, sessionBaseDir) {
     initProvider();
     if (provider === 'none')
         return null;
+    const wsDir = sessionBaseDir || workingDir;
     try {
-        const workspace = getSessionWorkspace(workingDir, sessionId);
-        const specContent = readSessionSpec(workingDir, sessionId) || '';
-        const libraryFiles = listLibraryFiles(workingDir, sessionId);
+        const workspace = getSessionWorkspace(wsDir, sessionId);
+        const specContent = readSessionSpec(wsDir, sessionId) || '';
+        const libraryFiles = listLibraryFiles(wsDir, sessionId);
         // Read library contents for context
         const libraryDir = `${workspace}/library`;
         const libraryContents = [];
@@ -1344,7 +1736,7 @@ ${toolResultsSummary}
 
 Return JSON: {"fileName": "descriptive-name.md", "content": "full markdown content"}`;
         let responseText = null;
-        if (provider === 'anthropic') {
+        if (anthropicClient) {
             const response = await anthropicClient.messages.create({
                 model: ANTHROPIC_FAST_MODEL,
                 max_tokens: 16000,
@@ -1353,7 +1745,7 @@ Return JSON: {"fileName": "descriptive-name.md", "content": "full markdown conte
             });
             responseText = response.content[0].type === 'text' ? response.content[0].text : null;
         }
-        else {
+        else if (geminiClient) {
             const response = await geminiClient.models.generateContent({
                 model: GEMINI_FAST_MODEL,
                 contents: userMessage,
@@ -1402,3 +1794,174 @@ Return JSON: {"fileName": "descriptive-name.md", "content": "full markdown conte
         return null;
     }
 }
+// ============================================================
+// processResearchCompletion — Generate teleprompter script from research results
+// ============================================================
+/**
+ * Generate a complete teleprompter script from research results.
+ * Replaces augmentResearchResult + extractPriorityContent.
+ * Reads full JSONL and produces a spoken monologue.
+ */
+export async function processResearchCompletion(workingDir, sessionId, task, agentResult, chatHistory, sendToChat, sessionBaseDir) {
+    initProvider();
+    if (provider === 'none')
+        return agentResult.substring(0, 500);
+    const wsDir = sessionBaseDir || workingDir;
+    try {
+        // Read spec for context
+        const specContent = readSessionSpec(wsDir, sessionId) || '';
+        // Read FULL JSONL data — not truncated. The user waited for this research;
+        // give the completion generator the complete picture.
+        const toolResults = getRecentToolResults(sessionId, workingDir, 30);
+        const toolSummary = toolResults.map(tr => {
+            const inputPreview = JSON.stringify(tr.toolInput).substring(0, 200);
+            return `[${tr.toolName}: ${inputPreview}]\n${tr.resultContent}`;
+        }).join('\n\n---\n\n');
+        // Also read agent reasoning for synthesis context
+        const agentTexts = readSessionHistory(sessionId, workingDir, {
+            lastN: 20,
+            types: ['assistant']
+        }).filter(m => m.text && m.text.length > 30)
+            .map(m => m.text)
+            .join('\n\n');
+        // Read sub-agent findings if any
+        const subagents = getSubagentTranscripts(sessionId, workingDir);
+        const subagentSummary = subagents.length > 0
+            ? subagents.map(sa => {
+                const texts = sa.messages.filter(m => m.text && m.text.length > 30).map(m => m.text);
+                return `[Sub-agent ${sa.taskId}]\n${texts.join('\n')}`;
+            }).join('\n\n')
+            : '';
+        const historyStr = chatHistory
+            ? chatHistory.slice(-10).map(t => `${t.role}: ${t.text}`).join('\n')
+            : '';
+        const userMessage = `Research task: "${task}"
+
+Agent's headline findings:
+${agentResult}
+
+Full tool outputs (${toolResults.length} results):
+${toolSummary}
+
+${agentTexts ? `Agent reasoning and analysis:\n${agentTexts.substring(0, 8000)}` : ''}
+
+${subagentSummary ? `Sub-agent findings:\n${subagentSummary.substring(0, 4000)}` : ''}
+
+${specContent ? `Session spec (for context):\n${specContent.substring(0, 3000)}` : ''}
+
+${historyStr ? `Recent conversation (match this vocabulary):\n${historyStr}` : ''}
+
+Write the spoken monologue now. The user waited for this research — be comprehensive.${sendToChat ? ' If you have structured data (lists, URLs, code, steps), include a CHAT_CONTENT section at the end after a line "---CHAT---" with markdown content to send to the chat panel.' : ''}`;
+        let script = null;
+        if (anthropicClient) {
+            const response = await anthropicClient.messages.create({
+                model: ANTHROPIC_FAST_MODEL,
+                max_tokens: 4000,
+                system: RESEARCH_COMPLETION_SYSTEM,
+                messages: [{ role: 'user', content: userMessage }]
+            });
+            script = response.content[0].type === 'text' ? response.content[0].text : null;
+        }
+        else if (geminiClient) {
+            const response = await geminiClient.models.generateContent({
+                model: GEMINI_FAST_MODEL,
+                contents: userMessage,
+                config: { systemInstruction: RESEARCH_COMPLETION_SYSTEM }
+            });
+            script = response.text || null;
+        }
+        if (!script)
+            return agentResult.substring(0, 500);
+        // Check for chat content section
+        if (sendToChat && script.includes('---CHAT---')) {
+            const parts = script.split('---CHAT---');
+            const spokenPart = parts[0].trim();
+            const chatPart = parts[1]?.trim();
+            if (chatPart) {
+                console.log(`💬 processResearchCompletion: sending ${chatPart.length} chars to chat`);
+                sendToChat(chatPart);
+            }
+            console.log(`🎙️ processResearchCompletion: generated ${spokenPart.length} char script + ${chatPart?.length || 0} char chat content`);
+            return spokenPart;
+        }
+        console.log(`🎙️ processResearchCompletion: generated ${script.length} char script`);
+        return script;
+    }
+    catch (err) {
+        console.error('❌ processResearchCompletion failed:', err);
+        // Fallback: return truncated agent result as-is
+        return agentResult.substring(0, 500);
+    }
+}
+// ============================================================
+// handleResearchBatch — Decide whether research events are worth speaking
+// ============================================================
+/**
+ * Process a batch of research events and decide whether to speak.
+ * Replaces contextualizeResearchUpdate — but usually returns null (silent).
+ * Only speaks when something genuinely critical is found.
+ */
+export async function handleResearchBatch(workingDir, sessionId, task, batchEvents, researchLog, chatHistory, sessionBaseDir) {
+    // Usually: stay silent. The frontend spinner handles visual feedback.
+    // Only speak if the batch contains something genuinely interesting.
+    // Quick heuristic: if fewer than 5 research steps, too early to say anything useful
+    if (researchLog.length < 5)
+        return null;
+    // Check if any event mentions something critical (error, user-impacting finding)
+    const hasCritical = batchEvents.some(e => e.toLowerCase().includes('error') ||
+        e.toLowerCase().includes('warning') ||
+        e.toLowerCase().includes('breaking') ||
+        e.toLowerCase().includes('deprecated'));
+    if (!hasCritical)
+        return null;
+    // Something interesting — generate a brief spoken update via contextualizeResearchUpdate
+    return contextualizeResearchUpdate(workingDir, sessionId, task, batchEvents, researchLog, chatHistory, sessionBaseDir);
+}
+// ============================================================
+// prepareBriefingScript — Session resume/switch spoken briefing
+// ============================================================
+/**
+ * Generate a brief spoken script for session resume or switch.
+ * Replaces buildContextBriefing + getSpecForVoiceModel.
+ */
+export async function prepareBriefingScript(workingDir, sessionId, conversationHistory, type = 'default') {
+    initProvider();
+    // Read spec for context
+    const specContent = readSessionSpec(workingDir, sessionId);
+    if (!specContent && (!conversationHistory || conversationHistory.length === 0)) {
+        return type === 'switch'
+            ? 'Switched sessions. What would you like to work on?'
+            : 'Welcome back. What would you like to work on?';
+    }
+    // Extract goal and last topic from spec
+    const goalMatch = specContent?.match(/## Goal\s*\n([\s\S]*?)(?=\n##|$)/);
+    const goal = goalMatch ? goalMatch[1].trim().substring(0, 200) : '';
+    const prefix = type === 'switch' ? 'Switched over.' : 'Welcome back.';
+    // If we have a goal, generate a brief spoken briefing
+    if (goal) {
+        const lastExchanges = conversationHistory
+            ? conversationHistory.slice(-3).map(e => `${e.role}: ${e.text.substring(0, 100)}`).join('. ')
+            : '';
+        if (lastExchanges) {
+            return `${prefix} We were working on ${goal}. Last time we discussed ${lastExchanges.substring(0, 150)}. Where would you like to pick up?`;
+        }
+        return `${prefix} We were working on ${goal}. Where would you like to pick up?`;
+    }
+    return type === 'switch'
+        ? 'Switched sessions. What would you like to work on?'
+        : 'Session resumed. What would you like to work on?';
+}
+// ============================================================
+// prepareRecoveryScript — Gemini crash recovery spoken script
+// ============================================================
+/**
+ * Generate a spoken script after Gemini auto-recovery.
+ * Replaces inline recovery logic in index.ts.
+ */
+export async function prepareRecoveryScript(conversationHistory) {
+    if (conversationHistory && conversationHistory.length > 0) {
+        const lastTopic = conversationHistory[conversationHistory.length - 1];
+        return `Voice session was briefly interrupted but I'm back. We were talking about ${lastTopic.text.substring(0, 100)}. Where were we?`;
+    }
+    return 'Voice session was briefly interrupted but I\'m back. What were we working on?';
+}