protoagent 0.1.13 → 0.1.15

package/dist/agentic-loop/errors.js

@@ -0,0 +1,198 @@
+// Error handling module for the agentic loop.
+// Handles API errors with various retry strategies:
+// - 400 errors: JSON repair, orphaned tool cleanup, truncation, "continue" prompts
+// - 429 errors: rate limit backoff
+// - 5xx errors: exponential backoff
+// - Context window exceeded: forced compaction
+import { compactIfNeeded } from '../utils/compactor.js';
+import { logger } from '../utils/logger.js';
+const LIMITS = {
+    MAX_REPAIR: 2,
+    MAX_CONTEXT: 2,
+    MAX_TRUNCATE: 5,
+    MAX_CONTINUE: 1,
+};
+// Sleep with abort signal support.
+export 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 });
+    });
+}
+// Handle an API error with appropriate retry strategy.
+export async function handleApiError(apiError, messages, _validToolNames, pricing, retryState, iterationCount, onEvent, client, model, requestDefaults, sessionId) {
+    const errMsg = apiError?.message || 'Unknown API error';
+    const status = apiError?.status;
+    logger.error(`API error: ${errMsg}`, { status, code: apiError?.code });
+    const retryableStatus = status === 408 || status === 409 || status === 425;
+    const retryableCode = ['ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'ENETUNREACH', 'EAI_AGAIN'].includes(apiError?.code);
+    // Context window exceeded - force compaction (check before generic 400 handling)
+    const isContextTooLong = status === 400 &&
+        /prompt.*too long|context.*length|maximum.*token|tokens?.*exceed/i.test(errMsg);
+    if (isContextTooLong && retryState.contextCount < LIMITS.MAX_CONTEXT) {
+        retryState.contextCount++;
+        logger.warn(`Prompt too long (attempt ${retryState.contextCount})`);
+        onEvent({
+            type: 'error',
+            error: 'Prompt too long. Compacting conversation...',
+            transient: true,
+        });
+        if (pricing && client && model) {
+            try {
+                const compacted = await compactIfNeeded(client, model, messages, pricing.contextWindow, requestDefaults || {}, sessionId);
+                messages.length = 0;
+                messages.push(...compacted);
+            }
+            catch (compactErr) {
+                logger.error(`Compaction failed: ${compactErr}`);
+            }
+        }
+        // Truncate oversized tool results as fallback
+        const MAX_TOOL_CHARS = 20_000;
+        for (let i = 0; i < messages.length; i++) {
+            const m = messages[i];
+            if (m.role === 'tool' && typeof m.content === 'string' && m.content.length > MAX_TOOL_CHARS) {
+                messages[i] = {
+                    ...m,
+                    content: m.content.slice(0, MAX_TOOL_CHARS) + '\n... (truncated)',
+                };
+            }
+        }
+        return { handled: true, shouldAbort: false, silentRetry: true };
+    }
+    // Rate limit - backoff
+    if (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...`, transient: true });
+        await sleepWithAbort(backoff);
+        return { handled: true, shouldAbort: false, silentRetry: true };
+    }
+    // Server error - exponential backoff
+    if (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...`, transient: true });
+        await sleepWithAbort(backoff);
+        return { handled: true, shouldAbort: false, silentRetry: true };
+    }
+    // Generic 400 errors - try repair/truncate/continue
+    if (status === 400) {
+        return await handle400Error(messages, retryState, onEvent);
+    }
+    // Non-retryable
+    return { handled: false, shouldAbort: false, silentRetry: false, errorMessage: errMsg };
+}
+// Handle 400 errors: repair JSON → remove orphaned → truncate → continue.
+async function handle400Error(messages, retryState, onEvent) {
+    // 1. Try JSON repairs on tool arguments
+    // Models sometimes emit invalid escape sequences in tool args (e.g., \| from grep regex)
+    // which cause JSON.parse to fail. These persist across requests unless repaired.
+    if (retryState.repairCount < LIMITS.MAX_REPAIR) {
+        let repaired = false;
+        for (const msg of messages) {
+            const msgAny = msg;
+            if (msg.role === 'assistant' && Array.isArray(msgAny.tool_calls)) {
+                for (const tc of msgAny.tool_calls) {
+                    const args = tc.function?.arguments;
+                    if (args && typeof args === 'string') {
+                        const fixed = repairInvalidEscapes(args);
+                        if (fixed !== args) {
+                            tc.function.arguments = fixed;
+                            repaired = true;
+                        }
+                    }
+                }
+            }
+        }
+        if (repaired) {
+            retryState.repairCount++;
+            logger.warn('400 response: repaired invalid JSON escapes');
+            return { handled: true, shouldAbort: false, silentRetry: true };
+        }
+    }
+    // 2. Remove orphaned tool results
+    // This happens when messages are truncated and the assistant's tool_calls are
+    // removed but the tool results remain. The API rejects orphaned tool results.
+    const cleaned = removeOrphanedToolResults(messages);
+    if (cleaned.changed) {
+        messages.length = 0;
+        messages.push(...cleaned.messages);
+        logger.warn('400 response: removed orphaned tool results');
+        return { handled: true, shouldAbort: false, silentRetry: true };
+    }
+    // 3. Truncate messages progressively
+    // If repairs didn't work, remove the last message (usually the problematic one)
+    // and retry. We keep at least system + 1 user message.
+    if (retryState.truncateCount < LIMITS.MAX_TRUNCATE && messages.length > 2) {
+        retryState.truncateCount++;
+        const removed = messages.splice(-1);
+        logger.debug('400 error: removed last message', {
+            role: removed[0]?.role,
+            remaining: messages.length,
+        });
+        return { handled: true, shouldAbort: false, silentRetry: true };
+    }
+    // 4. Try "continue" prompt
+    // Sometimes the model just needs a nudge to continue after getting stuck.
+    if (retryState.continueCount < LIMITS.MAX_CONTINUE) {
+        retryState.continueCount++;
+        messages.push({ role: 'user', content: 'continue' });
+        logger.warn('400 error: adding "continue" message');
+        onEvent({ type: 'error', error: 'Retrying with "continue"...', transient: true });
+        return { handled: true, shouldAbort: false, silentRetry: true };
+    }
+    // All strategies exhausted
+    return {
+        handled: false,
+        shouldAbort: false,
+        silentRetry: false,
+        errorMessage: 'Could not recover from error. Try /clear to start fresh.',
+    };
+}
+// Repair invalid JSON escape sequences.
+// Models sometimes emit \| \! \- etc. (e.g. grep regex args).
+function repairInvalidEscapes(value) {
+    return value.replace(/\\([^"\\\/bfnrtu])/g, '\\\\$1');
+}
+// Remove orphaned tool result messages that don't have a matching tool_call_id.
+function removeOrphanedToolResults(messages) {
+    const validToolCallIds = new Set();
+    for (const msg of messages) {
+        const msgAny = msg;
+        if (msg.role === 'assistant' && Array.isArray(msgAny.tool_calls)) {
+            for (const tc of msgAny.tool_calls) {
+                if (tc.id)
+                    validToolCallIds.add(tc.id);
+            }
+        }
+    }
+    const filtered = messages.filter((msg) => {
+        const msgAny = msg;
+        if (msg.role === 'tool' && msgAny.tool_call_id) {
+            const isOrphaned = !validToolCallIds.has(msgAny.tool_call_id);
+            if (isOrphaned) {
+                logger.warn('Removing orphaned tool result', { id: msgAny.tool_call_id });
+            }
+            return !isOrphaned;
+        }
+        return true;
+    });
+    return { messages: filtered, changed: filtered.length !== messages.length };
+}

package/dist/agentic-loop/executor.js

@@ -0,0 +1,108 @@
+/**
+ * Tool execution module for the agentic loop.
+ *
+ * Handles execution of tool calls including special handling for
+ * sub-agents and proper abort signal management between tool calls.
+ */
+import { handleToolCall } from '../tools/index.js';
+import { runSubAgent } from '../sub-agent.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Execute all tool calls from an assistant message.
+ *
+ * Handles:
+ * - Abort checking between tool calls
+ * - Sub-agent special case with progress reporting
+ * - Error handling and result accumulation
+ * - Pending tool call tracking for abort scenarios
+ *
+ * Returns true if execution completed normally, false if aborted.
+ */
+export async function executeToolCalls(toolCalls, messages, onEvent, context) {
+    const { sessionId, abortSignal, requestDefaults, client, model, pricing } = context;
+    // 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(toolCalls.map((tc) => tc.id));
+    const injectStubsForPendingToolCalls = () => {
+        for (const id of pendingToolCallIds) {
+            messages.push({
+                role: 'tool',
+                tool_call_id: id,
+                content: 'Aborted by user.',
+            });
+        }
+    };
+    for (const toolCall of toolCalls) {
+        // Check abort between tool calls
+        if (abortSignal?.aborted) {
+            logger.debug('Agentic loop aborted between tool calls');
+            injectStubsForPendingToolCalls();
+            return { completed: false, shouldAbort: true };
+        }
+        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,
+            });
+            messages.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);
+            messages.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();
+                return { completed: false, shouldAbort: true };
+            }
+            onEvent({
+                type: 'tool_result',
+                toolCall: { id: toolCall.id, name, args: argsStr, status: 'error', result: errMsg },
+            });
+        }
+    }
+    return { completed: true, shouldAbort: false };
+}

package/dist/agentic-loop/stream.js

@@ -0,0 +1,109 @@
+/**
+ * Stream processing module for the agentic loop.
+ *
+ * Handles accumulation of streaming response chunks into a complete
+ * assistant message, including content, tool calls, and usage data.
+ */
+import { estimateTokens, estimateConversationTokens, createUsageInfo, getContextInfo } from '../utils/cost-tracker.js';
+import { logger } from '../utils/logger.js';
+/**
+ * Process a streaming API response, accumulating content and tool calls.
+ *
+ * Emits text_delta events for immediate UI display and usage info
+ * when available. Returns the complete accumulated message.
+ */
+export async function processStream(stream, messages, model, pricing, onEvent) {
+    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 (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 += tc.function.name;
+                }
+                if (tc.function?.arguments) {
+                    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;
+                }
+            }
+        }
+    }
+    // Calculate usage metrics
+    const inputTokens = actualUsage?.prompt_tokens ?? estimateConversationTokens(messages);
+    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(messages, pricing).utilizationPercentage
+        : 0;
+    // Log API response with usage info at INFO level
+    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),
+        })),
+    });
+    return {
+        assistantMessage,
+        hasToolCalls,
+        usage: { inputTokens, outputTokens, cost, contextPercent },
+    };
+}