protoagent 0.0.5 → 0.1.0

package/dist/agentic-loop.js

@@ -1,568 +1,535 @@
-import { tools, handleToolCall } from './tools/index.js';
-import { createChatCompletion } from './config/client.js';
-import { generateSystemPrompt } from './config/system-prompt.js';
-import { getModelConfig } from './config/providers.js';
-import { estimateTokens, createUsageInfo, logUsageInfo, getContextInfo } from './utils/cost-tracker.js';
-import { checkAndCompactIfNeeded } from './utils/conversation-compactor.js';
+/**
+ * The agentic loop — the core of ProtoAgent.
+ *
+ * This module implements the standard tool-use loop:
+ *
+ *  1. Send the conversation to the LLM with tool definitions
+ *  2. If the response contains tool_calls:
+ *     a. Execute each tool
+ *     b. Append the results to the conversation
+ *     c. Go to step 1
+ *  3. If the response is plain text:
+ *     a. Return it to the caller (the UI renders it)
+ *
+ * The loop is a plain TypeScript module — not an Ink component.
+ * The UI subscribes to events emitted by the loop and updates
+ * React state accordingly. This keeps the core logic testable
+ * and UI-independent.
+ */
+import { getAllTools, handleToolCall } from './tools/index.js';
+import { generateSystemPrompt } from './system-prompt.js';
+import { subAgentTool, runSubAgent } from './sub-agent.js';
+import { estimateTokens, estimateConversationTokens, createUsageInfo, getContextInfo, } from './utils/cost-tracker.js';
+import { compactIfNeeded } from './utils/compactor.js';
 import { logger } from './utils/logger.js';
