byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/llm/openrouter-llm-service.d.ts

@@ -0,0 +1,183 @@
+import type { ToolSet } from '../../../core/domain/cipher/tools/types.js';
+import type { ExecutionContext } from '../../../core/interfaces/cipher/i-cipher-agent.js';
+import type { IHistoryStorage } from '../../../core/interfaces/cipher/i-history-storage.js';
+import type { ILLMService } from '../../../core/interfaces/cipher/i-llm-service.js';
+import type { ILogger } from '../../../core/interfaces/cipher/i-logger.js';
+import type { MemoryManager } from '../memory/memory-manager.js';
+import type { SimplePromptFactory } from '../system-prompt/simple-prompt-factory.js';
+import type { ToolManager } from '../tools/tool-manager.js';
+import { SessionEventBus } from '../events/event-emitter.js';
+import { ContextManager, type FileData, type ImageData } from './context/context-manager.js';
+/**
+ * Configuration for OpenRouter LLM service
+ */
+export interface OpenRouterServiceConfig {
+    apiKey: string;
+    baseUrl?: string;
+    httpReferer?: string;
+    maxInputTokens?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    model?: string;
+    siteName?: string;
+    temperature?: number;
+    timeout?: number;
+    verbose?: boolean;
+}
+/**
+ * LLM service configuration response
+ */
+export interface LLMServiceConfig {
+    configuredMaxInputTokens: number;
+    model: string;
+    modelMaxInputTokens: number;
+    provider: string;
+    router: string;
+}
+/**
+ * OpenRouter LLM Service.
+ *
+ * Orchestrates the agentic loop for tool calling with OpenRouter.
+ * OpenRouter provides access to multiple LLM providers through an OpenAI-compatible API.
+ *
+ * Responsibilities:
+ * - Manage conversation context via ContextManager
+ * - Execute agentic loop (call LLM → execute tools → repeat)
+ * - Delegate tool execution to ToolManager
+ * - Format messages for OpenRouter API via formatter
+ * - Handle errors and iteration limits
+ *
+ * Does NOT:
+ * - Execute tools directly (uses ToolManager)
+ * - Store persistent history (uses in-memory ContextManager)
+ */
+export declare class OpenRouterLLMService implements ILLMService {
+    private readonly client;
+    private readonly config;
+    private readonly contextManager;
+    private readonly formatter;
+    private readonly logger;
+    private readonly memoryManager?;
+    private readonly promptFactory;
+    private readonly sessionEventBus;
+    private readonly tokenizer;
+    private readonly toolManager;
+    /**
+     * Creates a new OpenRouter LLM service
+     *
+     * @param sessionId - Unique session identifier
+     * @param config - Service configuration
+     * @param options - Service dependencies
+     * @param options.toolManager - Tool manager for tool execution
+     * @param options.systemPromptManager - Simple prompt factory for building system prompts
+     * @param options.sessionEventBus - Session event bus for emitting events
+     * @param options.memoryManager - Optional memory manager for agent memories
+     * @param options.historyStorage - Optional history storage for persistence
+     * @param options.logger - Optional logger for structured logging
+     */
+    constructor(sessionId: string, config: OpenRouterServiceConfig, options: {
+        historyStorage?: IHistoryStorage;
+        logger?: ILogger;
+        memoryManager?: MemoryManager;
+        sessionEventBus: SessionEventBus;
+        systemPromptManager: SimplePromptFactory;
+        toolManager: ToolManager;
+    });
+    /**
+     * Complete a task with tool calling support.
+     *
+     * This is the main entry point for the agentic loop.
+     * It handles:
+     * 1. Adding user message to context
+     * 2. Looping: call LLM → check for tool calls → execute tools
+     * 3. Returning final response when no more tool calls
+     *
+     * @param textInput - User input text
+     * @param sessionId - Session ID for tracking the conversation
+     * @param options - Execution options
+     * @param options.signal - Optional abort signal for cancellation
+     * @param options.imageData - Optional image data
+     * @param options.fileData - Optional file data
+     * @param options.stream - Whether to stream response (not implemented yet)
+     * @param options.executionContext - Optional execution context (for JSON input mode, etc.)
+     * @param options.mode - Optional mode for system prompt ('json-input' enables autonomous mode)
+     * @returns Final assistant response
+     */
+    completeTask(textInput: string, sessionId: string, options?: {
+        executionContext?: ExecutionContext;
+        fileData?: FileData;
+        imageData?: ImageData;
+        mode?: 'autonomous' | 'default' | 'query';
+        signal?: AbortSignal;
+        stream?: boolean;
+    }): Promise<string>;
+    /**
+     * Get all available tools from ToolManager.
+     */
+    getAllTools(): Promise<ToolSet>;
+    /**
+     * Get service configuration.
+     */
+    getConfig(): LLMServiceConfig;
+    /**
+     * Get the context manager instance.
+     */
+    getContextManager(): ContextManager<unknown>;
+    /**
+     * Initialize the LLM service by loading persisted history.
+     * Should be called after construction to restore previous conversation.
+     *
+     * @returns True if history was loaded, false otherwise
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Call LLM and parse the response.
+     *
+     * @param tools - Available tools for function calling
+     * @param formattedMessages - Formatted messages to send
+     * @returns Parsed message from LLM response
+     */
+    private callLLMAndParseResponse;
+    /**
+     * Execute a single iteration of the agentic loop.
+     *
+     * @param iterationCount - Current iteration number
+     * @param tools - Available tools for this iteration
+     * @param executionContext - Optional execution context
+     * @param mode - Optional mode for system prompt
+     * @returns Final response string if complete, null if more iterations needed
+     */
+    private executeAgenticIteration;
+    /**
+     * Execute a single tool call.
+     *
+     * @param toolCall - Tool call to execute
+     */
+    private executeToolCall;
+    /**
+     * Extract text content from an internal message.
+     *
+     * @param message - Internal message
+     * @returns Text content as string
+     */
+    private extractTextContent;
+    /**
+     * Handle final response when there are no tool calls.
+     *
+     * @param lastMessage - Last message from LLM
+     * @returns Final response content
+     */
+    private handleFinalResponse;
+    /**
+     * Handle LLM errors and re-throw or wrap appropriately.
+     *
+     * @param error - Error to handle
+     */
+    private handleLLMError;
+    /**
+     * Handle tool calls from LLM response.
+     *
+     * @param lastMessage - Last message containing tool calls
+     */
+    private handleToolCalls;
+}

