byterover-cli 0.2.1 → 0.3.1

package/dist/infra/cipher/llm/context/loop-detector.js

@@ -0,0 +1,194 @@
+/**
+ * Loop Detector for Agent Tool Calls
+ *
+ * Detects repetitive tool call patterns to prevent the agent from:
+ * - Making the same tool call with identical arguments multiple times
+ * - Oscillating between two tool calls (A→B→A→B pattern)
+ *
+ * When a loop is detected, the caller should skip tool execution
+ * and inject a warning message to guide the LLM to try a different approach.
+ *
+ * Thread-safe: Uses AsyncMutex to protect shared state during parallel tool execution.
+ */
+import { AsyncMutex } from './async-mutex.js';
+/**
+ * Default configuration values.
+ */
+const DEFAULT_CONFIG = {
+    exactRepeatThreshold: 3,
+    oscillationThreshold: 2,
+    windowSize: 10,
+};
+/**
+ * Loop Detector.
+ *
+ * Tracks recent tool calls and detects repetitive patterns.
+ * This helps prevent the agent from wasting tokens and time
+ * on repeated unsuccessful attempts.
+ *
+ * Thread-safe: All mutating operations use AsyncMutex to ensure
+ * safe concurrent access during parallel tool execution.
+ *
+ * @example
+ * ```typescript
+ * const detector = new LoopDetector()
+ *
+ * // Before executing each tool call (async for thread safety)
+ * const result = await detector.recordAndCheck('read_file', { path: '/foo.ts' })
+ * if (result.isLoop) {
+ *   // Skip execution, inject warning to LLM
+ *   console.log(result.suggestion)
+ * } else {
+ *   // Execute tool normally
+ * }
+ * ```
+ */
+export class LoopDetector {
+    config;
+    mutex = new AsyncMutex();
+    recentCalls = [];
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get the number of recorded calls in the window.
+     */
+    getRecentCallCount() {
+        return this.recentCalls.length;
+    }
+    /**
+     * Record a tool call and check for loop patterns.
+     * Thread-safe: Uses mutex to protect shared state during parallel execution.
+     *
+     * @param toolName - Name of the tool being called
+     * @param args - Arguments passed to the tool
+     * @returns Detection result indicating if a loop was found
+     */
+    async recordAndCheck(toolName, args) {
+        return this.mutex.withLock(async () => {
+            const signature = this.createSignature(toolName, args);
+            this.recentCalls.push(signature);
+            // Trim to window size
+            if (this.recentCalls.length > this.config.windowSize) {
+                this.recentCalls.shift();
+            }
+            return this.detectLoop();
+        });
+    }
+    /**
+     * Reset the detector state.
+     * Should be called when starting a new conversation or task.
+     * Thread-safe: Uses mutex to protect shared state.
+     */
+    async reset() {
+        return this.mutex.withLock(async () => {
+            this.recentCalls = [];
+        });
+    }
+    /**
+     * Create a signature for a tool call.
+     */
+    createSignature(toolName, args) {
+        return {
+            argsHash: this.hashArgs(args),
+            timestamp: Date.now(),
+            toolName,
+        };
+    }
+    /**
+     * Detect exact repeat pattern: same call N times consecutively.
+     */
+    detectExactRepeat() {
+        if (this.recentCalls.length < this.config.exactRepeatThreshold) {
+            return { isLoop: false };
+        }
+        const lastCall = this.recentCalls.at(-1);
+        if (!lastCall) {
+            return { isLoop: false };
+        }
+        let repeatCount = 1;
+        // Count consecutive identical calls from the end
+        for (let i = this.recentCalls.length - 2; i >= 0; i--) {
+            if (this.signaturesMatch(this.recentCalls[i], lastCall)) {
+                repeatCount++;
+            }
+            else {
+                break;
+            }
+        }
+        if (repeatCount >= this.config.exactRepeatThreshold) {
+            return {
+                isLoop: true,
+                loopType: 'exact_repeat',
+                repeatCount,
+                suggestion: `Tool "${lastCall.toolName}" has been called ${repeatCount} times with the same arguments. This indicates a loop. Please try a different approach to accomplish your goal.`,
+            };
+        }
+        return { isLoop: false };
+    }
+    /**
+     * Detect loop patterns in recent calls.
+     */
+    detectLoop() {
+        // Pattern 1: Exact repeat (same tool+args N times in a row)
+        const exactRepeat = this.detectExactRepeat();
+        if (exactRepeat.isLoop) {
+            return exactRepeat;
+        }
+        // Pattern 2: Oscillation (A→B→A→B)
+        const oscillation = this.detectOscillation();
+        if (oscillation.isLoop) {
+            return oscillation;
+        }
+        return { isLoop: false };
+    }
+    /**
+     * Detect oscillation pattern: A→B→A→B.
+     */
+    detectOscillation() {
+        // Need at least 4 calls for one oscillation cycle (A→B→A→B)
+        const minCalls = this.config.oscillationThreshold * 2;
+        if (this.recentCalls.length < minCalls) {
+            return { isLoop: false };
+        }
+        // Check for A→B→A→B pattern in the last 4 calls
+        const calls = this.recentCalls.slice(-4);
+        // A[0] == A[2] and B[1] == B[3] and A[0] != B[1]
+        if (this.signaturesMatch(calls[0], calls[2]) &&
+            this.signaturesMatch(calls[1], calls[3]) &&
+            !this.signaturesMatch(calls[0], calls[1])) {
+            return {
+                isLoop: true,
+                loopType: 'oscillation',
+                repeatCount: 2,
+                suggestion: `Detected oscillation pattern between "${calls[0].toolName}" and "${calls[1].toolName}". The agent is alternating between these two tools without making progress. Please try a different strategy.`,
+            };
+        }
+        return { isLoop: false };
+    }
+    /**
+     * Create a deterministic hash of tool arguments.
+     * Sorts keys to ensure consistent ordering.
+     */
+    hashArgs(args) {
+        // Sort keys for deterministic serialization
+        const sortedKeys = Object.keys(args).sort();
+        const sortedArgs = {};
+        for (const key of sortedKeys) {
+            sortedArgs[key] = args[key];
+        }
+        return JSON.stringify(sortedArgs);
+    }
+    /**
+     * Check if two signatures represent the same tool call.
+     */
+    signaturesMatch(a, b) {
+        return a.toolName === b.toolName && a.argsHash === b.argsHash;
+    }
+}