-import { interruptHandler, UserInterruptError } from './utils/interrupt-handler.js';
-// Create system message for ProtoAgent dynamically
-async function createSystemMessage() {
-    const systemPrompt = await generateSystemPrompt();
-    return {
-        role: 'system',
-        content: systemPrompt
-    };
+function emitAbortAndFinish(onEvent) {
+    onEvent({ type: 'done' });
 }
-export class AgenticLoop {
-    constructor(openaiClient, config, options = {}) {
-        this.systemMessage = null;
-        this.openaiClient = openaiClient;
-        this.config = config;
-        this.options = {
-            maxIterations: options.maxIterations || 100,
-            streamOutput: options.streamOutput !== false, // Default to true
+async function sleepWithAbort(delayMs, abortSignal) {
+    if (!abortSignal) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        return;
+    }
+    if (abortSignal.aborted) {
+        throw new Error('Operation aborted');
+    }
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            abortSignal.removeEventListener('abort', onAbort);
+            resolve();
+        }, delayMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            abortSignal.removeEventListener('abort', onAbort);
+            reject(new Error('Operation aborted'));
         };
-        this.messages = []; // Will be initialized with system message in initialize()
+        abortSignal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function appendStreamingFragment(current, fragment) {
+    if (!fragment)
+        return current;
+    if (!current)
+        return fragment;
+    if (current === fragment)
+        return current;
+    if (fragment.startsWith(current))
+        return fragment;
+    const maxOverlap = Math.min(current.length, fragment.length);
+    for (let overlap = maxOverlap; overlap > 0; overlap--) {
+        if (current.endsWith(fragment.slice(0, overlap))) {
+            return current + fragment.slice(overlap);
+        }
     }
-    /**
-     * Initialize the agentic loop with dynamic system message
-     */
-    async initialize() {
-        logger.debug('🚀 Initializing agentic loop', { component: 'AgenticLoop' });
-        this.systemMessage = await createSystemMessage();
-        this.messages = [this.systemMessage];
-        logger.debug('✅ Agentic loop initialized', {
-            component: 'AgenticLoop',
-            systemMessageLength: this.systemMessage.content?.toString().length || 0
-        });
+    return current + fragment;
+}
+function collapseRepeatedString(value) {
+    if (!value)
+        return value;
+    for (let size = 1; size <= Math.floor(value.length / 2); size++) {
+        if (value.length % size !== 0)
+            continue;
+        const candidate = value.slice(0, size);
+        if (candidate.repeat(value.length / size) === value) {
+            return candidate;
+        }
+    }
+    return value;
+}
+function normalizeToolName(name, validToolNames) {
+    if (!name)
+        return name;
+    if (validToolNames.has(name))
+        return name;
+    const collapsed = collapseRepeatedString(name);
+    if (validToolNames.has(collapsed)) {
+        return collapsed;
     }
-    /**
-     * Get the current conversation history
-     */
-    getMessages() {
-        return [...this.messages];
+    return name;
+}
+function extractFirstCompleteJsonValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const opening = trimmed[0];
+    const closing = opening === '{' ? '}' : opening === '[' ? ']' : null;
+    if (!closing)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < trimmed.length; i++) {
+        const char = trimmed[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === '\\') {
+                escaped = true;
+            }
+            else if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === opening)
+            depth++;
+        if (char === closing)
+            depth--;
+        if (depth === 0) {
+            return trimmed.slice(0, i + 1);
+        }
     }
-    /**
-     * Clear the conversation history (keeps system message)
-     */
-    clearHistory() {
-        this.messages = this.systemMessage ? [this.systemMessage] : [];
+    return null;
+}
+function normalizeJsonArguments(argumentsText) {
+    const trimmed = argumentsText.trim();
+    if (!trimmed)
+        return argumentsText;
+    try {
+        JSON.parse(trimmed);
+        return trimmed;
     }
-    /**
-     * Add a message to the conversation history
-     */
-    addMessage(message) {
-        this.messages.push(message);
+    catch {
+        // Fall through to repair heuristics.
     }
-    /**
-     * Process a user input and run the agentic loop
-     */
-    async processUserInput(userInput) {
-        logger.debug('📥 Processing user input', {
-            component: 'AgenticLoop',
-            inputLength: userInput.length,
-            currentMessageCount: this.messages.length
-        });
+    const collapsed = collapseRepeatedString(trimmed);
+    if (collapsed !== trimmed) {
         try {
-            // Add user message to conversation history
-            logger.debug('➕ Adding user message to conversation', { component: 'AgenticLoop' });
-            this.addMessage({
-                role: 'user',
-                content: userInput
-            });
-            // Show a subtle hint about Q key on first use (only if this is the first interaction)
-            if (this.messages.length === 2) { // System message + first user message
-                logger.consoleLog('🤔 Thinking... (press Q to pause)');
-            }
-            else {
-                logger.consoleLog('🤔 Thinking...');
+            JSON.parse(collapsed);
+            return collapsed;
+        }
+        catch {
+            // Fall through to next heuristic.
+        }
+    }
+    const firstJsonValue = extractFirstCompleteJsonValue(trimmed);
+    if (firstJsonValue) {
+        try {
+            JSON.parse(firstJsonValue);
+            return firstJsonValue;
+        }
+        catch {
+            // Give up and return the original text below.
+        }
+    }
+    return argumentsText;
+}
+function sanitizeToolCall(toolCall, validToolNames) {
+    const originalName = toolCall.function?.name || '';
+    const originalArgs = toolCall.function?.arguments || '';
+    const normalizedName = normalizeToolName(originalName, validToolNames);
+    const normalizedArgs = normalizeJsonArguments(originalArgs);
+    const changed = normalizedName !== originalName || normalizedArgs !== originalArgs;
+    if (!changed) {
+        return { toolCall, changed: false };
+    }
+    return {
+        changed: true,
+        toolCall: {
+            ...toolCall,
+            function: {
+                ...toolCall.function,
+                name: normalizedName,
+                arguments: normalizedArgs,
+            },
+        },
+    };
+}
+function sanitizeMessagesForRetry(messages, validToolNames) {
+    let changed = false;
+    const sanitizedMessages = messages.map((message) => {
+        const msgAny = message;
+        if (message.role !== 'assistant' || !Array.isArray(msgAny.tool_calls) || msgAny.tool_calls.length === 0) {
+            return message;
+        }
+        const nextToolCalls = msgAny.tool_calls.map((toolCall) => {
+            const sanitized = sanitizeToolCall(toolCall, validToolNames);
+            changed = changed || sanitized.changed;
+            return sanitized.toolCall;
+        });
+        return {
+            ...msgAny,
+            tool_calls: nextToolCalls,
+        };
+    });
+    return { messages: sanitizedMessages, changed };
+}
+function getValidToolNames() {
+    return new Set([...getAllTools(), subAgentTool]
+        .map((tool) => tool.function?.name)
+        .filter((name) => Boolean(name)));
+}
+/**
+ * Process a single user input through the agentic loop.
+ *
+ * Takes the full conversation history (including system message),
+ * appends the user message, runs the loop, and returns the updated
+ * message history.
+ *
+ * The `onEvent` callback is called for each event (text deltas,
+ * tool calls, usage info, etc.) so the UI can render progress.
+ */
+export async function runAgenticLoop(client, model, messages, userInput, onEvent, options = {}) {
+    const maxIterations = options.maxIterations ?? 100;
+    const pricing = options.pricing;
+    const abortSignal = options.abortSignal;
+    const sessionId = options.sessionId;
+    // Note: userInput is passed for context/logging but user message should already be in messages array
+    // (added by the caller in handleSubmit for immediate UI display)
+    const updatedMessages = [...messages];
+    // Refresh system prompt to pick up any new skills or project changes
+    const newSystemPrompt = await generateSystemPrompt();
+    const systemMsgIndex = updatedMessages.findIndex((m) => m.role === 'system');
+    if (systemMsgIndex !== -1) {
+        updatedMessages[systemMsgIndex] = { role: 'system', content: newSystemPrompt };
+    }
+    let iterationCount = 0;
+    let repairRetryCount = 0;
+    const validToolNames = getValidToolNames();
+    while (iterationCount < maxIterations) {
+        // Check if abort was requested
+        if (abortSignal?.aborted) {
+            logger.debug('Agentic loop aborted by user');
+            emitAbortAndFinish(onEvent);
+            return updatedMessages;
+        }
+        iterationCount++;
+        // Check for compaction
+        if (pricing) {
+            const contextInfo = getContextInfo(updatedMessages, pricing);
+            if (contextInfo.needsCompaction) {
+                const compacted = await compactIfNeeded(client, model, updatedMessages, pricing.contextWindow, contextInfo.currentTokens);
+                // Replace messages in-place
+                updatedMessages.length = 0;
+                updatedMessages.push(...compacted);
             }
-            logger.info('🤔 AI thinking process started');
-            logger.debug('🧠 Starting thinking process', {
-                component: 'AgenticLoop',
-                totalMessages: this.messages.length,
-                maxIterations: this.options.maxIterations
+        }
+        try {
+            // Build tools list: core tools + sub-agent tool + dynamic (MCP) tools
+            const allTools = [...getAllTools(), subAgentTool];
+            logger.debug('Making API request', {
+                model,
+                toolsCount: allTools.length,
+                messagesCount: updatedMessages.length,
+                toolNames: allTools.map((t) => t.function?.name).join(', '),
             });
-            // Start the agentic loop
-            let continueProcessing = true;
-            let iterationCount = 0;
-            while (continueProcessing && iterationCount < this.options.maxIterations) {
-                iterationCount++;
-                logger.trace(`🔄 Starting agentic loop iteration ${iterationCount}/${this.options.maxIterations}`, {
-                    component: 'AgenticLoop',
-                    iteration: iterationCount,
-                    messageCount: this.messages.length,
-                    conversationTokensApprox: this.messages.reduce((sum, msg) => sum + (typeof msg.content === 'string' ? msg.content.length / 4 : 0), 0)
-                });
-                try {
-                    // Check if conversation needs compaction before making API call
-                    logger.debug('🔍 Checking context window usage', { component: 'AgenticLoop', iteration: iterationCount });
-                    const modelConfig = getModelConfig(this.config.provider, this.config.model);
-                    if (modelConfig) {
-                        const contextInfo = getContextInfo(this.messages, modelConfig);
-                        logger.debug('📊 Context analysis complete', {
-                            component: 'AgenticLoop',
-                            currentTokens: contextInfo.currentTokens,
-                            maxTokens: modelConfig.contextWindow,
-                            needsCompaction: contextInfo.needsCompaction,
-                            percentageUsed: ((contextInfo.currentTokens / modelConfig.contextWindow) * 100).toFixed(1)
-                        });
-                        if (contextInfo.needsCompaction) {
-                            logger.consoleLog('\n🗜️  Context window approaching limit, compacting conversation...');
-                            logger.info('🗜️  Context compaction message displayed to user');
-                            logger.debug('🗜️  Starting conversation compaction', { component: 'AgenticLoop' });
-                            this.messages = await checkAndCompactIfNeeded(this.openaiClient, this.config.model, this.messages, modelConfig.contextWindow, contextInfo.currentTokens);
-                            logger.debug('✅ Conversation compaction complete', {
-                                component: 'AgenticLoop',
-                                newMessageCount: this.messages.length
-                            });
-                        }
-                    }
-                    logger.debug('🌐 Creating chat completion request', {
-                        component: 'AgenticLoop',
-                        model: this.config.model,
-                        messageCount: this.messages.length,
-                        toolsCount: tools.length,
-                        streaming: true
-                    });
-                    // Create completion using OpenAI with built-in retry logic and cost tracking
-                    const { stream, estimatedInputTokens } = await createChatCompletion(this.openaiClient, {
-                        model: this.config.model,
-                        messages: this.messages,
-                        tools: tools,
-                        tool_choice: 'auto',
-                        stream: true
-                    }, this.config, this.messages);
-                    logger.debug('📡 Chat completion stream created', {
-                        component: 'AgenticLoop',
-                        estimatedInputTokens,
-                        iteration: iterationCount
+            // Log message structure for debugging provider compatibility
+            for (const msg of updatedMessages) {
+                const m = msg;
+                if (m.role === 'tool') {
+                    logger.trace('Message payload', {
+                        role: m.role,
+                        tool_call_id: m.tool_call_id,
+                        contentLength: m.content?.length,
+                        contentPreview: m.content?.slice(0, 100),
                     });
-                    // Collect the streamed response
-                    logger.trace('📨 Starting to collect streamed response', { component: 'AgenticLoop' });
-                    let assistantMessage = {
-                        role: 'assistant',
-                        content: '',
-                        tool_calls: []
-                    };
-                    let streamedContent = '';
-                    let hasToolCalls = false;
-                    let actualUsage = undefined;
-                    let chunkCount = 0;
-                    // Start listening for 'Q' key interrupts during streaming
-                    interruptHandler.startListening();
-                    try {
-                        for await (const chunk of stream) {
-                            // Check for user interrupt
-                            if (interruptHandler.isInterrupted()) {
-                                logger.debug('User requested pause during streaming', { component: 'AgenticLoop' });
-                                break;
-                            }
-                            chunkCount++;
-                            const delta = chunk.choices[0]?.delta;
-                            logger.trace('📦 Processing chunk', {
-                                component: 'AgenticLoop',
-                                chunkNumber: chunkCount,
-                                hasContent: !!delta?.content,
-                                hasToolCalls: !!delta?.tool_calls,
-                                finishReason: chunk.choices[0]?.finish_reason
-                            });
-                            if (chunk.usage) {
-                                actualUsage = chunk.usage;
-                                logger.trace('📊 Received usage data', {
-                                    component: 'AgenticLoop',
-                                    promptTokens: chunk.usage.prompt_tokens,
-                                    completionTokens: chunk.usage.completion_tokens,
-                                    totalTokens: chunk.usage.total_tokens
-                                });
-                            }
-                            if (delta?.content) {
-                                streamedContent += delta.content;
-                                assistantMessage.content = streamedContent;
-                                // Stream content to user in real-time if no tool calls are being made
-                                if (this.options.streamOutput && !hasToolCalls && !delta.tool_calls) {
-                                    if (streamedContent === delta.content) {
-                                        // First content chunk
-                                        process.stdout.write('\n🤖 ProtoAgent: ');
-                                    }
-                                    process.stdout.write(delta.content);
-                                }
-                            }
-                            if (delta?.tool_calls) {
-                                hasToolCalls = true;
-                                logger.trace('🔧 Tool calls detected in delta', {
-                                    component: 'AgenticLoop',
-                                    toolCallsCount: delta.tool_calls.length
-                                });
-                                // Initialize tool_calls array if not exists
-                                if (!assistantMessage.tool_calls) {
-                                    assistantMessage.tool_calls = [];
-                                }
-                                // Handle tool calls in streaming
-                                for (const toolCallDelta of delta.tool_calls) {
-                                    const index = toolCallDelta.index || 0;
-                                    logger.trace('🛠️  Processing tool call delta', {
-                                        component: 'AgenticLoop',
-                                        index,
-                                        hasId: !!toolCallDelta.id,
-                                        hasName: !!toolCallDelta.function?.name,
-                                        hasArgs: !!toolCallDelta.function?.arguments
-                                    });
-                                    // Ensure we have an entry at this index
-                                    if (!assistantMessage.tool_calls[index]) {
-                                        assistantMessage.tool_calls[index] = {
-                                            id: '',
-                                            type: 'function',
-                                            function: { name: '', arguments: '' }
-                                        };
-                                    }
-                                    if (toolCallDelta.id) {
-                                        assistantMessage.tool_calls[index].id = toolCallDelta.id;
-                                    }
-                                    if (toolCallDelta.function?.name) {
-                                        assistantMessage.tool_calls[index].function.name += toolCallDelta.function.name;
-                                    }
-                                    if (toolCallDelta.function?.arguments) {
-                                        assistantMessage.tool_calls[index].function.arguments += toolCallDelta.function.arguments;
-                                    }
-                                }
-                            }
-                        }
-                        logger.debug('✅ Stream processing complete', {
-                            component: 'AgenticLoop',
-                            totalChunks: chunkCount,
-                            finalContentLength: streamedContent.length,
-                            finalToolCallsCount: assistantMessage.tool_calls?.length || 0,
-                            hasActualUsage: !!actualUsage
-                        });
-                    }
-                    finally {
-                        // Always stop listening for interrupts when streaming ends
-                        interruptHandler.stopListening();
-                    }
-                    // Check if streaming was interrupted
-                    if (interruptHandler.isInterrupted()) {
-                        logger.debug('User paused during streaming', { component: 'AgenticLoop' });
-                        interruptHandler.reset();
-                        throw new UserInterruptError('User paused during streaming');
-                    }
-                    const message = assistantMessage;
-                    // DEBUG: Log the complete AI response
-                    logger.debug('🤖 AI Response received', {
-                        component: 'AgenticLoop',
-                        iteration: iterationCount,
-                        responseType: message.tool_calls?.length > 0 ? 'TOOL_CALLS' : 'TEXT_RESPONSE',
-                        contentLength: message.content?.length || 0,
-                        contentPreview: message.content ? message.content.substring(0, 200) + (message.content.length > 200 ? '...' : '') : null,
-                        rawMessage: JSON.stringify(message),
-                        toolCallsCount: message.tool_calls?.length || 0,
-                        toolNames: message.tool_calls?.map((tc) => tc.function.name) || [],
-                        toolCallsDetails: message.tool_calls?.map((tc) => ({
+                }
+                else if (m.role === 'assistant' && m.tool_calls?.length) {
+                    logger.trace('Message payload', {
+                        role: m.role,
+                        toolCalls: m.tool_calls.map((tc) => ({
                             id: tc.id,
-                            name: tc.function.name,
-                            argsLength: tc.function.arguments?.length || 0,
-                            argsPreview: tc.function.arguments ? tc.function.arguments.substring(0, 100) + (tc.function.arguments.length > 100 ? '...' : '') : null
-                        })) || []
+                            name: tc.function?.name,
+                            argsLength: tc.function?.arguments?.length,
+                        })),
                     });
-                    // TRACE: Log the AI's decision after thinking
-                    logger.trace('🧠 AI thinking complete - analyzing response...', {
-                        component: 'AgenticLoop',
-                        iteration: iterationCount,
-                        hasToolCalls: !!(message.tool_calls && message.tool_calls.length > 0),
-                        hasContent: !!(message.content && message.content.trim().length > 0),
-                        toolCount: message.tool_calls?.length || 0,
-                        contentLength: message.content?.length || 0
+                }
+                else {
+                    logger.trace('Message payload', {
+                        role: m.role,
+                        contentLength: m.content?.length,
                     });
-                    if (message.tool_calls && message.tool_calls.length > 0) {
-                        logger.trace('🔧 AI decided to use tools', {
-                            component: 'AgenticLoop',
-                            decision: 'TOOL_CALLS',
-                            tools: message.tool_calls.map((tc) => tc.function.name).join(', '),
-                            reasoning: 'AI determined that tool usage is needed to complete the task'
-                        });
-                    }
-                    else if (message.content && message.content.trim().length > 0) {
-                        logger.trace('💬 AI decided to provide direct response', {
-                            component: 'AgenticLoop',
-                            decision: 'DIRECT_RESPONSE',
-                            responsePreview: message.content.slice(0, 100) + (message.content.length > 100 ? '...' : ''),
-                            reasoning: 'AI determined that a direct text response is sufficient'
-                        });
-                    }
-                    else {
-                        logger.trace('⚠️ AI provided empty response', {
-                            component: 'AgenticLoop',
-                            decision: 'EMPTY_RESPONSE',
-                            reasoning: 'AI returned neither tool calls nor content - this may indicate an issue'
-                        });
-                    }
-                    // Calculate and log cost information
-                    if (modelConfig) {
-                        const finalInputTokens = actualUsage?.prompt_tokens ?? estimatedInputTokens;
-                        const finalOutputTokens = actualUsage?.completion_tokens ?? estimateTokens(message.content || '');
-                        const usageInfo = createUsageInfo(finalInputTokens, finalOutputTokens, modelConfig);
-                        const contextInfo = getContextInfo(this.messages, modelConfig);
-                        logUsageInfo(usageInfo, contextInfo, modelConfig);
+                }
+            }
+            const stream = await client.chat.completions.create({
+                model,
+                messages: updatedMessages,
+                tools: allTools,
+                tool_choice: 'auto',
+                stream: true,
+                stream_options: { include_usage: true },
+            }, {
+                signal: abortSignal,
+            });
+            // Accumulate the streamed response
+            const assistantMessage = {
+                role: 'assistant',
+                content: '',
+                tool_calls: [],
+            };
+            let streamedContent = '';
+            let hasToolCalls = false;
+            let actualUsage;
+            for await (const chunk of stream) {
+                const delta = chunk.choices[0]?.delta;
+                if (chunk.usage) {
+                    actualUsage = chunk.usage;
+                }
+                // Stream text content
+                if (delta?.content) {
+                    streamedContent += delta.content;
+                    assistantMessage.content = streamedContent;
+                    if (!hasToolCalls) {
+                        onEvent({ type: 'text_delta', content: delta.content });
                     }
-                    // Check if AI wants to use tools
-                    if (message.tool_calls && message.tool_calls.length > 0) {
-                        logger.debug('🔧 AI requested tool usage', {
-                            component: 'AgenticLoop',
-                            toolCount: message.tool_calls.length,
-                            toolNames: message.tool_calls.map((tc) => tc.function.name)
-                        });
-                        // Add the AI's message (with tool calls) to conversation
-                        this.addMessage(message);
-                        logger.debug('➕ AI message with tool calls added to conversation', {
-                            component: 'AgenticLoop',
-                            messageRole: 'assistant',
-                            hasContent: !!message.content,
-                            contentLength: message.content?.length || 0,
-                            toolCallsCount: message.tool_calls?.length || 0,
-                            conversationLength: this.messages.length
-                        });
-                        logger.consoleLog(`🔧 Using ${message.tool_calls.length} tool(s)...`);
-                        logger.info(`🔧 Tool usage message displayed: ${message.tool_calls.length} tools`);
-                        // Execute each tool call
-                        // Start listening for interrupts during tool execution
-                        interruptHandler.startListening();
-                        try {
-                            for (const toolCall of message.tool_calls) {
-                                // Check for user interrupt before each tool
-                                if (interruptHandler.isInterrupted()) {
-                                    logger.debug('User requested pause during tool execution', { component: 'AgenticLoop' });
-                                    interruptHandler.reset();
-                                    throw new UserInterruptError('User paused during tool execution');
-                                }
-                                const { name, arguments: args } = toolCall.function;
-                                logger.debug('🛠️  Executing tool', {
-                                    component: 'AgenticLoop',
-                                    toolName: name,
-                                    toolId: toolCall.id,
-                                    argsLength: args.length
-                                });
-                                logger.consoleLog(`🛠️  ${name}`);
-                                logger.info(`🛠️  Tool execution message displayed: ${name}`);
-                                try {
-                                    const toolArgs = JSON.parse(args);
-                                    logger.debug('📋 Tool arguments parsed', {
-                                        component: 'AgenticLoop',
-                                        toolName: name,
-                                        parsedArgs: Object.keys(toolArgs)
-                                    });
-                                    const startTime = Date.now();
-                                    const result = await handleToolCall(name, toolArgs);
-                                    const executionTime = Date.now() - startTime;
-                                    logger.debug('✅ Tool execution successful', {
-                                        component: 'AgenticLoop',
-                                        toolName: name,
-                                        executionTime,
-                                        resultLength: result.length
-                                    });
-                                    // Add tool result to conversation
-                                    this.addMessage({
-                                        role: 'tool',
-                                        tool_call_id: toolCall.id,
-                                        content: result
-                                    });
-                                    // Show abbreviated result to user
-                                    const lines = result.split('\n');
-                                    if (lines.length > 10) {
-                                        logger.consoleLog(`   ✅ ${lines.slice(0, 3).join('\n   ')}\n   ... (${lines.length - 6} more lines) ...\n   ${lines.slice(-3).join('\n   ')}`);
-                                        logger.info(`   ✅ Tool result displayed (abbreviated, ${lines.length} lines)`);
-                                    }
-                                    else {
-                                        logger.consoleLog(`   ✅ ${result.slice(0, 200)}${result.length > 200 ? '...' : ''}`);
-                                        logger.info(`   ✅ Tool result displayed (full, ${result.length} chars)`);
-                                    }
-                                }
-                                catch (error) {
-                                    const errorMessage = error instanceof Error ? error.message : String(error);
-                                    logger.error('❌ Tool execution failed', {
-                                        component: 'AgenticLoop',
-                                        toolName: name,
-                                        error: errorMessage
-                                    });
-                                    logger.consoleLog(`   ❌ Error: ${errorMessage}`);
-                                    logger.error(`   ❌ Tool error message displayed: ${errorMessage}`);
-                                    // Add error result to conversation
-                                    this.addMessage({
-                                        role: 'tool',
-                                        tool_call_id: toolCall.id,
-                                        content: `Error: ${errorMessage}`
-                                    });
-                                }
-                            }
+                }
+                // Accumulate tool calls
+                if (delta?.tool_calls) {
+                    hasToolCalls = true;
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index || 0;
+                        if (!assistantMessage.tool_calls[idx]) {
+                            assistantMessage.tool_calls[idx] = {
+                                id: '',
+                                type: 'function',
+                                function: { name: '', arguments: '' },
+                            };
                         }
-                        finally {
-                            // Always stop listening for interrupts when tool execution ends
-                            interruptHandler.stopListening();
+                        if (tc.id)
+                            assistantMessage.tool_calls[idx].id = tc.id;
+                        if (tc.function?.name) {
+                            assistantMessage.tool_calls[idx].function.name = appendStreamingFragment(assistantMessage.tool_calls[idx].function.name, tc.function.name);
                         }
-                        // Continue the loop to let AI process tool results
-                        logger.trace('🔄 Continuing agentic loop for AI to process tool results', {
-                            component: 'AgenticLoop',
-                            decision: 'CONTINUE_PROCESSING',
-                            reasoning: 'Tools were executed, AI needs another thinking cycle to process results',
-                            nextIteration: iterationCount + 1
-                        });
-                        continue;
-                    }
-                    else {
-                        // AI provided a regular response
-                        if (message.content && !hasToolCalls) {
-                            // Content was already streamed to user during the loop above
-                            if (this.options.streamOutput) {
-                                logger.consoleLog('\n'); // Add newline after streaming is complete
-                                logger.debug('\\n AI response streaming completed');
-                            }
-                            else {
-                                logger.consoleLog(`\n🤖 ProtoAgent: ${message.content}\n`);
-                                logger.info('🤖 AI response displayed to user (non-streaming)');
-                            }
-                            // Add AI response to conversation history
-                            this.addMessage({
-                                role: 'assistant',
-                                content: message.content
-                            });
-                            logger.debug('➕ AI text response added to conversation', {
-                                component: 'AgenticLoop',
-                                messageRole: 'assistant',
-                                contentLength: message.content?.length || 0,
-                                conversationLength: this.messages.length
-                            });
+                        if (tc.function?.arguments) {
+                            assistantMessage.tool_calls[idx].function.arguments = appendStreamingFragment(assistantMessage.tool_calls[idx].function.arguments, tc.function.arguments);
                         }
-                        else if (message.content && hasToolCalls) {
-                            // AI provided content along with tool calls (rare case)
-                            if (this.options.streamOutput) {
-                                process.stdout.write('\n🤖 ProtoAgent: ');
-                                process.stdout.write(message.content);
-                                logger.consoleLog('\n');
-                                logger.info('🤖 AI response with tool calls displayed (streaming)');
-                            }
-                            else {
-                                logger.consoleLog(`\n🤖 ProtoAgent: ${message.content}\n`);
-                                logger.info('🤖 AI response with tool calls displayed (non-streaming)');
-                            }
-                            // Add AI response to conversation history
-                            this.addMessage({
-                                role: 'assistant',
-                                content: message.content
-                            });
-                            logger.debug('➕ AI mixed response (content + tool calls) added to conversation', {
-                                component: 'AgenticLoop',
-                                messageRole: 'assistant',
-                                contentLength: message.content?.length || 0,
-                                conversationLength: this.messages.length
-                            });
+                        // Gemini 3+ models include an `extra_content` field on tool calls
+                        // containing a `thought_signature`. This MUST be preserved and sent
+                        // back in subsequent requests, otherwise Gemini returns a 400.
+                        // See: https://ai.google.dev/gemini-api/docs/openai
+                        // See also: https://gist.github.com/thomasgauvin/3cfe8e907c957fba4e132e6cf0f06292
+                        if (tc.extra_content) {
+                            assistantMessage.tool_calls[idx].extra_content = tc.extra_content;
                         }
-                        logger.trace('✅ Agentic loop complete - stopping processing', {
-                            component: 'AgenticLoop',
-                            decision: 'STOP_PROCESSING',
-                            reasoning: 'AI provided final response without tool calls',
-                            totalIterations: iterationCount
-                        });
-                        continueProcessing = false;
                     }
                 }
-                catch (apiError) {
-                    // Check if this is a user interrupt first
-                    if (apiError instanceof UserInterruptError) {
-                        logger.warn('🛑 User pressed Q - interrupt during processing', {
-                            component: 'AgenticLoop',
-                            reason: apiError.message
+            }
+            // Emit usage info
+            if (pricing) {
+                const inputTokens = actualUsage?.prompt_tokens ?? estimateConversationTokens(updatedMessages);
+                const outputTokens = actualUsage?.completion_tokens ?? estimateTokens(assistantMessage.content || '');
+                const usageInfo = createUsageInfo(inputTokens, outputTokens, pricing);
+                const contextInfo = getContextInfo(updatedMessages, pricing);
+                onEvent({
+                    type: 'usage',
+                    usage: {
+                        inputTokens,
+                        outputTokens,
+                        cost: usageInfo.estimatedCost,
+                        contextPercent: contextInfo.utilizationPercentage,
+                    },
+                });
+            }
+            // Handle tool calls
+            if (assistantMessage.tool_calls.length > 0) {
+                // Clean up empty tool_calls entries (from sparse array)
+                assistantMessage.tool_calls = assistantMessage.tool_calls.filter(Boolean);
+                assistantMessage.tool_calls = assistantMessage.tool_calls.map((toolCall) => {
+                    const sanitized = sanitizeToolCall(toolCall, validToolNames);
+                    if (sanitized.changed) {
+                        logger.warn('Sanitized streamed tool call', {
+                            originalName: toolCall.function?.name,
+                            sanitizedName: sanitized.toolCall.function?.name,
                         });
-                        console.log('\n'); // Just a clean newline
-                        return;
                     }
-                    // Handle API errors that weren't caught by the retry logic
-                    logger.trace('❌ API Error occurred - stopping agentic loop', {
-                        component: 'AgenticLoop',
-                        decision: 'STOP_ON_API_ERROR',
-                        errorStatus: apiError?.status,
-                        errorMessage: apiError?.message,
-                        reasoning: 'Unrecoverable API error encountered'
-                    });
-                    console.error('\n❌ API Error:', apiError?.message || 'Unknown API error');
-                    logger.error('\n❌ API Error message displayed to user', {
-                        component: 'AgenticLoop',
-                        error: apiError?.message || 'Unknown API error'
+                    return sanitized.toolCall;
+                });
+                logger.debug('Model returned tool calls', {
+                    count: assistantMessage.tool_calls.length,
+                    calls: assistantMessage.tool_calls.map((tc) => ({
+                        id: tc.id,
+                        name: tc.function?.name,
+                        argsPreview: tc.function?.arguments?.slice(0, 100),
+                    })),
+                });
+                updatedMessages.push(assistantMessage);
+                for (const toolCall of assistantMessage.tool_calls) {
+                    const { name, arguments: argsStr } = toolCall.function;
+                    onEvent({
+                        type: 'tool_call',
+                        toolCall: { id: toolCall.id, name, args: argsStr, status: 'running' },
                     });
-                    // Check for specific error types and provide helpful messages
-                    if (apiError?.status === 401) {
-                        logger.consoleLog('💡 Authentication failed. Your API key may be invalid or expired.');
-                        logger.consoleLog('   Run: protoagent config --update-key');
-                        logger.info('💡 Auth error help message displayed to user');
-                    }
-                    else if (apiError?.status === 403) {
-                        logger.consoleLog('💡 Access forbidden. Check your API key permissions or billing status.');
-                        logger.info('💡 Access forbidden help message displayed to user');
-                    }
-                    else if (apiError?.status === 400) {
-                        logger.consoleLog('💡 Bad request. There may be an issue with the request format.');
-                        logger.consoleLog('   This could be a bug in ProtoAgent. Please check for updates.');
-                        logger.info('💡 Bad request help message displayed to user');
+                    try {
+                        const args = JSON.parse(argsStr);
+                        let result;
+                        // Handle sub-agent tool specially
+                        if (name === 'sub_agent') {
+                            result = await runSubAgent(client, model, args.task, args.max_iterations);
+                        }
+                        else {
+                            result = await handleToolCall(name, args, { sessionId });
+                        }
+                        logger.debug('Tool result', {
+                            tool: name,
+                            tool_call_id: toolCall.id,
+                            resultLength: result.length,
+                            resultPreview: result.slice(0, 200),
+                        });
+                        updatedMessages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            content: result,
+                        });
+                        onEvent({
+                            type: 'tool_result',
+                            toolCall: { id: toolCall.id, name, args: argsStr, status: 'done', result },
+                        });
                     }
-                    else {
-                        logger.consoleLog('💡 An unexpected API error occurred. Please try again.');
-                        logger.info('💡 Generic API error help message displayed to user');
+                    catch (err) {
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        updatedMessages.push({
+                            role: 'tool',
+                            tool_call_id: toolCall.id,
+                            content: `Error: ${errMsg}`,
+                        });
+                        onEvent({
+                            type: 'tool_result',
+                            toolCall: { id: toolCall.id, name, args: argsStr, status: 'error', result: errMsg },
+                        });
                     }
-                    // Exit the processing loop for API errors
-                    break;
                 }
+                // Continue loop — let the LLM process tool results
+                continue;
             }
-            if (iterationCount >= this.options.maxIterations) {
-                logger.trace('⚠️ Maximum iteration limit reached - stopping agentic loop', {
-                    component: 'AgenticLoop',
-                    decision: 'STOP_ON_MAX_ITERATIONS',
-                    maxIterations: this.options.maxIterations,
-                    reasoning: 'Reached maximum allowed iterations to prevent infinite loops'
+            // Plain text response — we're done
+            if (assistantMessage.content) {
+                updatedMessages.push({
+                    role: 'assistant',
+                    content: assistantMessage.content,
                 });
-                logger.consoleLog('\n⚠️  Maximum iteration limit reached. Task may be incomplete.');
-                logger.warn('⚠️  Max iteration warning displayed to user');
             }
+            repairRetryCount = 0;
+            onEvent({ type: 'done' });
+            return updatedMessages;
         }
-        catch (error) {
-            // Check if this is a user interrupt
-            if (error instanceof UserInterruptError) {
-                logger.debug('🛑 User interrupt detected - returning control to user', {
-                    component: 'AgenticLoop',
-                    reason: error.message
-                });
-                logger.consoleLog('\n');
-                return;
+        catch (apiError) {
+            if (abortSignal?.aborted || apiError?.name === 'AbortError' || apiError?.message === 'Operation aborted') {
+                logger.debug('Agentic loop request aborted');
+                emitAbortAndFinish(onEvent);
+                return updatedMessages;
+            }
+            const errMsg = apiError?.message || 'Unknown API error';
+            // Try to extract response body for more details
+            let responseBody;
+            try {
+                if (apiError?.response) {
+                    responseBody = JSON.stringify(apiError.response);
+                }
+                else if (apiError?.error) {
+                    responseBody = JSON.stringify(apiError.error);
+                }
             }
-            // Handle general processing errors
-            console.error('\n❌ Error during processing:', error?.message || 'Unknown error');
-            logger.error('\n❌ General processing error displayed to user', {
-                component: 'AgenticLoop',
-                error: error?.message || 'Unknown error'
+            catch { /* ignore */ }
+            logger.error(`API error: ${errMsg}`, {
+                status: apiError?.status,
+                code: apiError?.code,
+                responseBody,
+                headers: apiError?.headers ? Object.fromEntries(Object.entries(apiError.headers).filter(([k]) => ['content-type', 'x-error', 'retry-after'].includes(k.toLowerCase()))) : undefined,
+            });
+            // Log the last few messages to help debug format issues
+            logger.debug('Messages at time of error', {
+                lastMessages: updatedMessages.slice(-3).map((m) => ({
+                    role: m.role,
+                    hasToolCalls: !!(m.tool_calls?.length),
+                    tool_call_id: m.tool_call_id,
+                    contentPreview: m.content?.slice(0, 150),
+                })),
             });
-            // Provide helpful error messages for common issues
-            if (error?.message?.includes('API key')) {
-                logger.consoleLog('💡 There seems to be an issue with your API key configuration.');
-                logger.consoleLog('   Run: protoagent config --show');
-                logger.info('💡 API key error help message displayed');
+            const retryableStatus = apiError?.status === 408 || apiError?.status === 409 || apiError?.status === 425;
+            const retryableCode = ['ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'ENETUNREACH', 'EAI_AGAIN'].includes(apiError?.code);
+            if (apiError?.status === 400 && repairRetryCount < 2) {
+                const sanitized = sanitizeMessagesForRetry(updatedMessages, getValidToolNames());
+                if (sanitized.changed) {
+                    repairRetryCount++;
+                    updatedMessages.length = 0;
+                    updatedMessages.push(...sanitized.messages);
+                    logger.warn('400 response after malformed tool payload; retrying with sanitized messages', {
+                        repairRetryCount,
+                    });
+                    onEvent({
+                        type: 'error',
+                        error: 'Provider rejected the tool payload. Repairing the request and retrying...',
+                        transient: true,
+                    });
+                    continue;
+                }
             }
-            else if (error?.message?.includes('model')) {
-                logger.consoleLog('💡 There seems to be an issue with the selected model.');
-                logger.consoleLog('   Run: protoagent config --update-model');
-                logger.info('💡 Model error help message displayed');
+            // Retry on 429 (rate limit) with backoff
+            if (apiError?.status === 429) {
+                const retryAfter = parseInt(apiError?.headers?.['retry-after'] || '5', 10);
+                const backoff = Math.min(retryAfter * 1000, 60_000);
+                logger.info(`Rate limited, retrying in ${backoff / 1000}s...`);
+                onEvent({ type: 'error', error: `Rate limited. Retrying in ${backoff / 1000}s...`, transient: true });
+                await sleepWithAbort(backoff, abortSignal);
+                continue;
             }
-            else {
-                logger.consoleLog('💡 An unexpected error occurred. Please check your configuration and try again.');
-                logger.info('💡 Generic error help message displayed');
+            // Retry on transient request failures
+            if (apiError?.status >= 500 || retryableStatus || retryableCode) {
+                const backoff = Math.min(2 ** iterationCount * 1000, 30_000);
+                logger.info(`Request failed, retrying in ${backoff / 1000}s...`);
+                onEvent({ type: 'error', error: `Request failed. Retrying in ${backoff / 1000}s...`, transient: true });
+                await sleepWithAbort(backoff, abortSignal);
+                continue;
             }
-            logger.consoleLog('\n🤖 ProtoAgent: I encountered an error and cannot continue processing this request.\n');
-            logger.info('🤖 Error termination message displayed to user');
+            // Non-retryable error
+            onEvent({ type: 'error', error: errMsg });
+            onEvent({ type: 'done' });
+            return updatedMessages;
         }
     }
+    onEvent({ type: 'error', error: 'Maximum iteration limit reached.' });
+    onEvent({ type: 'done' });
+    return updatedMessages;
 }
 /**
- * Create a new agentic loop instance
+ * Initialize the conversation with the system prompt.
  */
-export async function createAgenticLoop(openaiClient, config, options) {
-    const loop = new AgenticLoop(openaiClient, config, options);
-    await loop.initialize();
-    return loop;
+export async function initializeMessages() {
+    const systemPrompt = await generateSystemPrompt();
+    return [{ role: 'system', content: systemPrompt }];
 }