protoagent 0.1.14 → 0.1.16

package/dist/agentic-loop.js

@@ -17,259 +17,18 @@
  * and UI-independent.
  */
 import { setMaxListeners } from 'node:events';
-import { getAllTools, handleToolCall } from './tools/index.js';
+import { getAllTools } 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 { subAgentTool } from './sub-agent.js';
+import { getContextInfo, } from './utils/cost-tracker.js';
 import { compactIfNeeded } from './utils/compactor.js';
 import { logger } from './utils/logger.js';
+import { processStream } from './agentic-loop/stream.js';
+import { executeToolCalls } from './agentic-loop/executor.js';
+import { handleApiError } from './agentic-loop/errors.js';
 function emitAbortAndFinish(onEvent) {
     onEvent({ type: 'done' });
 }
-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'));
-        };
-        abortSignal.addEventListener('abort', onAbort, { once: true });
-    });
-}
-/** @internal exported for unit testing only */
-export function appendStreamingFragment(current, fragment) {
-    if (!fragment)
-        return current;
-    if (!current)
-        return fragment;
-    // Some providers resend the full accumulated value instead of a delta.
-    // These two guards handle that case without corrupting normal incremental deltas.
-    if (current === fragment)
-        return current;
-    if (fragment.startsWith(current))
-        return fragment;
-    // Normal case: incremental delta, just append.
-    // The previous partial-overlap loop was removed because it caused false-positive
-    // deduplication: short JSON tokens (e.g. `", "`) would coincidentally match the
-    // tail of `current`, silently stripping characters from valid argument payloads.
-    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;
-    }
-    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);
-        }
-    }
-    return null;
-}
-/**
- * Repair invalid JSON escape sequences in a string value.
- *
- * JSON only allows: \" \\ \/ \b \f \n \r \t \uXXXX
- * Models sometimes emit \| \! \- etc. (e.g. grep regex args) which make
- * JSON.parse throw, and Anthropic strict-validates tool_call arguments on
- * every subsequent request, bricking the session permanently.
- *
- * We double the backslash for any \X where X is not a valid JSON escape char.
- */
-function repairInvalidEscapes(value) {
-    // Match a backslash followed by any character that is NOT a valid JSON escape
-    // Valid escapes: " \ / b f n r t u
-    return value.replace(/\\([^"\\\/bfnrtu])/g, '\\\\$1');
-}
-function normalizeJsonArguments(argumentsText) {
-    const trimmed = argumentsText.trim();
-    if (!trimmed)
-        return argumentsText;
-    try {
-        JSON.parse(trimmed);
-        return trimmed;
-    }
-    catch {
-        // Fall through to repair heuristics.
-    }
-    const collapsed = collapseRepeatedString(trimmed);
-    if (collapsed !== trimmed) {
-        try {
-            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.
-        }
-    }
-    // Heuristic: repair invalid escape sequences (e.g. \| from grep regex args)
-    const repaired = repairInvalidEscapes(trimmed);
-    if (repaired !== trimmed) {
-        try {
-            JSON.parse(repaired);
-            return repaired;
-        }
-        catch {
-            // Try repair + first-value extraction together
-            const repairedFirst = extractFirstCompleteJsonValue(repaired);
-            if (repairedFirst) {
-                try {
-                    JSON.parse(repairedFirst);
-                    return repairedFirst;
-                }
-                catch { /* give up */ }
-            }
-        }
-    }
-    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 };
-}
-/**
- * Remove orphaned tool result messages that don't have a matching tool_call_id
- * in any assistant message. This happens when messages are truncated and the
- * assistant's tool_calls are removed but the tool results remain.
- */
-function removeOrphanedToolResults(messages) {
-    // Collect all valid tool_call_ids from assistant messages
-    const validToolCallIds = new Set();
-    for (const message of messages) {
-        const msgAny = message;
-        if (message.role === 'assistant' && Array.isArray(msgAny.tool_calls)) {
-            for (const tc of msgAny.tool_calls) {
-                if (tc.id) {
-                    validToolCallIds.add(tc.id);
-                }
-            }
-        }
-    }
-    // Filter out tool messages with orphaned tool_call_ids
-    const filteredMessages = messages.filter((message) => {
-        const msgAny = message;
-        if (message.role === 'tool' && msgAny.tool_call_id) {
-            const isOrphaned = !validToolCallIds.has(msgAny.tool_call_id);
-            if (isOrphaned) {
-                logger.warn('Removing orphaned tool result', {
-                    tool_call_id: msgAny.tool_call_id,
-                    contentPreview: msgAny.content?.slice(0, 100),
-                });
-            }
-            return !isOrphaned;
-        }
-        return true;
-    });
-    return { messages: filteredMessages, changed: filteredMessages.length !== messages.length };
-}
 function getValidToolNames() {
     return new Set([...getAllTools(), subAgentTool]
         .map((tool) => tool.function?.name)
@@ -279,8 +38,7 @@ function getValidToolNames() {
  * 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.
+ * 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.
@@ -292,7 +50,7 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
     const sessionId = options.sessionId;
     const requestDefaults = options.requestDefaults || {};
     // The same AbortSignal is passed into every OpenAI SDK call and every
-    // sleepWithAbort() across all loop iterations and sub-agent calls.
+    // sleep across all loop iterations and sub-agent calls.
     // The SDK attaches an 'abort' listener per request, so on a long run
     // the default limit of 10 listeners is quickly exceeded, producing the
     // MaxListenersExceededWarning.  AbortSignal is a Web API EventTarget,
@@ -312,14 +70,14 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
         updatedMessages[systemMsgIndex] = { role: 'system', content: newSystemPrompt };
     }
     let iterationCount = 0;
-    let repairRetryCount = 0;
-    let contextRetryCount = 0;
-    let retriggerCount = 0;
-    let truncateRetryCount = 0;
-    let continueRetryCount = 0;
+    const retryState = {
+        repairCount: 0,
+        contextCount: 0,
+        truncateCount: 0,
+        continueCount: 0,
+        retriggerCount: 0,
+    };
     const MAX_RETRIGGERS = 3;
-    const MAX_TRUNCATE_RETRIES = 5;
-    const MAX_CONTINUE_RETRIES = 1;
     const validToolNames = getValidToolNames();
     while (iterationCount < maxIterations) {
         // Check if abort was requested
@@ -329,12 +87,16 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
             return updatedMessages;
         }
         iterationCount++;
-        // Check for compaction
+        // Check for compaction when we have pricing info (includes context window).
+        // Compaction preserves: (1) the system prompt at index 0, (2) any skill_content
+        // tool messages, and (3) the 5 most recent messages. Middle messages are
+        // summarized into a secondary system message. The length=0 + spread reassigns
+        // the array in place with the compacted structure.
         if (pricing) {
             const contextInfo = getContextInfo(updatedMessages, pricing);
             if (contextInfo.needsCompaction) {
-                const compacted = await compactIfNeeded(client, model, updatedMessages, pricing.contextWindow, contextInfo.currentTokens, requestDefaults, sessionId);
-                // Replace messages in-place
+                const compacted = await compactIfNeeded(client, model, updatedMessages, pricing.contextWindow, requestDefaults, sessionId);
+                // Replace messages in-place with compacted version
                 updatedMessages.length = 0;
                 updatedMessages.push(...compacted);
             }
@@ -349,34 +111,11 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
                 toolsCount: allTools.length,
                 messagesCount: updatedMessages.length,
             });
-            // 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),
-                    });
-                }
-                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,
-                        })),
-                    });
-                }
-                else {
-                    logger.trace('Message payload', {
-                        role: m.role,
-                        contentLength: m.content?.length,
-                    });
-                }
-            }
+            // Debug: log message roles and sizes
+            logger.trace('Messages', { msgs: updatedMessages.map((m) => ({
+                    role: m.role,
+                    len: m.content?.length || m.tool_calls?.length || 0,
+                })) });
             const stream = await client.chat.completions.create({
                 ...requestDefaults,
                 model,
@@ -388,112 +127,15 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
             }, {
                 signal: abortSignal,
             });
