@compilr-dev/agents 0.3.26 → 0.3.28

package/dist/agent.d.ts

@@ -256,6 +256,27 @@ export interface AgentConfig {
         maxIterations: number;
         toolCallCount: number;
     }) => Promise<number | false>;
+    /**
+     * Callback when tool loop is detected (same tool called N times with identical input).
+     *
+     * When provided, the agent asks the user instead of throwing ToolLoopError.
+     * Return `true` to continue (reset the counter), `false` to stop.
+     *
+     * When not provided, ToolLoopError is thrown (backwards compatible).
+     *
+     * @example
+     * ```typescript
+     * onToolLoopDetected: async ({ toolName, consecutiveCalls }) => {
+     *   const answer = await askUser(`${toolName} called ${consecutiveCalls} times. Continue?`);
+     *   return answer === 'yes';
+     * }
+     * ```
+     */
+    onToolLoopDetected?: (context: {
+        toolName: string;
+        consecutiveCalls: number;
+        input: Record<string, unknown>;
+    }) => Promise<boolean>;
     /**
      * Chat options (model, temperature, etc.)
      */
@@ -850,6 +871,7 @@ export declare class Agent {
     private readonly autoContextManagement;
     private readonly onEvent?;
     private readonly onIterationLimitReached?;
+    private readonly onToolLoopDetected?;
     private readonly retryConfig;
     private readonly checkpointer?;
     private readonly _sessionId;

package/dist/agent.js

@@ -50,6 +50,7 @@ export class Agent {
     autoContextManagement;
     onEvent;
     onIterationLimitReached;
+    onToolLoopDetected;
     // Retry configuration
     retryConfig;
     // State management
@@ -139,6 +140,7 @@ export class Agent {
         }
         this.onEvent = config.onEvent;
         this.onIterationLimitReached = config.onIterationLimitReached;
+        this.onToolLoopDetected = config.onToolLoopDetected;
         // State management
         this.checkpointer = config.checkpointer;
         this._sessionId = config.sessionId ?? generateSessionId();
@@ -2091,13 +2093,36 @@ export class Agent {
                                 aborted = true;
                                 break;
                             }
+                            const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                            toolCalls.push(toolCallEntry);
+                            iterationToolCalls.push(toolCallEntry);
+                            // Always push the tool_result BEFORE loop detection
+                            // so the conversation history stays valid if we throw
+                            messages.push(toolResultMsg);
+                            newMessages.push(toolResultMsg);
                             // Tool loop detection (still applies per-tool)
                             if (this.maxConsecutiveToolCalls > 0) {
                                 const currentHash = hashToolCall(toolUse.name, toolUse.input);
                                 if (currentHash === lastToolCallHash) {
                                     consecutiveIdenticalCalls++;
                                     if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                                        throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                        if (this.onToolLoopDetected) {
+                                            // Ask user: continue or stop?
+                                            const shouldContinue = await this.onToolLoopDetected({
+                                                toolName: toolUse.name,
+                                                consecutiveCalls: consecutiveIdenticalCalls,
+                                                input: toolUse.input,
+                                            });
+                                            if (shouldContinue) {
+                                                consecutiveIdenticalCalls = 0; // Reset counter
+                                            }
+                                            else {
+                                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                            }
+                                        }
+                                        else {
+                                            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                        }
                                     }
                                     emit({
                                         type: 'tool_loop_warning',
@@ -2110,11 +2135,6 @@ export class Agent {
                                     consecutiveIdenticalCalls = 1;
                                 }
                             }
-                            const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                            toolCalls.push(toolCallEntry);
-                            iterationToolCalls.push(toolCallEntry);
-                            messages.push(toolResultMsg);
-                            newMessages.push(toolResultMsg);
                             // Stamp for observation masking
                             if (this.observationMasker) {
                                 const block = toolResultMsg.content[0];
@@ -2134,13 +2154,35 @@ export class Agent {
                                 aborted = true;
                                 break;
                             }
+                            const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                            toolCalls.push(toolCallEntry);
+                            iterationToolCalls.push(toolCallEntry);
+                            // Always push the tool_result BEFORE loop detection
+                            // so the conversation history stays valid if we throw
+                            messages.push(toolResultMsg);
+                            newMessages.push(toolResultMsg);
                             // Tool loop detection
                             if (this.maxConsecutiveToolCalls > 0) {
                                 const currentHash = hashToolCall(toolUse.name, toolUse.input);
                                 if (currentHash === lastToolCallHash) {
                                     consecutiveIdenticalCalls++;
                                     if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
-                                        throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                        if (this.onToolLoopDetected) {
+                                            const shouldContinue = await this.onToolLoopDetected({
+                                                toolName: toolUse.name,
+                                                consecutiveCalls: consecutiveIdenticalCalls,
+                                                input: toolUse.input,
+                                            });
+                                            if (shouldContinue) {
+                                                consecutiveIdenticalCalls = 0;
+                                            }
+                                            else {
+                                                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                            }
+                                        }
+                                        else {
+                                            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                                        }
                                     }
                                     emit({
                                         type: 'tool_loop_warning',
@@ -2153,11 +2195,6 @@ export class Agent {
                                     consecutiveIdenticalCalls = 1;
                                 }
                             }
-                            const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
-                            toolCalls.push(toolCallEntry);
-                            iterationToolCalls.push(toolCallEntry);
-                            messages.push(toolResultMsg);
-                            newMessages.push(toolResultMsg);
                             // Stamp for observation masking
                             if (this.observationMasker) {
                                 const block = toolResultMsg.content[0];

package/dist/providers/claude.d.ts

@@ -107,6 +107,18 @@ export declare class ClaudeProvider implements LLMProvider {
      * reducing token costs by up to 90% on subsequent requests.
      */
     private wrapSystemPromptWithCache;
+    /**
+     * Add cache_control breakpoint to conversation messages.
+     *
+     * Caches the conversation history prefix (all messages except the most recent turn).
+     * This avoids re-processing the entire history on each API call.
+     * Only applies when there are enough messages to benefit (>= 4 messages = 2+ turns).
+     *
+     * Strategy: place cache_control on the last content block of the second-to-last
+     * user message. This caches system + tools + all messages up to that point.
+     * Only the most recent user message is uncached (and processed at full cost).
+     */
+    private addCacheControlToMessages;
     /**
      * Add cache_control to the last tool definition.
      *

package/dist/providers/claude.js

@@ -66,7 +66,9 @@ export class ClaudeProvider {
                 model: options?.model ?? this.defaultModel,
                 max_tokens: options?.maxTokens ?? this.defaultMaxTokens,
                 system: shouldCache && systemPrompt ? this.wrapSystemPromptWithCache(systemPrompt) : systemPrompt,
-                messages: anthropicMessages,
+                messages: shouldCache
+                    ? this.addCacheControlToMessages(anthropicMessages)
+                    : anthropicMessages,
                 tools: tools.length > 0
                     ? shouldCache
                         ? this.addCacheControlToLastTool(tools)
@@ -255,6 +257,67 @@ export class ClaudeProvider {
             },
         ];
     }
+    /**
+     * Add cache_control breakpoint to conversation messages.
+     *
+     * Caches the conversation history prefix (all messages except the most recent turn).
+     * This avoids re-processing the entire history on each API call.
+     * Only applies when there are enough messages to benefit (>= 4 messages = 2+ turns).
+     *
+     * Strategy: place cache_control on the last content block of the second-to-last
+     * user message. This caches system + tools + all messages up to that point.
+     * Only the most recent user message is uncached (and processed at full cost).
+     */
+    addCacheControlToMessages(messages) {
+        // Need at least 4 messages (2 turns) to benefit from caching
+        if (messages.length < 4)
+            return messages;
+        // Find the second-to-last user message
+        let targetIndex = -1;
+        let userCount = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                userCount++;
+                if (userCount === 2) {
+                    targetIndex = i;
+                    break;
+                }
+            }
+        }
+        if (targetIndex < 0)
+            return messages;
+        // Clone messages to avoid mutating originals
+        const result = messages.map((msg, idx) => {
+            if (idx !== targetIndex)
+                return msg;
+            // Add cache_control to the last content block of this message
+            const content = msg.content;
+            if (typeof content === 'string') {
+                return {
+                    ...msg,
+                    content: [
+                        {
+                            type: 'text',
+                            text: content,
+                            cache_control: { type: 'ephemeral' },
+                        },
+                    ],
+                };
+            }
+            if (Array.isArray(content) && content.length > 0) {
+                const lastBlock = content[content.length - 1];
+                return {
+                    ...msg,
+                    content: [
+                        ...content.slice(0, -1),
+                        { ...lastBlock, cache_control: { type: 'ephemeral' } },
+                    ],
+                };
+            }
+            return msg;
+        });
+        return result;
+    }
     /**
      * Add cache_control to the last tool definition.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",