package/dist/infra/cipher/llm/context/utils.d.ts

@@ -0,0 +1,17 @@
+import type { ITokenizer } from '../../../../core/interfaces/cipher/i-tokenizer.js';
+import type { InternalMessage } from '../../../../core/interfaces/cipher/message-types.js';
+/**
+ * Count total tokens in a message array.
+ * Adapted from dexto's token counting logic for cipher context.
+ *
+ * This provides a comprehensive token count including:
+ * - Role metadata tokens
+ * - Text content tokens
+ * - Multimodal content tokens (images, files)
+ * - Tool call tokens
+ *
+ * @param messages - Array of internal messages
+ * @param tokenizer - Tokenizer for counting
+ * @returns Total token count
+ */
+export declare function countMessagesTokens(messages: InternalMessage[], tokenizer: ITokenizer): number;

package/dist/infra/cipher/llm/context/utils.js

@@ -0,0 +1,89 @@
+/**
+ * Count tokens for a single content part
+ *
+ * @param part - Content part
+ * @param part.text - Text content (for text type)
+ * @param part.type - Type of content part
+ * @param tokenizer - Tokenizer for counting
+ * @returns Token count for the part
+ */
+function countPartTokens(part, tokenizer) {
+    switch (part.type) {
+        case 'file': {
+            // File content - rough estimate
+            // Similar to images, files can vary widely in token cost
+            return 100;
+        }
+        case 'image': {
+            // Image content - rough estimate
+            // Images are typically encoded and consume significant tokens
+            // Conservative estimate: ~100 tokens per image
+            return 100;
+        }
+        case 'text': {
+            // Text content - use tokenizer
+            return tokenizer.countTokens(part.text ?? '');
+        }
+        default: {
+            return 0;
+        }
+    }
+}
+/**
+ * Count tokens for message content
+ *
+ * @param content - Message content
+ * @param tokenizer - Tokenizer for counting
+ * @returns Token count for the content
+ */
+function countContentTokens(content, tokenizer) {
+    if (!content) {
+        return 0;
+    }
+    if (typeof content === 'string') {
+        // String content - use tokenizer
+        return tokenizer.countTokens(content);
+    }
+    if (Array.isArray(content)) {
+        // Array of parts (text, images, files)
+        let tokens = 0;
+        for (const part of content) {
+            tokens += countPartTokens(part, tokenizer);
+        }
+        return tokens;
+    }
+    return 0;
+}
+/**
+ * Count total tokens in a message array.
+ * Adapted from dexto's token counting logic for cipher context.
+ *
+ * This provides a comprehensive token count including:
+ * - Role metadata tokens
+ * - Text content tokens
+ * - Multimodal content tokens (images, files)
+ * - Tool call tokens
+ *
+ * @param messages - Array of internal messages
+ * @param tokenizer - Tokenizer for counting
+ * @returns Total token count
+ */
+export function countMessagesTokens(messages, tokenizer) {
+    let totalTokens = 0;
+    for (const message of messages) {
+        // Role token overhead (estimated)
+        // Each message has role metadata that consumes tokens
+        totalTokens += 4;
+        // Content tokens
+        totalTokens += countContentTokens(message.content, tokenizer);
+        // Tool call tokens
+        if (message.toolCalls) {
+            for (const call of message.toolCalls) {
+                // Tool calls are serialized as JSON
+                const callJson = JSON.stringify(call);
+                totalTokens += tokenizer.countTokens(callJson);
+            }
+        }
+    }
+    return totalTokens;
+}