-            // Accumulate the streamed response
-            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 (and return to UI for immediate display via onEvent)
-                if (delta?.content) {
-                    streamedContent += delta.content;
-                    assistantMessage.content = streamedContent;
-                    if (!hasToolCalls) {
-                        onEvent({ type: 'text_delta', content: delta.content });
-                    }
-                }
-                // Accumulate tool calls across stream chunks
-                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: '' },
-                            };
-                        }
-                        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);
-                        }
-                        if (tc.function?.arguments) {
-                            assistantMessage.tool_calls[idx].function.arguments = appendStreamingFragment(assistantMessage.tool_calls[idx].function.arguments, tc.function.arguments);
-                        }
-                        // 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;
-                        }
-                    }
-                }
-            }
-            // Log API response with usage info at INFO level
-            {
-                const inputTokens = actualUsage?.prompt_tokens ?? estimateConversationTokens(updatedMessages);
-                const outputTokens = actualUsage?.completion_tokens ?? estimateTokens(assistantMessage.content || '');
-                const cachedTokens = actualUsage?.prompt_tokens_details?.cached_tokens;
-                const cost = pricing
-                    ? createUsageInfo(inputTokens, outputTokens, pricing, cachedTokens).estimatedCost
-                    : 0;
-                const contextPercent = pricing
-                    ? getContextInfo(updatedMessages, pricing).utilizationPercentage
-                    : 0;
-                logger.info('Received API response', {
-                    model,
-                    inputTokens,
-                    outputTokens,
-                    cachedTokens,
-                    cost: cost > 0 ? `$${cost.toFixed(4)}` : 'N/A',
-                    contextPercent: contextPercent > 0 ? `${contextPercent.toFixed(1)}%` : 'N/A',
-                    hasToolCalls: assistantMessage.tool_calls.length > 0,
-                    contentLength: assistantMessage.content?.length || 0,
-                });
-                onEvent({
-                    type: 'usage',
-                    usage: { inputTokens, outputTokens, cost, contextPercent },
-                });
-            }
-            // Log the full assistant message for debugging
-            logger.debug('Assistant response details', {
-                contentLength: assistantMessage.content?.length || 0,
-                contentPreview: assistantMessage.content?.slice(0, 200) || '(empty)',
-                toolCallsCount: assistantMessage.tool_calls?.length || 0,
-                toolCalls: assistantMessage.tool_calls?.map((tc) => ({
-                    id: tc.id,
-                    name: tc.function?.name,
-                    argsPreview: tc.function?.arguments?.slice(0, 100),
-                })),
-            });
+            // Process the streaming response
+            const streamResult = await processStream(stream, updatedMessages, model, pricing, onEvent);
+            assistantMessage = streamResult.assistantMessage;
             // Handle tool calls