package/dist/infra/cipher/llm/openrouter-llm-service.js

@@ -0,0 +1,386 @@
+import { OpenAI } from 'openai';
+import { LlmGenerationError, LlmMaxIterationsError, LlmResponseParsingError, } from '../../../core/domain/cipher/errors/llm-error.js';
+import { NoOpLogger } from '../../../core/interfaces/cipher/i-logger.js';
+import { getErrorMessage } from '../../../utils/error-helpers.js';
+import { ContextManager } from './context/context-manager.js';
+import { OpenRouterMessageFormatter } from './formatters/openrouter-formatter.js';
+import { OpenRouterTokenizer } from './tokenizers/openrouter-tokenizer.js';
+/**
+ * OpenRouter LLM Service.
+ *
+ * Orchestrates the agentic loop for tool calling with OpenRouter.
+ * OpenRouter provides access to multiple LLM providers through an OpenAI-compatible API.
+ *
+ * Responsibilities:
+ * - Manage conversation context via ContextManager
+ * - Execute agentic loop (call LLM → execute tools → repeat)
+ * - Delegate tool execution to ToolManager
+ * - Format messages for OpenRouter API via formatter
+ * - Handle errors and iteration limits
+ *
+ * Does NOT:
+ * - Execute tools directly (uses ToolManager)
+ * - Store persistent history (uses in-memory ContextManager)
+ */
+export class OpenRouterLLMService {
+    client;
+    config;
+    contextManager;
+    formatter;
+    logger;
+    memoryManager;
+    promptFactory;
+    sessionEventBus;
+    tokenizer;
+    toolManager;
+    /**
+     * Creates a new OpenRouter LLM service
+     *
+     * @param sessionId - Unique session identifier
+     * @param config - Service configuration
+     * @param options - Service dependencies
+     * @param options.toolManager - Tool manager for tool execution
+     * @param options.systemPromptManager - Simple prompt factory for building system prompts
+     * @param options.sessionEventBus - Session event bus for emitting events
+     * @param options.memoryManager - Optional memory manager for agent memories
+     * @param options.historyStorage - Optional history storage for persistence
+     * @param options.logger - Optional logger for structured logging
+     */
+    constructor(sessionId, config, options) {
+        this.toolManager = options.toolManager;
+        this.promptFactory = options.systemPromptManager;
+        this.memoryManager = options.memoryManager;
+        this.sessionEventBus = options.sessionEventBus;
+        this.logger = options.logger ?? new NoOpLogger();
+        this.config = {
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl ?? 'https://openrouter.ai/api/v1',
+            httpReferer: config.httpReferer,
+            maxInputTokens: config.maxInputTokens ?? 200_000,
+            maxIterations: config.maxIterations ?? 50,
+            maxTokens: config.maxTokens ?? 8192,
+            model: config.model ?? 'anthropic/claude-haiku-4.5',
+            siteName: config.siteName,
+            temperature: config.temperature ?? 0.7,
+            timeout: config.timeout,
+            verbose: config.verbose,
+        };
+        // Initialize OpenAI client with OpenRouter base URL
+        this.client = new OpenAI({
+            apiKey: this.config.apiKey,
+            baseURL: this.config.baseUrl,
+            defaultHeaders: {
+                ...(this.config.httpReferer && { 'HTTP-Referer': this.config.httpReferer }),
+                ...(this.config.siteName && { 'X-Title': this.config.siteName }),
+            },
+            timeout: this.config.timeout,
+        });
+        // Initialize formatter and tokenizer
+        this.formatter = new OpenRouterMessageFormatter();
+        this.tokenizer = new OpenRouterTokenizer();
+        // Initialize context manager with optional history storage
+        this.contextManager = new ContextManager({
+            formatter: this.formatter,
+            historyStorage: options.historyStorage,
+            maxInputTokens: this.config.maxInputTokens,
+            sessionId,
+            tokenizer: this.tokenizer,
+        });
+    }
+    /**
+     * Complete a task with tool calling support.
+     *
+     * This is the main entry point for the agentic loop.
+     * It handles:
+     * 1. Adding user message to context
+     * 2. Looping: call LLM → check for tool calls → execute tools
+     * 3. Returning final response when no more tool calls
+     *
+     * @param textInput - User input text
+     * @param sessionId - Session ID for tracking the conversation
+     * @param options - Execution options
+     * @param options.signal - Optional abort signal for cancellation
+     * @param options.imageData - Optional image data
+     * @param options.fileData - Optional file data
+     * @param options.stream - Whether to stream response (not implemented yet)
+     * @param options.executionContext - Optional execution context (for JSON input mode, etc.)
+     * @param options.mode - Optional mode for system prompt ('json-input' enables autonomous mode)
+     * @returns Final assistant response
+     */
+    async completeTask(textInput, sessionId, options) {
+        // Extract options with defaults
+        const { executionContext, fileData, imageData, mode, signal } = options ?? {};
+        // Add user message to context
+        await this.contextManager.addUserMessage(textInput, imageData, fileData);
+        // Get all available tools
+        const toolSet = this.toolManager.getAllTools();
+        const tools = Object.entries(toolSet).map(([name, schema]) => ({
+            function: {
+                description: schema.description ?? '',
+                name,
+                parameters: schema.parameters,
+            },
+            type: 'function',
+        }));
+        let iterationCount = 0;
+        // Agentic loop
+        while (iterationCount < this.config.maxIterations) {
+            // Check if aborted
+            if (signal?.aborted) {
+                throw new Error('Operation aborted');
+            }
+            try {
+                // eslint-disable-next-line no-await-in-loop -- Sequential iterations required for agentic loop
+                const result = await this.executeAgenticIteration(iterationCount, tools, executionContext, mode);
+                if (result !== null) {
+                    return result;
+                }
+                iterationCount++;
+            }
+            catch (error) {
+                this.handleLLMError(error);
+            }
+        }
+        // Max iterations exceeded
+        throw new LlmMaxIterationsError(this.config.maxIterations, 'openrouter', this.config.model);
+    }
+    /**
+     * Get all available tools from ToolManager.
+     */
+    async getAllTools() {
+        return this.toolManager.getAllTools();
+    }
+    /**
+     * Get service configuration.
+     */
+    getConfig() {
+        return {
+            configuredMaxInputTokens: this.config.maxInputTokens,
+            model: this.config.model,
+            modelMaxInputTokens: this.config.maxInputTokens,
+            provider: 'openrouter',
+            router: 'openrouter',
+        };
+    }
+    /**
+     * Get the context manager instance.
+     */
+    getContextManager() {
+        return this.contextManager;
+    }
+    /**
+     * Initialize the LLM service by loading persisted history.
+     * Should be called after construction to restore previous conversation.
+     *
+     * @returns True if history was loaded, false otherwise
+     */
+    async initialize() {
+        return this.contextManager.initialize();
+    }
+    /**
+     * Call LLM and parse the response.
+     *
+     * @param tools - Available tools for function calling
+     * @param formattedMessages - Formatted messages to send
+     * @returns Parsed message from LLM response
+     */
+    async callLLMAndParseResponse(tools, formattedMessages) {
+        // Call OpenRouter API via OpenAI client
+        const response = await this.client.chat.completions.create({
+            // eslint-disable-next-line camelcase
+            max_tokens: this.config.maxTokens,
+            messages: formattedMessages,
+            model: this.config.model,
+            temperature: this.config.temperature,
+            ...(tools.length > 0 && { tools: tools }),
+        });
+        // Parse response to internal format
+        const messages = this.formatter.parseResponse(response);
+        if (messages.length === 0) {
+            throw new LlmResponseParsingError('No messages returned from formatter', 'openrouter', this.config.model);
+        }
+        const lastMessage = messages.at(-1);
+        if (!lastMessage) {
+            throw new LlmResponseParsingError('Failed to get last message from response', 'openrouter', this.config.model);
+        }
+        return lastMessage;
+    }
+    /**
+     * Execute a single iteration of the agentic loop.
+     *
+     * @param iterationCount - Current iteration number
+     * @param tools - Available tools for this iteration
+     * @param executionContext - Optional execution context
+     * @param mode - Optional mode for system prompt
+     * @returns Final response string if complete, null if more iterations needed
+     */
+    async executeAgenticIteration(iterationCount, tools, executionContext, mode) {
+        // Build system prompt using SimplePromptFactory (before compression for correct token accounting)
+        const availableTools = this.toolManager.getToolNames();
+        const markersSet = this.toolManager.getAvailableMarkers();
+        // Convert Set<string> to Record<string, string> for SimplePromptFactory
+        const availableMarkers = {};
+        for (const marker of markersSet) {
+            availableMarkers[marker] = marker;
+        }
+        const systemPrompt = await this.promptFactory.buildSystemPrompt({
+            availableMarkers,
+            availableTools,
+            commandType: executionContext?.commandType,
+            conversationMetadata: executionContext?.conversationMetadata,
+            memoryManager: this.memoryManager,
+            mode,
+        });
+        // Verbose debug: Show complete system prompt
+        if (this.config.verbose) {
+            this.logger.debug('System prompt details', {
+                first500Chars: systemPrompt.slice(0, 500),
+                iteration: iterationCount + 1,
+                last500Chars: systemPrompt.slice(-500),
+                length: systemPrompt.length,
+                lines: systemPrompt.split('\n').length,
+            });
+        }
+        // Get formatted messages from context with compression (passing system prompt for token accounting)
+        const { formattedMessages, tokensUsed } = await this.contextManager.getFormattedMessagesWithCompression(systemPrompt);
+        // Verbose: Log formatted messages and token usage
+        if (this.config.verbose) {
+            this.logger.debug('Formatted messages for LLM', {
+                formattedMessages,
+                iteration: `${iterationCount + 1}/${this.config.maxIterations}`,
+                maxInputTokens: this.config.maxInputTokens,
+                tokensUsed,
+            });
+        }
+        // Emit thinking event
+        this.sessionEventBus.emit('llmservice:thinking');
+        // Call LLM and parse response
+        const lastMessage = await this.callLLMAndParseResponse(tools, formattedMessages);
+        // Check if there are tool calls
+        if (!lastMessage.toolCalls || lastMessage.toolCalls.length === 0) {
+            return this.handleFinalResponse(lastMessage);
+        }
+        // Has tool calls - handle them
+        await this.handleToolCalls(lastMessage);
+        return null;
+    }
+    /**
+     * Execute a single tool call.
+     *
+     * @param toolCall - Tool call to execute
+     */
+    async executeToolCall(toolCall) {
+        try {
+            const toolName = toolCall.function.name;
+            const toolArgs = JSON.parse(toolCall.function.arguments);
+            // Emit tool call event
+            this.sessionEventBus.emit('llmservice:toolCall', {
+                args: toolArgs,
+                callId: toolCall.id,
+                toolName,
+            });
+            // Execute tool via ToolManager (handles approval, routing, etc.)
+            const result = await this.toolManager.executeTool(toolName, toolArgs);
+            // Emit tool result event (success)
+            this.sessionEventBus.emit('llmservice:toolResult', {
+                callId: toolCall.id,
+                result,
+                success: true,
+                toolName,
+            });
+            // Add tool result to context
+            await this.contextManager.addToolResult(toolCall.id, toolName, result, { success: true });
+        }
+        catch (error) {
+            // Add error result to context
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Emit tool result event (error)
+            this.sessionEventBus.emit('llmservice:toolResult', {
+                callId: toolCall.id,
+                error: errorMessage,
+                success: false,
+                toolName: toolCall.function.name,
+            });
+            await this.contextManager.addToolResult(toolCall.id, toolCall.function.name, `Error: ${errorMessage}`, {
+                success: false,
+            });
+        }
+    }
+    /**
+     * Extract text content from an internal message.
+     *
+     * @param message - Internal message
+     * @returns Text content as string
+     */
+    extractTextContent(message) {
+        if (typeof message.content === 'string') {
+            return message.content;
+        }
+        if (Array.isArray(message.content)) {
+            return message.content
+                .filter((part) => part.type === 'text')
+                .map((part) => (part.type === 'text' ? part.text : ''))
+                .join('');
+        }
+        return '';
+    }
+    /**
+     * Handle final response when there are no tool calls.
+     *
+     * @param lastMessage - Last message from LLM
+     * @returns Final response content
+     */
+    async handleFinalResponse(lastMessage) {
+        const content = this.extractTextContent(lastMessage);
+        // Emit response event
+        this.sessionEventBus.emit('llmservice:response', {
+            content,
+            model: this.config.model,
+            provider: 'openrouter',
+        });
+        // Add assistant message to context
+        await this.contextManager.addAssistantMessage(content);
+        return content;
+    }
+    /**
+     * Handle LLM errors and re-throw or wrap appropriately.
+     *
+     * @param error - Error to handle
+     */
+    handleLLMError(error) {
+        // Emit error event
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.sessionEventBus.emit('llmservice:error', {
+            error: errorMessage,
+        });
+        // Re-throw LLM errors as-is
+        if (error instanceof LlmResponseParsingError ||
+            error instanceof LlmGenerationError ||
+            error instanceof LlmMaxIterationsError) {
+            throw error;
+        }
+        // Wrap other errors
+        if (error && typeof error === 'object' && 'message' in error) {
+            throw new LlmGenerationError(getErrorMessage(error), 'openrouter', this.config.model);
+        }
+        throw new LlmGenerationError(String(error), 'openrouter', this.config.model);
+    }
+    /**
+     * Handle tool calls from LLM response.
+     *
+     * @param lastMessage - Last message containing tool calls
+     */
+    async handleToolCalls(lastMessage) {
+        if (!lastMessage.toolCalls || lastMessage.toolCalls.length === 0) {
+            return;
+        }
+        // Has tool calls - add assistant message with tool calls
+        const assistantContent = this.extractTextContent(lastMessage);
+        await this.contextManager.addAssistantMessage(assistantContent, lastMessage.toolCalls);
+        // Execute tool calls via ToolManager
+        for (const toolCall of lastMessage.toolCalls) {
+            // eslint-disable-next-line no-await-in-loop -- Sequential tool execution required
+            await this.executeToolCall(toolCall);
+        }
+    }
+}