package/dist/infra/cipher/llm/formatters/claude-formatter.d.ts

@@ -0,0 +1,54 @@
+import type { MessageCreateParamsBase, MessageParam } from '@anthropic-ai/sdk/resources/messages';
+import type { IMessageFormatter } from '../../../../core/interfaces/cipher/i-message-formatter.js';
+import type { InternalMessage } from '../../../../core/interfaces/cipher/message-types.js';
+export type { MessageParam as ClaudeMessage, Message as ClaudeResponse } from '@anthropic-ai/sdk/resources/messages';
+export type ClaudeGenerationConfig = Pick<MessageCreateParamsBase, 'max_tokens' | 'system' | 'temperature' | 'tools'>;
+/**
+ * Message formatter for Anthropic Claude API.
+ *
+ * Converts the internal message format to Claude's specific structure:
+ * - System prompts are NOT included in messages (handled separately in config)
+ * - Uses 'assistant' role (not 'model' like Gemini)
+ * - Tool calls use tool_use blocks with id and input
+ * - Tool results use tool_result blocks with tool_use_id
+ */
+export declare class ClaudeMessageFormatter implements IMessageFormatter<MessageParam> {
+    /**
+     * Formats internal messages into Claude's API format.
+     *
+     * IMPORTANT: System prompts are NOT included in the returned array.
+     * They should be passed separately via the config.system parameter.
+     *
+     * @param history Array of internal messages to format
+     * @param _systemPrompt System prompt (ignored - handled separately in config)
+     * @returns Array of MessageParam objects formatted for Claude's API
+     */
+    format(history: Readonly<InternalMessage[]>, _systemPrompt?: null | string): MessageParam[];
+    /**
+     * Parses Claude API response into internal message objects.
+     *
+     * @param response The raw response from Claude API
+     * @returns Array of internal messages (typically one assistant message)
+     */
+    parseResponse(response: unknown): InternalMessage[];
+    /**
+     * Formats assistant message to Claude's format.
+     * Uses 'assistant' role and includes both text and tool_use blocks.
+     */
+    private formatAssistantMessage;
+    /**
+     * Formats tool result message to Claude's format.
+     * Tool results are sent as user messages with tool_result blocks.
+     */
+    private formatToolResult;
+    /**
+     * Formats a single user content part.
+     * Currently supports text parts, with placeholders for image/file support.
+     */
+    private formatUserContentPart;
+    /**
+     * Formats user message to Claude's format.
+     * Handles both simple string content and multimodal content blocks.
+     */
+    private formatUserMessage;
+}