-            if (assistantMessage.tool_calls.length > 0) {
+            if (streamResult.hasToolCalls) {
                 // Reset retrigger count on valid tool call response
-                retriggerCount = 0;
+                retryState.retriggerCount = 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,
-                        });
-                    }
-                    return sanitized.toolCall;
-                });
                 // Validate that all tool calls have valid JSON arguments
                 const invalidToolCalls = assistantMessage.tool_calls.filter((tc) => {
                     const args = tc.function?.arguments;
@@ -523,91 +165,19 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
                     tools: assistantMessage.tool_calls.map((tc) => tc.function?.name).join(', '),
                 });
                 updatedMessages.push(assistantMessage);
-                // Track which tool_call_ids still need a tool result message.
-                // This set is used to inject stub responses on abort, preventing
-                // orphaned tool_call_ids from permanently bricking the session.
-                const pendingToolCallIds = new Set(assistantMessage.tool_calls.map((tc) => tc.id));
-                const injectStubsForPendingToolCalls = () => {
-                    for (const id of pendingToolCallIds) {
-                        updatedMessages.push({
-                            role: 'tool',
-                            tool_call_id: id,
-                            content: 'Aborted by user.',
-                        });
-                    }
+                // Execute tool calls
+                const toolContext = {
+                    sessionId,
+                    abortSignal,
+                    requestDefaults,
+                    client,
+                    model,
+                    pricing,
                 };
-                for (const toolCall of assistantMessage.tool_calls) {
-                    // Check abort between tool calls
-                    if (abortSignal?.aborted) {
-                        logger.debug('Agentic loop aborted between tool calls');
-                        injectStubsForPendingToolCalls();
-                        emitAbortAndFinish(onEvent);
-                        return updatedMessages;
-                    }
-                    const { name, arguments: argsStr } = toolCall.function;
-                    onEvent({
-                        type: 'tool_call',
-                        toolCall: { id: toolCall.id, name, args: argsStr, status: 'running' },
-                    });
-                    try {
-                        const args = JSON.parse(argsStr);
-                        let result;
-                        // Handle sub-agent tool specially
-                        if (name === 'sub_agent') {
-                            const subProgress = (evt) => {
-                                onEvent({
-                                    type: 'sub_agent_iteration',
-                                    subAgentTool: { tool: evt.tool, status: evt.status, iteration: evt.iteration, args: evt.args },
-                                });
-                            };
-                            const subResult = await runSubAgent(client, model, args.task, args.max_iterations, requestDefaults, subProgress, abortSignal, pricing);
-                            result = subResult.response;
-                            // Emit sub-agent usage for the UI to add to total cost
-                            if (subResult.usage.inputTokens > 0 || subResult.usage.outputTokens > 0) {
-                                onEvent({
-                                    type: 'sub_agent_iteration',
-                                    subAgentUsage: subResult.usage,
-                                });
-                            }
-                        }
-                        else {
-                            result = await handleToolCall(name, args, { sessionId, abortSignal });
-                        }
-                        logger.info('Tool completed', {
-                            tool: name,
-                            resultLength: result.length,
-                        });
-                        updatedMessages.push({
-                            role: 'tool',
-                            tool_call_id: toolCall.id,
-                            content: result,
-                        });
-                        pendingToolCallIds.delete(toolCall.id);
-                        onEvent({
-                            type: 'tool_result',
-                            toolCall: { id: toolCall.id, name, args: argsStr, status: 'done', result },
-                        });
-                    }
-                    catch (err) {
-                        const errMsg = err instanceof Error ? err.message : String(err);
-                        updatedMessages.push({
-                            role: 'tool',
-                            tool_call_id: toolCall.id,
-                            content: `Error: ${errMsg}`,
-                        });
-                        pendingToolCallIds.delete(toolCall.id);
-                        // If the tool was aborted, inject stubs for remaining pending calls and stop
-                        if (abortSignal?.aborted || (err instanceof Error && (err.name === 'AbortError' || err.message === 'Operation aborted'))) {
-                            logger.debug('Agentic loop aborted during tool execution');
-                            injectStubsForPendingToolCalls();
-                            emitAbortAndFinish(onEvent);
-                            return updatedMessages;
-                        }
-                        onEvent({
-                            type: 'tool_result',
-                            toolCall: { id: toolCall.id, name, args: argsStr, status: 'error', result: errMsg },
-                        });
-                    }
+                const executionResult = await executeToolCalls(assistantMessage.tool_calls, updatedMessages, onEvent, toolContext);
+                if (executionResult.shouldAbort) {
+                    emitAbortAndFinish(onEvent);
+                    return updatedMessages;
                 }
                 // Signal UI that this iteration's tool calls are all done,
                 // so it can flush completed messages to static output.
@@ -622,20 +192,20 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
                     content: assistantMessage.content,
                 });
                 // Reset retrigger count on valid content response
