@compilr-dev/agents 0.5.9 → 0.6.0

package/dist/agent.d.ts

@@ -86,6 +86,11 @@ export type AgentEvent = {
     type: 'tool_loop_warning';
     toolName: string;
     consecutiveCalls: number;
+} | {
+    type: 'tool_loop_nudge';
+    toolName: string;
+    consecutiveCalls: number;
+    nudgeCount: number;
 } | {
     type: 'abort_checkpoint_saved';
     sessionId: string;
@@ -222,10 +227,22 @@ export interface AgentConfig {
      */
     maxIterations?: number;
     /**
-     * Maximum consecutive identical tool calls before throwing ToolLoopError (default: 3).
-     * Set to 0 to disable loop detection.
+     * Maximum consecutive identical tool calls (same name + input + result) before
+     * the loop detector trips (default: 5). Set to 0 to disable loop detection.
+     *
+     * Detection is result-aware: a repeated call only counts when its result is
+     * also identical to the previous one, so legitimate polling that returns
+     * changing output (e.g. `bash_output` while a build runs) does not trip.
      */
     maxConsecutiveToolCalls?: number;
+    /**
+     * On a loop trip, how many times to inject a corrective "self-heal" message
+     * and let the agent continue before throwing ToolLoopError (default: 1).
+     * Set to 0 to throw immediately on the first trip (no self-heal).
+     *
+     * Ignored when `onToolLoopDetected` is provided (that callback takes over).
+     */
+    maxToolLoopNudges?: number;
     /**
      * Behavior when max iterations is reached (default: 'error').
      * - 'error': Throw MaxIterationsError immediately
@@ -888,6 +905,7 @@ export declare class Agent {
     private readonly systemPrompt;
     private readonly maxIterations;
     private readonly maxConsecutiveToolCalls;
+    private readonly maxToolLoopNudges;
     private readonly iterationLimitBehavior;
     private readonly chatOptions;
     private readonly toolRegistry;

package/dist/agent.js

@@ -44,6 +44,7 @@ export class Agent {
     systemPrompt;
     maxIterations;
     maxConsecutiveToolCalls;
+    maxToolLoopNudges;
     iterationLimitBehavior;
     chatOptions;
     toolRegistry;
@@ -122,7 +123,8 @@ export class Agent {
         this.provider = config.provider;
         this.systemPrompt = config.systemPrompt ?? '';
         this.maxIterations = config.maxIterations ?? 10;
-        this.maxConsecutiveToolCalls = config.maxConsecutiveToolCalls ?? 3;
+        this.maxConsecutiveToolCalls = config.maxConsecutiveToolCalls ?? 5;
+        this.maxToolLoopNudges = config.maxToolLoopNudges ?? 1;
         this.iterationLimitBehavior = config.iterationLimitBehavior ?? 'error';
         this.chatOptions = config.chatOptions ?? {};
         this.toolRegistry =
@@ -1759,6 +1761,8 @@ export class Agent {
         // Tool loop detection: track consecutive identical calls
         let lastToolCallHash = '';
         let consecutiveIdenticalCalls = 0;
+        // Self-heal: how many corrective nudges we've injected for the current streak
+        let loopNudgeCount = 0;
         // Hash function for tool call comparison.
         // Uses a JSON replacer that recursively sorts object keys for stable hashing.
         // NOTE: A simple `JSON.stringify(input, Object.keys(input).sort())` only sorts
@@ -1780,6 +1784,87 @@ export class Agent {
         const hashToolCall = (name, input) => {
             return `${name}:${stableStringify(input)}`;
         };
+        // Cheap djb2 string hash — keeps the result portion of the loop key small
+        // instead of carrying full (possibly large) tool output around.
+        const cheapHash = (s) => {
+            let h = 5381;
+            for (let i = 0; i < s.length; i++)
+                h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+            return String(h >>> 0);
+        };
+        /**
+         * Result-aware tool-loop detection with self-heal.
+         *
+         * A call counts toward a loop only when name + input + result all match the
+         * previous call (so progress-making polls don't trip). On a trip:
+         *  - if `onToolLoopDetected` is wired → legacy ask-continue/stop path;
+         *  - else inject a corrective message and continue, up to `maxToolLoopNudges`
+         *    times; after that, throw ToolLoopError.
+         *
+         * Pushes any nudge into both `messages` and `newMessages`, so it must run
+         * AFTER the tool result has been pushed (history stays valid on throw).
+         */
+        const handleToolLoop = async (toolUse, resultContent) => {
+            if (this.maxConsecutiveToolCalls <= 0)
+                return;
+            // Tools that are legitimately repeatable opt out entirely.
+            if (this.toolRegistry.get(toolUse.name)?.repeatable)
+                return;
+            const currentHash = `${hashToolCall(toolUse.name, toolUse.input)}#${cheapHash(resultContent)}`;
+            if (currentHash !== lastToolCallHash) {
+                // Different call/result → progress. Fresh slate.
+                lastToolCallHash = currentHash;
+                consecutiveIdenticalCalls = 1;
+                loopNudgeCount = 0;
+                return;
+            }
+            consecutiveIdenticalCalls++;
+            if (consecutiveIdenticalCalls < this.maxConsecutiveToolCalls) {
+                emit({
+                    type: 'tool_loop_warning',
+                    toolName: toolUse.name,
+                    consecutiveCalls: consecutiveIdenticalCalls,
+                });
+                return;
+            }
+            // ── Trip ──
+            // Legacy callback path (back-compat): ask the host to continue or stop.
+            if (this.onToolLoopDetected) {
+                const shouldContinue = await this.onToolLoopDetected({
+                    toolName: toolUse.name,
+                    consecutiveCalls: consecutiveIdenticalCalls,
+                    input: toolUse.input,
+                });
+                if (shouldContinue) {
+                    consecutiveIdenticalCalls = 0;
+                    return;
+                }
+                throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+            }
+            // Default: self-heal with a corrective message, up to maxToolLoopNudges.
+            if (loopNudgeCount < this.maxToolLoopNudges) {
+                loopNudgeCount++;
+                const nudge = {
+                    role: 'user',
+                    content: `[system reminder] You've called \`${toolUse.name}\` with identical input and an ` +
+                        `unchanged result ${String(consecutiveIdenticalCalls)} times in a row. If a process ` +
+                        `is still running, wait before polling again or tell the user what you're waiting on. ` +
+                        `Otherwise stop repeating this call and take a different step toward the goal.`,
+                };
+                messages.push(nudge);
+                newMessages.push(nudge);
+                emit({
+                    type: 'tool_loop_nudge',
+                    toolName: toolUse.name,
+                    consecutiveCalls: consecutiveIdenticalCalls,
+                    nudgeCount: loopNudgeCount,
+                });
+                consecutiveIdenticalCalls = 0;
+                return;
+            }
+            // Nudges exhausted → hard stop.
+            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+        };
         // Wrap agentic loop in try/finally to ensure conversation history is always
         // preserved, even when ToolLoopError or MaxIterationsError is thrown.
         // Without this, a thrown error skips the history append and the agent
@@ -2253,41 +2338,8 @@ export class Agent {
                             // 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) {
-                                        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',
-                                        toolName: toolUse.name,
-                                        consecutiveCalls: consecutiveIdenticalCalls,
-                                    });
-                                }
-                                else {
-                                    lastToolCallHash = currentHash;
-                                    consecutiveIdenticalCalls = 1;
-                                }
-                            }
+                            // Tool loop detection (result-aware + self-heal)
+                            await handleToolLoop(toolUse, toolResultMsg.content[0]?.content ?? '');
                             // Stamp for observation masking
                             if (this.observationMasker) {
                                 const block = toolResultMsg.content[0];
@@ -2314,40 +2366,8 @@ export class Agent {
                             // 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) {
-                                        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',
-                                        toolName: toolUse.name,
-                                        consecutiveCalls: consecutiveIdenticalCalls,
-                                    });
-                                }
-                                else {
-                                    lastToolCallHash = currentHash;
-                                    consecutiveIdenticalCalls = 1;
-                                }
-                            }
+                            // Tool loop detection (result-aware + self-heal)
+                            await handleToolLoop(toolUse, toolResultMsg.content[0]?.content ?? '');
                             // Stamp for observation masking
                             if (this.observationMasker) {
                                 const block = toolResultMsg.content[0];

package/dist/tools/define.d.ts

@@ -42,6 +42,11 @@ export interface DefineToolOptions<T extends object> {
      * Default: false
      */
     readonly?: boolean;
+    /**
+     * If true, this tool is exempt from tool-loop detection (repeated identical
+     * calls are always legitimate). Default: false.
+     */
+    repeatable?: boolean;
 }
 /**
  * Define a tool with type-safe input handling

package/dist/tools/define.js

@@ -35,6 +35,7 @@ export function defineTool(options) {
         parallel: options.parallel,
         silent: options.silent,
         readonly: options.readonly,
+        repeatable: options.repeatable,
     };
 }
 /**

package/dist/tools/types.d.ts

@@ -127,6 +127,13 @@ export interface Tool<T = object> {
      * Default: false
      */
     readonly?: boolean;
+    /**
+     * If true, this tool is exempt from tool-loop detection — repeated identical
+     * calls are always legitimate (e.g. genuinely idempotent pollers). Most
+     * polling tools do NOT need this: loop detection is result-aware, so calls
+     * that return changing output don't trip. Default: false.
+     */
+    repeatable?: boolean;
 }
 /**
  * Fallback handler for tools not found in the primary registry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.5.9",
+  "version": "0.6.0",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -93,7 +93,7 @@
     "js-tiktoken": "^1.0.21"
   },
   "overrides": {
-    "hono": "^4.11.10",
+    "hono": "^4.12.21",
     "minimatch": ">=10.2.1",
     "glob": ">=11.0.0"
   }