package/dist/infra/cipher/llm/response-validator.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Response Validation Layer
+ *
+ * Validates LLM responses before processing to catch malformed content.
+ * Pure validation only - retry logic is handled by RetryableContentGenerator.
+ */
+import type { InternalMessage } from '../../../core/interfaces/cipher/message-types.js';
+/**
+ * Types of validation errors that can occur
+ */
+export type ResponseValidationType = 'EMPTY_RESPONSE' | 'INVALID_ROLE' | 'MALFORMED_TOOL_CALL' | 'NO_CONTENT' | 'NO_MESSAGES';
+/**
+ * Error thrown when response validation fails
+ */
+export declare class ResponseValidationError extends Error {
+    /**
+     * Original response that failed validation (for debugging)
+     */
+    readonly originalResponse?: unknown;
+    /**
+     * Type of validation failure
+     */
+    readonly validationType: ResponseValidationType;
+    /**
+     * Create a new ResponseValidationError
+     *
+     * @param message - Human-readable error message
+     * @param validationType - Type of validation failure
+     * @param originalResponse - Original response object (optional)
+     */
+    constructor(message: string, validationType: ResponseValidationType, originalResponse?: unknown);
+    /**
+     * Convert error to JSON for serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Response validator with validation rules and helper methods.
+ *
+ * Pure validation only - no retry logic.
+ * Retry behavior is handled by RetryableContentGenerator decorator.
+ */
+export declare const ResponseValidator: {
+    /**
+     * Validate individual message structure
+     *
+     * Checks that message has:
+     * 1. Valid role (assistant)
+     * 2. Either content or tool calls
+     * 3. Well-formed tool calls (if present)
+     *
+     * @param message - Internal message to validate
+     * @throws ResponseValidationError if validation fails
+     */
+    readonly validateMessage: (message: InternalMessage) => void;
+    /**
+     * Validate parsed message array
+     *
+     * Checks that:
+     * 1. Array is not empty
+     * 2. Has at least one message
+     *
+     * @param messages - Parsed messages from formatter
+     * @throws ResponseValidationError if validation fails
+     */
+    readonly validateMessageArray: (messages: InternalMessage[]) => void;
+    /**
+     * Validate raw response from LLM provider
+     *
+     * Checks that response is:
+     * 1. Not null/undefined
+     * 2. An object
+     *
+     * @param response - Raw response from provider
+     * @throws ResponseValidationError if validation fails
+     */
+    readonly validateRawResponse: (response: unknown) => void;
+    /**
+     * Validate complete response after parsing
+     *
+     * Runs all validation checks on raw response, message array, and last message.
+     *
+     * @param response - Raw response from provider
+     * @param messages - Parsed messages from formatter
+     * @returns Last message if all validations pass
+     * @throws ResponseValidationError if any validation fails
+     */
+    readonly validateResponse: (response: unknown, messages: InternalMessage[]) => InternalMessage;
+};