-                retriggerCount = 0;
+                retryState.retriggerCount = 0;
             }
             // Check if we need to retrigger: if the last message is a tool result
             // but we got no assistant response (empty content, no tool_calls), the AI
             // may have stopped prematurely. Inject a 'continue' prompt and retry.
             const lastMessage = updatedMessages[updatedMessages.length - 1];
-            if (lastMessage?.role === 'tool' && retriggerCount < MAX_RETRIGGERS) {
-                retriggerCount++;
+            if (lastMessage?.role === 'tool' && retryState.retriggerCount < MAX_RETRIGGERS) {
+                retryState.retriggerCount++;
                 logger.warn('AI stopped after tool call without responding; retriggering', {
-                    retriggerCount,
+                    retriggerCount: retryState.retriggerCount,
                     maxRetriggers: MAX_RETRIGGERS,
                     lastMessageRole: lastMessage.role,
                     assistantContent: assistantMessage.content || '(empty)',
-                    hasToolCalls: assistantMessage.tool_calls.length > 0,
+                    hasToolCalls: assistantMessage.tool_calls?.length > 0,
                 });
                 // Inject a 'continue' prompt to help the AI continue
                 updatedMessages.push({
@@ -644,8 +214,9 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
                 });
                 continue;
             }
-            repairRetryCount = 0;
-            retriggerCount = 0;
+            // Reset retry counts on successful completion
+            retryState.repairCount = 0;
+            retryState.retriggerCount = 0;
             onEvent({ type: 'done' });
             return updatedMessages;
         }