package/dist/infra/cipher/llm/formatters/claude-formatter.js

@@ -0,0 +1,182 @@
+/**
+ * Message formatter for Anthropic Claude API.
+ *
+ * Converts the internal message format to Claude's specific structure:
+ * - System prompts are NOT included in messages (handled separately in config)
+ * - Uses 'assistant' role (not 'model' like Gemini)
+ * - Tool calls use tool_use blocks with id and input
+ * - Tool results use tool_result blocks with tool_use_id
+ */
+export class ClaudeMessageFormatter {
+    /**
+     * Formats internal messages into Claude's API format.
+     *
+     * IMPORTANT: System prompts are NOT included in the returned array.
+     * They should be passed separately via the config.system parameter.
+     *
+     * @param history Array of internal messages to format
+     * @param _systemPrompt System prompt (ignored - handled separately in config)
+     * @returns Array of MessageParam objects formatted for Claude's API
+     */
+    format(history, _systemPrompt) {
+        const messages = [];
+        // Note: System prompt is NOT added to messages for Claude
+        // It's passed separately via config.system parameter
+        for (const msg of history) {
+            switch (msg.role) {
+                case 'assistant': {
+                    messages.push(this.formatAssistantMessage(msg));
+                    break;
+                }
+                case 'system': {
+                    // Skip system messages - they should be in config.system
+                    // Additional system messages in history are ignored
+                    break;
+                }
+                case 'tool': {
+                    messages.push(this.formatToolResult(msg));
+                    break;
+                }
+                case 'user': {
+                    messages.push(this.formatUserMessage(msg));
+                    break;
+                }
+            }
+        }
+        return messages;
+    }
+    /**
+     * Parses Claude API response into internal message objects.
+     *
+     * @param response The raw response from Claude API
+     * @returns Array of internal messages (typically one assistant message)
+     */
+    parseResponse(response) {
+        const typedResponse = response;
+        if (!typedResponse.content || typedResponse.content.length === 0) {
+            return [];
+        }
+        const textParts = [];
+        const toolUses = [];
+        // Extract text and tool uses from response content blocks
+        for (const block of typedResponse.content) {
+            if (block.type === 'text') {
+                textParts.push(block.text);
+            }
+            else if (block.type === 'tool_use') {
+                toolUses.push(block);
+            }
+        }
+        // Convert to internal message format
+        const toolCalls = toolUses.length > 0
+            ? toolUses.map((tu) => ({
+                function: {
+                    arguments: JSON.stringify(tu.input),
+                    name: tu.name,
+                },
+                id: tu.id,
+                type: 'function',
+            }))
+            : undefined;
+        return [
+            {
+                content: textParts.join('') || null,
+                role: 'assistant',
+                toolCalls,
+            },
+        ];
+    }
+    /**
+     * Formats assistant message to Claude's format.
+     * Uses 'assistant' role and includes both text and tool_use blocks.
+     */
+    formatAssistantMessage(msg) {
+        const contentBlocks = [];
+        // Add text content if present
+        if (msg.content) {
+            contentBlocks.push({
+                text: String(msg.content),
+                type: 'text',
+            });
+        }
+        // Add tool calls if present
+        if (msg.toolCalls) {
+            for (const tc of msg.toolCalls) {
+                contentBlocks.push({
+                    id: tc.id,
+                    input: JSON.parse(tc.function.arguments),
+                    name: tc.function.name,
+                    type: 'tool_use',
+                });
+            }
+        }
+        return {
+            content: contentBlocks,
+            role: 'assistant',
+        };
+    }
+    /**
+     * Formats tool result message to Claude's format.
+     * Tool results are sent as user messages with tool_result blocks.
+     */
+    formatToolResult(msg) {
+        return {
+            content: [
+                {
+                    content: String(msg.content ?? ''),
+                    tool_use_id: msg.toolCallId ?? '',
+                    type: 'tool_result',
+                },
+            ],
+            role: 'user',
+        };
+    }
+    /**
+     * Formats a single user content part.
+     * Currently supports text parts, with placeholders for image/file support.
+     */
+    formatUserContentPart(part) {
+        if (part.type === 'text') {
+            return { text: part.text, type: 'text' };
+        }
+        if (part.type === 'image') {
+            // Image support not yet implemented for Claude
+            // Claude supports images via base64 encoded data
+            return { text: '[Image not yet supported]', type: 'text' };
+        }
+        if (part.type === 'file') {
+            // File support not yet implemented for Claude
+            return { text: '[File not yet supported]', type: 'text' };
+        }
+        return { text: '[Unknown content type]', type: 'text' };
+    }
+    /**
+     * Formats user message to Claude's format.
+     * Handles both simple string content and multimodal content blocks.
+     */
+    formatUserMessage(msg) {
+        if (typeof msg.content === 'string') {
+            // Simple text message
+            return {
+                content: msg.content,
+                role: 'user',
+            };
+        }
+        if (Array.isArray(msg.content)) {
+            // Multimodal content (text, images, files)
+            const contentBlocks = [];
+            for (const part of msg.content) {
+                contentBlocks.push(this.formatUserContentPart(part));
+            }
+            return {
+                content: contentBlocks,
+                role: 'user',
+            };
+        }
+        // Empty content
+        return {
+            content: '',
+            role: 'user',
+        };
+    }
+}

