@compilr-dev/agents 0.3.25 → 0.3.27

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.)
      */
@@ -348,9 +369,9 @@ export interface AgentConfig {
      */
     checkpointOnAbort?: boolean;
     /**
-     * Anchor manager options for critical information that survives context compaction.
+     * Pin manager options for critical information that survives context compaction.
      *
-     * Anchors are pieces of information that:
+     * Pins are pieces of information that:
      * - Never get compacted - Survive all context management
      * - Always re-injected - Present in every LLM call
      * - Scoped - Session, persistent, or temporary
@@ -359,7 +380,7 @@ export interface AgentConfig {
      * ```typescript
      * const agent = new Agent({
      *   provider,
-     *   anchors: {
+     *   pins: {
      *     maxAnchors: 20,
      *     maxTokens: 2000,
      *     persistPath: '~/.myapp/anchors.json',
@@ -368,6 +389,8 @@ export interface AgentConfig {
      * });
      * ```
      */
+    pins?: AnchorManagerOptions;
+    /** @deprecated Use `pins` instead */
     anchors?: AnchorManagerOptions;
     /**
      * Guardrail options for pattern-based safety checks.
@@ -848,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;
@@ -865,9 +889,9 @@ export declare class Agent {
      */
     private readonly subAgents;
     /**
-     * Anchor manager for critical information that survives context compaction
+     * Pin manager for critical information that survives context compaction
      */
-    private readonly anchorManager?;
+    private readonly pinManager?;
     /**
      * Guardrail manager for pattern-based safety checks
      */
@@ -1029,99 +1053,72 @@ export declare class Agent {
      */
     recordUsage(model: string, provider: string, tokens: TokenUsage): void;
     /**
-     * Add an anchor (critical information that survives context compaction).
+     * Add a pin (critical information that survives context compaction).
      *
-     * Anchors are injected into every LLM call and never get compacted.
+     * Pins are injected into every LLM call and never get compacted.
      * Use them for information that must not be forgotten.
      *
-     * @param input - Anchor input
-     * @returns The created anchor, or undefined if anchors are not enabled
+     * @param input - Pin input (uses AnchorInput type)
+     * @returns The created pin, or undefined if pins are not enabled
      *
      * @example
      * ```typescript
-     * // Session anchor - lives for this session only
-     * agent.addAnchor({
-     *   content: 'This session we implemented: edit tool, grep tool',
-     *   priority: 'critical',
-     *   scope: 'session',
-     * });
-     *
-     * // Safety anchor - persisted across sessions
-     * agent.addAnchor({
-     *   content: 'Never delete files in /important without confirmation',
-     *   priority: 'safety',
-     *   scope: 'persistent',
-     * });
-     *
-     * // Temporary anchor - expires after 1 hour
-     * agent.addAnchor({
-     *   content: 'Currently working on feature X',
+     * agent.addPin({
+     *   content: 'Team roster: $default, $arch',
      *   priority: 'info',
-     *   scope: 'temporary',
-     *   expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+     *   scope: 'session',
      * });
      * ```
      */
-    addAnchor(input: AnchorInput): Anchor | undefined;
+    addPin(input: AnchorInput): Anchor | undefined;
     /**
-     * Get an anchor by ID
+     * Get a pin by ID
      */
-    getAnchor(id: string): Anchor | undefined;
+    getPin(id: string): Anchor | undefined;
     /**
-     * Get all anchors, optionally filtered
-     *
-     * @param options - Query options for filtering
-     * @returns Array of anchors
-     *
-     * @example
-     * ```typescript
-     * // Get all anchors
-     * const all = agent.getAnchors();
-     *
-     * // Get only safety anchors
-     * const safety = agent.getAnchors({ priority: 'safety' });
-     *
-     * // Get session anchors with specific tags
-     * const tagged = agent.getAnchors({ scope: 'session', tags: ['files'] });
-     * ```
+     * Get all pins, optionally filtered
      */
-    getAnchors(options?: AnchorQueryOptions): Anchor[];
+    getPins(options?: AnchorQueryOptions): Anchor[];
     /**
-     * Check if an anchor exists
+     * Check if a pin exists
      */
-    hasAnchor(id: string): boolean;
+    hasPin(id: string): boolean;
     /**
-     * Remove an anchor by ID
+     * Remove a pin by ID
      *
-     * @returns true if anchor was removed, false if not found
+     * @returns true if pin was removed, false if not found
      */
-    removeAnchor(id: string): boolean;
+    removePin(id: string): boolean;
     /**
-     * Clear anchors based on criteria
-     *
-     * @param options - Clear options for filtering which anchors to remove
-     * @returns Number of anchors removed
-     *
-     * @example
-     * ```typescript
-     * // Clear all session anchors
-     * agent.clearAnchors({ scope: 'session' });
-     *
-     * // Clear expired temporary anchors
-     * agent.clearAnchors({ expiredOnly: true });
+     * Clear pins based on criteria
      *
-     * // Clear anchors with specific tags
-     * agent.clearAnchors({ tags: ['auto'] });
-     * ```
+     * @param options - Clear options for filtering which pins to remove
+     * @returns Number of pins removed
      */
-    clearAnchors(options?: AnchorClearOptions): number;
+    clearPins(options?: AnchorClearOptions): number;
     /**
-     * Get the anchor manager (if configured)
+     * Get the pin manager (if configured)
      */
-    getAnchorManager(): AnchorManager | undefined;
+    getPinManager(): AnchorManager | undefined;
     /**
-     * Check if anchors are enabled
+     * Check if pins are enabled
      */
+    hasPins(): boolean;
+    /** @deprecated Use addPin() instead */
+    addAnchor(input: AnchorInput): Anchor | undefined;
+    /** @deprecated Use getPin() instead */
+    getAnchor(id: string): Anchor | undefined;
+    /** @deprecated Use getPins() instead */
+    getAnchors(options?: AnchorQueryOptions): Anchor[];
+    /** @deprecated Use hasPin() instead */
+    hasAnchor(id: string): boolean;
+    /** @deprecated Use removePin() instead */
+    removeAnchor(id: string): boolean;
+    /** @deprecated Use clearPins() instead */
+    clearAnchors(options?: AnchorClearOptions): number;
+    /** @deprecated Use getPinManager() instead */
+    getAnchorManager(): AnchorManager | undefined;
+    /** @deprecated Use hasPins() instead */
     hasAnchors(): boolean;
     /**
      * Add a custom guardrail
@@ -1657,8 +1654,8 @@ export declare class Agent {
      * Generate a summary of messages using the LLM provider.
      * Used for context summarization when approaching limits.
      *
-     * If anchors are configured, the summary will prioritize keeping
-     * information related to anchor content (anchor-weighted summarization).
+     * If pins are configured, the summary will prioritize keeping
+     * information related to pinned content (pin-weighted summarization).
      */
     private generateSummary;
     /**

package/dist/agent.js

@@ -50,6 +50,7 @@ export class Agent {
     autoContextManagement;
     onEvent;
     onIterationLimitReached;
+    onToolLoopDetected;
     // Retry configuration
     retryConfig;
     // State management
@@ -69,9 +70,9 @@ export class Agent {
      */
     subAgents = new Map();
     /**
-     * Anchor manager for critical information that survives context compaction
+     * Pin manager for critical information that survives context compaction
      */
-    anchorManager;
+    pinManager;
     /**
      * Guardrail manager for pattern-based safety checks
      */
@@ -139,15 +140,18 @@ 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();
         this.autoCheckpoint = config.autoCheckpoint ?? false;
         this.checkpointOnAbort = config.checkpointOnAbort ?? false;
         this._createdAt = new Date().toISOString();
-        // Anchor management
-        if (config.anchors !== undefined) {
-            this.anchorManager = new AnchorManager(config.anchors);
+        // Pin management (backwards compat: accept `anchors` as alias for `pins`)
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        const pinConfig = config.pins ?? config.anchors;
+        if (pinConfig !== undefined) {
+            this.pinManager = new AnchorManager(pinConfig);
         }
         // Guardrail management
         if (config.guardrails !== undefined) {
@@ -427,128 +431,118 @@ export class Agent {
         this.usageTracker?.record({ model, provider, tokens });
     }
     // ==========================================================================
-    // Anchor Management - Critical information that survives context compaction
+    // Pin Management - Critical information that survives context compaction
     // ==========================================================================
     /**
-     * Add an anchor (critical information that survives context compaction).
+     * Add a pin (critical information that survives context compaction).
      *
-     * Anchors are injected into every LLM call and never get compacted.
+     * Pins are injected into every LLM call and never get compacted.
      * Use them for information that must not be forgotten.
      *
-     * @param input - Anchor input
-     * @returns The created anchor, or undefined if anchors are not enabled
+     * @param input - Pin input (uses AnchorInput type)
+     * @returns The created pin, or undefined if pins are not enabled
      *
      * @example
      * ```typescript
-     * // Session anchor - lives for this session only
-     * agent.addAnchor({
-     *   content: 'This session we implemented: edit tool, grep tool',
-     *   priority: 'critical',
-     *   scope: 'session',
-     * });
-     *
-     * // Safety anchor - persisted across sessions
-     * agent.addAnchor({
-     *   content: 'Never delete files in /important without confirmation',
-     *   priority: 'safety',
-     *   scope: 'persistent',
-     * });
-     *
-     * // Temporary anchor - expires after 1 hour
-     * agent.addAnchor({
-     *   content: 'Currently working on feature X',
+     * agent.addPin({
+     *   content: 'Team roster: $default, $arch',
      *   priority: 'info',
-     *   scope: 'temporary',
-     *   expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+     *   scope: 'session',
      * });
      * ```
      */
-    addAnchor(input) {
-        if (!this.anchorManager)
+    addPin(input) {
+        if (!this.pinManager)
             return undefined;
-        const anchor = this.anchorManager.add(input);
+        const anchor = this.pinManager.add(input);
         this.onEvent?.({ type: 'anchor_added', anchor });
         return anchor;
     }
     /**
-     * Get an anchor by ID
+     * Get a pin by ID
      */
-    getAnchor(id) {
-        return this.anchorManager?.get(id);
+    getPin(id) {
+        return this.pinManager?.get(id);
     }
     /**
-     * Get all anchors, optionally filtered
-     *
-     * @param options - Query options for filtering
-     * @returns Array of anchors
-     *
-     * @example
-     * ```typescript
-     * // Get all anchors
-     * const all = agent.getAnchors();
-     *
-     * // Get only safety anchors
-     * const safety = agent.getAnchors({ priority: 'safety' });
-     *
-     * // Get session anchors with specific tags
-     * const tagged = agent.getAnchors({ scope: 'session', tags: ['files'] });
-     * ```
+     * Get all pins, optionally filtered
      */
-    getAnchors(options) {
-        return this.anchorManager?.getAll(options) ?? [];
+    getPins(options) {
+        return this.pinManager?.getAll(options) ?? [];
     }
     /**
-     * Check if an anchor exists
+     * Check if a pin exists
      */
-    hasAnchor(id) {
-        return this.anchorManager?.has(id) ?? false;
+    hasPin(id) {
+        return this.pinManager?.has(id) ?? false;
     }
     /**
-     * Remove an anchor by ID
+     * Remove a pin by ID
      *
-     * @returns true if anchor was removed, false if not found
+     * @returns true if pin was removed, false if not found
      */
-    removeAnchor(id) {
-        if (!this.anchorManager)
+    removePin(id) {
+        if (!this.pinManager)
             return false;
-        const removed = this.anchorManager.remove(id);
+        const removed = this.pinManager.remove(id);
         if (removed) {
             this.onEvent?.({ type: 'anchor_removed', anchorId: id });
         }
         return removed;
     }
     /**
-     * Clear anchors based on criteria
-     *
-     * @param options - Clear options for filtering which anchors to remove
-     * @returns Number of anchors removed
-     *
-     * @example
-     * ```typescript
-     * // Clear all session anchors
-     * agent.clearAnchors({ scope: 'session' });
+     * Clear pins based on criteria
      *
-     * // Clear expired temporary anchors
-     * agent.clearAnchors({ expiredOnly: true });
-     *
-     * // Clear anchors with specific tags
-     * agent.clearAnchors({ tags: ['auto'] });
-     * ```
+     * @param options - Clear options for filtering which pins to remove
+     * @returns Number of pins removed
      */
-    clearAnchors(options) {
-        return this.anchorManager?.clear(options) ?? 0;
+    clearPins(options) {
+        return this.pinManager?.clear(options) ?? 0;
     }
     /**
-     * Get the anchor manager (if configured)
+     * Get the pin manager (if configured)
      */
-    getAnchorManager() {
-        return this.anchorManager;
+    getPinManager() {
+        return this.pinManager;
     }
     /**
-     * Check if anchors are enabled
+     * Check if pins are enabled
      */
+    hasPins() {
+        return this.pinManager !== undefined;
+    }
+    // --- Deprecated aliases (use pin methods instead) --------------------------
+    /** @deprecated Use addPin() instead */
+    addAnchor(input) {
+        return this.addPin(input);
+    }
+    /** @deprecated Use getPin() instead */
+    getAnchor(id) {
+        return this.getPin(id);
+    }
+    /** @deprecated Use getPins() instead */
+    getAnchors(options) {
+        return this.getPins(options);
+    }
+    /** @deprecated Use hasPin() instead */
+    hasAnchor(id) {
+        return this.hasPin(id);
+    }
+    /** @deprecated Use removePin() instead */
+    removeAnchor(id) {
+        return this.removePin(id);
+    }
+    /** @deprecated Use clearPins() instead */
+    clearAnchors(options) {
+        return this.clearPins(options);
+    }
+    /** @deprecated Use getPinManager() instead */
+    getAnchorManager() {
+        return this.getPinManager();
+    }
+    /** @deprecated Use hasPins() instead */
     hasAnchors() {
-        return this.anchorManager !== undefined;
+        return this.hasPins();
     }
     // ==========================================================================
     // Guardrail Management - Pattern-based safety checks
@@ -1535,25 +1529,25 @@ export class Agent {
         // Build messages: system prompt + history + new user message
         let messages = [];
         // Add system message if present
-        // NOTE: Anchors are now appended to the system prompt (not a separate message)
+        // NOTE: Pins are appended to the system prompt (not a separate message)
         // to avoid multiple system messages which can confuse Claude's role identity
         let systemContent = this.systemPrompt;
-        // Inject anchors into the system prompt (not as separate message)
-        if (this.anchorManager && this.anchorManager.size > 0) {
-            const anchorsContent = this.anchorManager.format();
-            if (anchorsContent) {
-                // Insert anchors BEFORE the role ending (if present) so role reinforcement stays at the end
+        // Inject pins into the system prompt (not as separate message)
+        if (this.pinManager && this.pinManager.size > 0) {
+            const pinsContent = this.pinManager.format();
+            if (pinsContent) {
+                // Insert pins BEFORE the role ending (if present) so role reinforcement stays at the end
                 const roleEndingMarker = '## YOUR ASSIGNED ROLE:';
                 const roleEndingIndex = systemContent.indexOf(roleEndingMarker);
                 if (roleEndingIndex > 0) {
-                    // Insert anchors before the role ending
+                    // Insert pins before the role ending
                     const beforeRole = systemContent.substring(0, roleEndingIndex);
                     const roleEnding = systemContent.substring(roleEndingIndex);
-                    systemContent = `${beforeRole}\n\n---\n\n## Active Anchors (Critical Information)\n\n${anchorsContent}\n\n---\n\n${roleEnding}`;
+                    systemContent = `${beforeRole}\n\n---\n\n## Pinned Context (Critical Information)\n\n${pinsContent}\n\n---\n\n${roleEnding}`;
                 }
                 else {
-                    // No role ending, just append anchors
-                    systemContent = `${systemContent}\n\n---\n\n## Active Anchors (Critical Information)\n\n${anchorsContent}`;
+                    // No role ending, just append pins
+                    systemContent = `${systemContent}\n\n---\n\n## Pinned Context (Critical Information)\n\n${pinsContent}`;
                 }
             }
         }
@@ -2099,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',
@@ -2118,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];
@@ -2142,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',
@@ -2161,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];
@@ -2498,25 +2527,25 @@ export class Agent {
      * Generate a summary of messages using the LLM provider.
      * Used for context summarization when approaching limits.
      *
-     * If anchors are configured, the summary will prioritize keeping
-     * information related to anchor content (anchor-weighted summarization).
+     * If pins are configured, the summary will prioritize keeping
+     * information related to pinned content (pin-weighted summarization).
      */
     async generateSummary(messages) {
-        // Build anchor context if available (for weighted summarization)
+        // Build pin context if available (for weighted summarization)
         let anchorContext = '';
-        if (this.anchorManager && this.anchorManager.size > 0) {
-            const anchors = this.anchorManager.getAll();
-            if (anchors.length > 0) {
-                const anchorItems = anchors.map((a) => `- [${a.priority}] ${a.content}`).join('\n');
+        if (this.pinManager && this.pinManager.size > 0) {
+            const pins = this.pinManager.getAll();
+            if (pins.length > 0) {
+                const pinItems = pins.map((a) => `- [${a.priority}] ${a.content}`).join('\n');
                 anchorContext = `
-## PRIORITY CONTEXT (Anchors)
+## PRIORITY CONTEXT (Pinned)
 
-The following are critical anchors that should be preserved in context. When summarizing,
-PRIORITIZE keeping information that relates to these anchors:
+The following are pinned items that should be preserved in context. When summarizing,
+PRIORITIZE keeping information that relates to these pins:
 
-${anchorItems}
+${pinItems}
 
-Ensure the summary captures any conversation details related to these anchors.
+Ensure the summary captures any conversation details related to these pinned items.
 `;
             }
         }
@@ -2525,7 +2554,7 @@ Ensure the summary captures any conversation details related to these anchors.
 2. Important context established
 3. Tasks completed or in progress
 4. Any relevant file paths or code snippets mentioned
-${anchorContext ? '5. Information related to the priority anchors listed below' : ''}
+${anchorContext ? '5. Information related to the pinned priority items below' : ''}
 ${anchorContext}
 Keep the summary under 500 words.
 

package/package.json

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