@@ -685,170 +256,29 @@ export async function runAgenticLoop(client, model, messages, userInput, onEvent
                 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);
-                }
-            }
-            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),
-                })),
-            });
-            const retryableStatus = apiError?.status === 408 || apiError?.status === 409 || apiError?.status === 425;
-            const retryableCode = ['ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'ENETUNREACH', 'EAI_AGAIN'].includes(apiError?.code);
-            // Handle 400 errors: try sanitization first, then truncate messages
-            if (apiError?.status === 400) {
-                // Try sanitization first
-                if (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,
-                        });
-                        // Silently retry without showing error to user
-                        continue;
-                    }
-                }
-                // Try removing orphaned tool results
-                const orphanedRemoved = removeOrphanedToolResults(updatedMessages);
-                if (orphanedRemoved.changed) {
-                    updatedMessages.length = 0;
-                    updatedMessages.push(...orphanedRemoved.messages);
-                    logger.warn('400 response after orphaned tool results; retrying with cleaned messages');
-                    // Silently retry without showing error to user
-                    continue;
-                }
-                // If sanitization didn't help, try removing messages one at a time (up to 5)
-                if (truncateRetryCount < MAX_TRUNCATE_RETRIES) {
-                    truncateRetryCount++;
-                    const removedCount = Math.min(1, Math.max(0, updatedMessages.length - 2)); // Remove 1 at a time, keep system + at least 1 user
-                    if (removedCount > 0) {
-                        const removed = updatedMessages.splice(-removedCount);
-                        logger.debug('400 error: removing message from history to attempt fix', {
-                            truncateRetryCount,
-                            maxRetries: MAX_TRUNCATE_RETRIES,
-                            removedCount,
-                            removedRoles: removed.map((m) => m.role),
-                            removedPreviews: removed.map((m) => ({
-                                role: m.role,
-                                content: m.content?.slice(0, 100),
-                                tool_calls: m.tool_calls?.map((tc) => tc.function?.name),
-                            })),
-                        });
-                        // Silently retry without showing error to user
-                        continue;
-                    }
-                }
-                // After truncation retries exhausted, try adding a "continue" message
-                if (continueRetryCount < MAX_CONTINUE_RETRIES) {
-                    continueRetryCount++;
-                    updatedMessages.push({ role: 'user', content: 'continue' });
-                    logger.warn('400 error: adding "continue" message to retry', {
-                        continueRetryCount,
-                        messageCount: updatedMessages.length,
-                    });
-                    onEvent({
-                        type: 'error',
-                        error: 'Request failed. Retrying with "continue"...',
-                        transient: true,
-                    });
-                    continue;
-                }
+            // Handle API errors with retry strategies
+            const errorResult = await handleApiError(apiError, updatedMessages, validToolNames, pricing, retryState, iterationCount, onEvent, client, model, requestDefaults, sessionId);
+            if (errorResult.shouldAbort) {
+                emitAbortAndFinish(onEvent);
+                return updatedMessages;
             }