package/dist/infra/cipher/llm/formatters/gemini-formatter.d.ts

@@ -0,0 +1,69 @@
+import type { Content } from '@google/genai';
+import type { IMessageFormatter } from '../../../../core/interfaces/cipher/i-message-formatter.js';
+import type { InternalMessage } from '../../../../core/interfaces/cipher/message-types.js';
+/**
+ * Message formatter for Google Gemini API.
+ *
+ * Converts the internal message format to Gemini's specific structure:
+ * - Maps 'assistant' role to 'model' (Gemini's terminology)
+ * - System prompts are injected as user messages (Gemini doesn't have system role)
+ * - Tool calls use functionCall parts
+ * - Tool results use functionResponse parts in user messages
+ */
+export declare class GeminiMessageFormatter implements IMessageFormatter<Content> {
+    /**
+     * Formats internal messages into Gemini's API format.
+     *
+     * @param history Array of internal messages to format
+     * @param systemPrompt Optional system prompt to include at the beginning
+     * @returns Array of Content objects formatted for Gemini's API
+     */
+    format(history: Readonly<InternalMessage[]>, systemPrompt?: null | string): Content[];
+    /**
+     * Parses Gemini API response into internal message objects.
+     *
+     * @param response The raw response from Gemini API
+     * @returns Array of internal messages (typically one assistant message)
+     */
+    parseResponse(response: unknown): InternalMessage[];
+    /**
+     * Combines multiple tool results into a single Gemini user message.
+     * Required by Gemini API when assistant made multiple tool calls.
+     */
+    private combineToolResults;
+    /**
+     * Formats assistant message to Gemini's Content format.
+     * Maps 'assistant' role to 'model' and includes both text and tool calls.
+     */
+    private formatAssistantMessage;
+    /**
+     * Formats a single non-tool message to Gemini Content.
+     */
+    private formatNonToolMessage;
+    /**
+     * Formats a single tool result message to a Gemini functionResponse Part.
+     * Multiple tool results are combined into a single user message by format().
+     *
+     * Note: msg.content is a JSON string from ToolOutputProcessor.
+     * We need to parse it back to an object for Gemini's API.
+     */
+    private formatToolResultPart;
+    /**
+     * Formats a single user content part.
+     * Currently supports text parts, with placeholders for image/file support.
+     */
+    private formatUserContentPart;
+    /**
+     * Formats user message to Gemini's Content format.
+     * Handles both simple string content and multimodal content parts.
+     */
+    private formatUserMessage;
+    /**
+     * Generates a unique tool call ID.
+     * Gemini doesn't provide tool call IDs, so we generate them.
+     *
+     * @param toolName The name of the tool being called
+     * @returns A unique identifier for the tool call
+     */
+    private generateToolCallId;
+}