byterover-cli 1.8.0 → 2.1.0

package/dist/agent/infra/llm/agent-llm-service.d.ts

@@ -0,0 +1,423 @@
+import type { ToolSet } from '../../core/domain/tools/types.js';
+import type { ExecutionContext } from '../../core/interfaces/i-cipher-agent.js';
+import type { IHistoryStorage } from '../../core/interfaces/i-history-storage.js';
+import type { ILLMService } from '../../core/interfaces/i-llm-service.js';
+import type { ILogger } from '../../core/interfaces/i-logger.js';
+import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
+import type { MemoryManager } from '../memory/memory-manager.js';
+import type { SystemPromptManager } from '../system-prompt/system-prompt-manager.js';
+import type { ToolManager } from '../tools/tool-manager.js';
+import type { CompactionService } from './context/compaction/compaction-service.js';
+import type { ICompressionStrategy } from './context/compression/types.js';
+import { type IContentGenerator } from '../../core/interfaces/i-content-generator.js';
+import { SessionEventBus } from '../events/event-emitter.js';
+import { ContextManager, type FileData, type ImageData } from './context/context-manager.js';
+import { type ThinkingConfig } from './thought-parser.js';
+import { type TruncationConfig } from './tool-output-processor.js';
+/**
+ * Configuration for ByteRover LLM service
+ */
+export interface AgentLLMServiceConfig {
+    maxInputTokens?: number;
+    maxIterations?: number;
+    maxTokens?: number;
+    model: string;
+    /**
+     * Explicit provider ID for formatter/tokenizer selection.
+     * When set, overrides the model-name-based heuristic detection.
+     * Used for direct provider connections (anthropic, openai, google, xai, groq, mistral).
+     */
+    provider?: string;
+    temperature?: number;
+    /**
+     * Thinking configuration for Gemini models (optional).
+     * If not provided, will be auto-configured based on model version.
+     */
+    thinkingConfig?: ThinkingConfig;
+    timeout?: number;
+    /**
+     * Truncation configuration for tool outputs (optional).
+     * If not provided, will use default truncation settings.
+     */
+    truncationConfig?: TruncationConfig;
+    verbose?: boolean;
+}
+/**
+ * LLM service configuration response
+ */
+export interface LLMServiceConfig {
+    configuredMaxInputTokens: number;
+    model: string;
+    modelMaxInputTokens: number;
+    provider: string;
+    router: string;
+}
+/**
+ * ByteRover LLM Service.
+ *
+ * Orchestrates the agentic loop using IContentGenerator for LLM calls.
+ * Responsibilities:
+ * - Manage conversation context via ContextManager
+ * - Execute agentic loop (call LLM → execute tools → repeat)
+ * - Delegate tool execution to ToolManager
+ * - Delegate LLM calls to IContentGenerator
+ * - Handle errors and iteration limits
+ *
+ * Does NOT:
+ * - Execute tools directly (uses ToolManager)
+ * - Store persistent history (uses in-memory ContextManager)
+ * - Format messages for specific providers (handled by generators)
+ * - Handle retry logic (handled by RetryableContentGenerator decorator)
+ */
+export declare class AgentLLMService implements ILLMService {
+    /** Cached base system prompt (everything built by SystemPromptManager) for reuse across iterations */
+    private cachedBasePrompt;
+    private readonly compactionService?;
+    private readonly config;
+    private readonly contextManager;
+    private readonly environmentBuilder;
+    private readonly formatter;
+    private readonly generator;
+    private readonly logger;
+    private readonly loopDetector;
+    /** Flag indicating memory was modified by tools during this task, requiring prompt rebuild */
+    private memoryDirtyFlag;
+    private readonly memoryManager?;
+    private readonly metadataHandler;
+    private readonly mutex;
+    private readonly outputProcessor;
+    private readonly providerId;
+    private readonly providerType;
+    /** Optional sandbox service for rolling checkpoint variable injection (Pattern 1) */
+    private readonly sandboxService?;
+    private readonly sessionEventBus;
+    private readonly sessionId;
+    private readonly systemPromptManager;
+    private readonly tokenizer;
+    private readonly toolManager;
+    private readonly workingDirectory;
+    /**
+     * Initialize a new ByteRover LLM service instance.
+     *
+     * Sets up the service with all required dependencies and initializes:
+     * - Context manager for conversation history
+     * - Message formatter (Gemini or Claude format based on model)
+     * - Token counter/tokenizer for the selected model
+     * - Configuration with sensible defaults
+     *
+     * Each service instance maintains isolated conversation context,
+     * allowing multiple concurrent sessions with separate histories.
+     *
+     * @param sessionId - Unique identifier for this session
+     * @param generator - Content generator for LLM calls (with decorators pre-applied)
+     * @param config - LLM service configuration (model, tokens, temperature)
+     * @param options - Service dependencies
+     * @param options.toolManager - Tool manager for executing agent tools
+     * @param options.systemPromptManager - System prompt manager for building system prompts
+     * @param options.memoryManager - Memory manager for agent memories
+     * @param options.sessionEventBus - Event bus for session lifecycle events
+     * @param options.compactionService - Optional compaction service for context overflow management
+     * @param options.historyStorage - Optional history storage for persistence
+     * @param options.logger - Optional logger for structured logging
+     * @param options.sandboxService - Optional sandbox service for rolling checkpoint variable injection
+     */
+    constructor(sessionId: string, generator: IContentGenerator, config: AgentLLMServiceConfig, options: {
+        compactionService?: CompactionService;
+        /** Optional compression strategies for context overflow management */
+        compressionStrategies?: ICompressionStrategy[];
+        historyStorage?: IHistoryStorage;
+        logger?: ILogger;
+        memoryManager?: MemoryManager;
+        /** Optional sandbox service for rolling checkpoint variable injection */
+        sandboxService?: ISandboxService;
+        sessionEventBus: SessionEventBus;
+        systemPromptManager: SystemPromptManager;
+        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 options - Execution options
+     * @param options.executionContext - Optional execution context
+     * @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.taskId - Task ID from usecase for billing tracking
+     * @returns Final assistant response
+     */
+    completeTask(textInput: string, options?: {
+        executionContext?: ExecutionContext;
+        fileData?: FileData;
+        imageData?: ImageData;
+        signal?: AbortSignal;
+        stream?: boolean;
+        taskId?: string;
+    }): Promise<string>;
+    /**
+     * Get all available tools for the agent.
+     *
+     * Retrieves the current set of tools that can be used during task execution.
+     * These tools are passed to the LLM to enable function calling capabilities.
+     *
+     * @returns Promise resolving to a map of tool names to their schemas
+     */
+    getAllTools(): Promise<ToolSet>;
+    /**
+     * Get the service's runtime configuration.
+     *
+     * Returns metadata about the service including:
+     * - Configured and model-specific token limits
+     * - Selected LLM model
+     * - Provider identity (e.g. 'byterover', 'anthropic', 'openrouter')
+     * - Router type (always 'in-built')
+     *
+     * This is useful for introspecting service capabilities and limits
+     * without needing access to the internal config object.
+     *
+     * @returns Service configuration object with model info and constraints
+     */
+    getConfig(): LLMServiceConfig;
+    /**
+     * Get access to the conversation context manager.
+     *
+     * Provides access to the ContextManager instance that maintains:
+     * - Conversation history (messages and responses)
+     * - Token counting and compression
+     * - Message formatting for the selected model
+     *
+     * Useful for:
+     * - Inspecting conversation state
+     * - Retrieving formatted messages
+     * - Managing context during multi-turn interactions
+     *
+     * @returns The ContextManager instance managing conversation state
+     */
+    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>;
+    /**
+     * Add a parallel tool result to the context.
+     * Called sequentially after parallel execution to preserve message order.
+     *
+     * @param result - Parallel tool result to add
+     */
+    private addParallelToolResultToContext;
+    /**
+     * Build generation request for the IContentGenerator.
+     *
+     * Converts internal context to the standardized GenerateContentRequest format.
+     *
+     * @param options - Request options
+     * @param options.systemPrompt - System prompt text
+     * @param options.tools - Available tools for function calling
+     * @param options.executionContext - Optional execution context
+     * @returns GenerateContentRequest for the generator
+     */
+    private buildGenerateContentRequest;
+    /**
+     * Build a compact progress summary from current messages.
+     * Used by rolling checkpoint to capture agentic state before clearing history.
+     *
+     * @param messages - Current conversation messages
+     * @returns JSON string summarizing progress
+     */
+    private buildProgressSummary;
+    /**
+     * Call LLM via generator and process the response.
+     *
+     * Uses the IContentGenerator interface which already has:
+     * - Retry logic (via RetryableContentGenerator decorator)
+     * - Logging (via LoggingContentGenerator decorator)
+     *
+     * @param request - Generation request
+     * @returns Parsed internal message from response
+     */
+    private callLLMAndParseResponse;
+    /**
+     * Streaming variant of callLLMAndParseResponse that:
+     * - Uses generateContentStream for real-time chunk delivery
+     * - Accumulates content and tool calls from chunks
+     * - Emits llmservice:chunk events for thinking/reasoning chunks
+     * - Returns complete InternalMessage when stream ends
+     *
+     * @param request - Generation request
+     * @param taskId - Task ID for event emission
+     * @returns Parsed internal message from accumulated stream
+     */
+    private callLLMAndParseResponseStreaming;
+    /**
+     * Check for context overflow and trigger compaction if needed.
+     * Called after each assistant response and after tool execution batches.
+     *
+     * Follows OpenCode's compaction patterns:
+     * - First tries pruning tool outputs (if overflow > 85%)
+     * - Then tries full compaction with LLM summary (if overflow > 95%)
+     *
+     * @param taskId - Task ID from usecase for billing tracking (passed from caller)
+     */
+    private checkAndTriggerCompaction;
+    /**
+     * Detect provider type from model name using the LLM registry.
+     *
+     * Uses explicit provider config first, then the centralized registry,
+     * and falls back to string prefix matching if model is not in registry.
+     *
+     * @param model - Model identifier
+     * @param explicitProvider - Optional explicit provider ID from config
+     * @returns Provider type ('claude', 'gemini', or 'openai')
+     */
+    private detectProviderType;
+    /**
+     * Determine which reflection prompt to add based on hierarchical priority.
+     * Only the highest priority eligible reflection is returned.
+     *
+     * Priority (highest to lowest):
+     * 1. final_iteration - query only, at the last iteration
+     * 2. near_max_iterations - general, at 80% threshold
+     * 3. mid_point_check - query only, at 50% threshold
+     * 4. completion_check - general, periodic every 3 iterations
+     *
+     * @param iterationCount - Current iteration count (0-indexed)
+     * @param commandType - Command type ('query' or 'curate')
+     * @returns Reflection type to add, or undefined if none eligible
+     */
+    private determineReflectionType;
+    /**
+     * Execute a single iteration of the agentic loop.
+     *
+     * @param options - Iteration options
+     * @param options.effectiveMaxIterations - Effective max iterations (per-invocation override or config default)
+     * @param options.executionContext - Optional execution context
+     * @param options.fileData - Optional file data (only used on first iteration)
+     * @param options.imageData - Optional image data (only used on first iteration)
+     * @param options.iterationCount - Current iteration number
+     * @param options.stream - Whether to stream response and emit thinking chunks
+     * @param options.taskId - Task ID from usecase for billing tracking
+     * @param options.textInput - User input text (only used on first iteration)
+     * @param options.tools - Available tools for this iteration
+     * @returns Final response string if complete, null if more iterations needed
+     */
+    private executeAgenticIteration;
+    /**
+     * Execute a single tool call in parallel (without adding to context).
+     * Returns all information needed to add the result to context later.
+     *
+     * @param toolCall - Tool call to execute
+     * @param taskId - Task ID from usecase for billing tracking (passed to subagents)
+     * @param executionContext - Optional execution context for context-aware tool behavior
+     * @returns Parallel tool result with all execution data
+     */
+    private executeToolCallParallel;
+    /**
+     * Extract text content from an internal message.
+     *
+     * @param message - Internal message
+     * @returns Text content as string
+     */
+    private extractTextContent;
+    /**
+     * Extract partial response from conversation history when max iterations reached.
+     * Returns the last assistant message or accumulated tool outputs.
+     *
+     * @returns Partial response string
+     */
+    private getPartialResponse;
+    /**
+     * Handle final response when there are no tool calls.
+     *
+     * @param lastMessage - Last message from LLM
+     * @param taskId - Optional task ID for concurrent task isolation
+     * @returns Final response content
+     */
+    private handleFinalResponse;
+    /**
+     * Handle LLM errors and re-throw or wrap appropriately.
+     *
+     * @param error - Error to handle
+     * @param taskId - Optional task ID for concurrent task isolation
+     */
+    private handleLLMError;
+    /**
+     * Handle agent termination due to timeout or max turns.
+     *
+     * Emits appropriate events and returns a partial response.
+     *
+     * @param reason - Why the agent is terminating
+     * @param stateMachine - The state machine for context
+     * @param taskId - Optional task ID for concurrent task isolation
+     * @returns Partial response or fallback message
+     */
+    private handleTermination;
+    /**
+     * Handle thoughts from LLM response (Gemini only).
+     *
+     * Extracts and emits thought events if present.
+     *
+     * @param message - Message potentially containing thoughts
+     * @param taskId - Optional task ID for concurrent task isolation
+     */
+    private handleThoughts;
+    /**
+     * Handle tool calls from LLM response.
+     * Uses tool parts with state machine: pending → running → completed/error.
+     * Executes tools in parallel for performance, but updates state in order.
+     *
+     * @param lastMessage - Last message containing tool calls
+     * @param taskId - Task ID from usecase for billing tracking (passed to subagents)
+     * @param executionContext - Optional execution context for context-aware tool behavior
+     * @returns Early exit result if setFinalResult() was called, undefined otherwise
+     */
+    private handleToolCalls;
+    /**
+     * Perform a rolling checkpoint: save progress to sandbox variable, clear history, re-inject prompt.
+     * This treats each batch of iterations as a mini-task, preventing unbounded token accumulation.
+     *
+     * @param iterationCount - Current iteration number
+     * @param sessionId - Session ID for sandbox variable injection
+     * @param textInput - Original user input text (for continuation prompt)
+     */
+    private performRollingCheckpoint;
+    /**
+     * Replace the DateTime section in a cached system prompt with a fresh timestamp.
+     * DateTimeContributor wraps its output in <dateTime>...</dateTime> XML tags,
+     * enabling reliable regex replacement without rebuilding the entire prompt.
+     *
+     * @param cachedPrompt - Previously cached system prompt
+     * @returns Updated prompt with fresh DateTime
+     */
+    private refreshDateTime;
+    /**
+     * Check if a rolling checkpoint should trigger.
+     * Triggers every N iterations for curate/query commands, or when token utilization is high.
+     *
+     * @param iterationCount - Current iteration number
+     * @param commandType - Command type (only curate/query trigger checkpoints)
+     * @param currentTokens - Current estimated token count for messages
+     * @returns True if checkpoint should trigger
+     */
+    private shouldTriggerCheckpoint;
+    /**
+     * Validate LLM configuration using Zod schema.
+     *
+     * Performs validation against the centralized LLM config schema.
+     * Logs warnings for invalid configurations but doesn't throw to maintain
+     * backward compatibility with existing code.
+     *
+     * @param model - Model name to validate
+     * @param maxInputTokens - Optional max input tokens to validate
+     */
+    private validateConfig;
+}