-            // Handle context-window-exceeded (prompt too long) — attempt forced compaction
-            // This fires when our token estimate was too low (e.g. base64 images from MCP tools)
-            // and the request actually hit the hard provider limit.
-            const isContextTooLong = apiError?.status === 400 &&
-                typeof errMsg === 'string' &&
-                /prompt.{0,30}too long|context.{0,30}length|maximum.{0,30}token|tokens?.{0,10}exceed/i.test(errMsg);
-            if (isContextTooLong && contextRetryCount < 2) {
-                contextRetryCount++;
-                logger.warn(`Prompt too long (attempt ${contextRetryCount}); forcing compaction`, { errMsg });
+            if (!errorResult.handled) {
+                // Non-retryable error
                 onEvent({
                     type: 'error',
-                    error: 'Prompt too long. Compacting conversation and retrying...',
-                    transient: true,
+                    error: errorResult.errorMessage || 'Unknown error',
+                    transient: errorResult.transient,
                 });
-                if (pricing) {
-                    // Use the normal LLM-based compaction path
-                    try {
-                        const compacted = await compactIfNeeded(client, model, updatedMessages, pricing.contextWindow, 
-                        // Pass the context window itself as currentTokens to force compaction
-                        pricing.contextWindow, requestDefaults, sessionId);
-                        updatedMessages.length = 0;
-                        updatedMessages.push(...compacted);
-                    }
-                    catch (compactErr) {
-                        logger.error(`Forced compaction failed: ${compactErr}`);
-                        // Fall through to truncation fallback below
-                    }
-                }
-                // Fallback: truncate any tool result messages whose content looks like
-                // base64 or is extremely large (e.g. MCP screenshot data)
-                const MAX_TOOL_RESULT_CHARS = 20_000;
-                for (let i = 0; i < updatedMessages.length; i++) {
-                    const m = updatedMessages[i];
-                    if (m.role === 'tool' && typeof m.content === 'string' && m.content.length > MAX_TOOL_RESULT_CHARS) {
-                        updatedMessages[i] = {
-                            ...m,
-                            content: m.content.slice(0, MAX_TOOL_RESULT_CHARS) + '\n... (truncated — content was too large)',
-                        };
-                    }
-                }
-                continue;
-            }
-            // 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;
-            }
-            // 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;
+                onEvent({ type: 'done' });
+                return updatedMessages;
             }
-            // 400 error that couldn't be fixed by sanitization or truncation
-            if (apiError?.status === 400) {
-                onEvent({
-                    type: 'error',
-                    error: `Request failed: ${errMsg}\n\nThe conversation history could not be automatically repaired. Try /clear to start fresh.`,
-                    transient: false,
-                });
+            // If handled but not silently, the error was already emitted
+            if (!errorResult.silentRetry) {
                 onEvent({ type: 'done' });
                 return updatedMessages;
             }
-            // Non-retryable error
-            onEvent({ type: 'error', error: errMsg });
-            onEvent({ type: 'done' });
-            return updatedMessages;
+            // Silent retry - continue the loop
+            continue;
         }
     }
     onEvent({ type: 'error', error: 'Maximum iteration limit reached.' });