byterover-cli 1.6.0 → 1.7.0

package/dist/agent/core/interfaces/cipher-services.d.ts

@@ -0,0 +1,82 @@
+import type { AgentEventBus, SessionEventBus } from '../../infra/events/event-emitter.js';
+import type { FileSystemService } from '../../infra/file-system/file-system-service.js';
+import type { CompactionService } from '../../infra/llm/context/compaction/compaction-service.js';
+import type { MemoryManager } from '../../infra/memory/memory-manager.js';
+import type { ProcessService } from '../../infra/process/process-service.js';
+import type { MessageStorageService } from '../../infra/storage/message-storage-service.js';
+import type { SystemPromptManager } from '../../infra/system-prompt/system-prompt-manager.js';
+import type { ToolManager } from '../../infra/tools/tool-manager.js';
+import type { ToolProvider } from '../../infra/tools/tool-provider.js';
+import type { IBlobStorage } from './i-blob-storage.js';
+import type { IHistoryStorage } from './i-history-storage.js';
+import type { ILLMService } from './i-llm-service.js';
+import type { IPolicyEngine } from './i-policy-engine.js';
+import type { ISandboxService } from './i-sandbox-service.js';
+import type { IToolScheduler } from './i-tool-scheduler.js';
+/**
+ * Shared services created at agent level and shared across all sessions.
+ *
+ * These services are singletons that provide global functionality:
+ * - AgentEventBus: Global event bus for agent-level events
+ * - ToolManager: Manages tool registration and execution (stateless)
+ * - ToolScheduler: Orchestrates tool execution with policy checks
+ * - PolicyEngine: Rule-based ALLOW/DENY decisions for tools
+ * - SystemPromptManager: Builds system prompts using contributor pattern
+ * - FileSystemService: File system operations
+ * - ProcessService: Command execution
+ * - BlobStorage: Binary data storage
+ * - HistoryStorage: Conversation history persistence
+ * - MemoryManager: Agent memory system
+ * - ToolProvider: Provides available tools
+ */
+export interface CipherAgentServices {
+    agentEventBus: AgentEventBus;
+    blobStorage: IBlobStorage;
+    /**
+     * CompactionService for context overflow management.
+     * Only available when granular storage is enabled (useGranularStorage: true).
+     */
+    compactionService?: CompactionService;
+    fileSystemService: FileSystemService;
+    historyStorage: IHistoryStorage;
+    memoryManager: MemoryManager;
+    /**
+     * MessageStorageService for direct granular message access.
+     * Only available when granular storage is enabled (useGranularStorage: true).
+     */
+    messageStorageService?: MessageStorageService;
+    policyEngine: IPolicyEngine;
+    processService: ProcessService;
+    sandboxService: ISandboxService;
+    systemPromptManager: SystemPromptManager;
+    toolManager: ToolManager;
+    toolProvider: ToolProvider;
+    toolScheduler: IToolScheduler;
+}
+/**
+ * Session-specific services created per conversation session.
+ *
+ * These services are isolated per session to maintain conversation separation:
+ * - SessionEventBus: Session-scoped event bus
+ * - LLMService: LLM client with isolated context manager
+ */
+export interface SessionServices {
+    llmService: ILLMService;
+    sessionEventBus: SessionEventBus;
+}
+/**
+ * Configuration for SessionManager
+ */
+export interface SessionManagerConfig {
+    /**
+     * Maximum number of concurrent sessions allowed.
+     * Default: 100
+     */
+    maxSessions?: number;
+    /**
+     * Session time-to-live in milliseconds.
+     * Sessions inactive for longer than this will be cleaned up.
+     * Default: 3600000 (1 hour)
+     */
+    sessionTTL?: number;
+}

package/dist/agent/core/interfaces/i-blob-storage.d.ts

@@ -0,0 +1,84 @@
+import type { BlobMetadata, BlobStats, StoredBlob } from '../domain/blob/types.js';
+/**
+ * Interface for blob storage operations
+ * Provides persistent storage for binary/large data blobs
+ */
+export interface IBlobStorage {
+    /**
+     * Clear all blobs from storage
+     * WARNING: This is a destructive operation
+     *
+     * @throws If clearing fails
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the storage connection and release resources.
+     * Should be called when storage is no longer needed.
+     * Safe to call multiple times (idempotent).
+     */
+    close(): void;
+    /**
+     * Delete a blob by its key
+     *
+     * @param key - The blob identifier
+     *
+     * @throws If blob not found or deletion fails
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a blob exists
+     *
+     * @param key - The blob identifier
+     * @returns True if the blob exists, false otherwise
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get metadata for a blob without retrieving its content
+     *
+     * @param key - The blob identifier
+     * @returns The blob metadata, or undefined if not found
+     *
+     * @throws If retrieval fails
+     */
+    getMetadata(key: string): Promise<BlobMetadata | undefined>;
+    /**
+     * Get storage statistics
+     *
+     * @returns Statistics about the blob storage (count, total size, last updated)
+     */
+    getStats(): Promise<BlobStats>;
+    /**
+     * Initialize the storage system
+     * Must be called before any other operations
+     *
+     * @throws If initialization fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * List all blob keys, optionally filtered by prefix
+     *
+     * @param prefix - Optional prefix to filter keys
+     * @returns Array of blob keys matching the prefix
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Retrieve a blob by its key
+     *
+     * @param key - The blob identifier
+     * @returns The stored blob with content and metadata, or undefined if not found
+     *
+     * @throws If retrieval fails
+     */
+    retrieve(key: string): Promise<StoredBlob | undefined>;
+    /**
+     * Store a blob with optional metadata
+     *
+     * @param key - Unique identifier for the blob (alphanumeric, hyphens, underscores only)
+     * @param content - Blob content as Buffer or string
+     * @param metadata - Optional metadata (partial, defaults will be applied)
+     * @returns The stored blob with complete metadata
+     *
+     * @throws If key is invalid, content is too large, or storage fails
+     */
+    store(key: string, content: Buffer | string, metadata?: Partial<BlobMetadata>): Promise<StoredBlob>;
+}

package/dist/agent/core/interfaces/i-chat-session.d.ts

@@ -0,0 +1,107 @@
+import type { Message } from '../domain/session/types.js';
+import type { ExecutionContext } from './i-cipher-agent.js';
+import type { ILLMService } from './i-llm-service.js';
+/**
+ * Interface for a chat session.
+ * Represents an isolated conversation context with message history.
+ */
+export interface IChatSession {
+    /**
+     * Cancel the current operation.
+     * Aborts any ongoing LLM request.
+     */
+    cancel(): void;
+    /**
+     * Cleanup session resources but preserve history for later restoration.
+     * Call this when ending a session temporarily (e.g., user navigates away).
+     * History remains persisted; event listeners stay for potential reactivation.
+     */
+    cleanup(): void;
+    /**
+     * Dispose of the session completely and clean up all resources.
+     * Removes event listeners to prevent memory leaks.
+     * Should be called when session is permanently no longer needed.
+     */
+    dispose(): void;
+    /**
+     * Get the conversation history.
+     *
+     * @returns Array of messages in chronological order
+     */
+    getHistory(): Message[];
+    /**
+     * Get the LLM service for direct access to context manager.
+     * Useful for pre-loading conversation history in JSON input mode.
+     *
+     * @returns The LLM service instance
+     */
+    getLLMService(): ILLMService;
+    /**
+     * Get the number of messages in the conversation.
+     *
+     * @returns Message count
+     */
+    getMessageCount(): number;
+    /** Unique session identifier */
+    readonly id: string;
+    /**
+     * Reset the conversation history.
+     * Clears all messages except the system prompt (if present).
+     */
+    reset(): void;
+    /**
+     * Send a message and get a response.
+     * Handles tool execution loop automatically.
+     *
+     * @param input - User message content
+     * @param options - Optional execution options
+     * @param options.executionContext - Optional execution context
+     * @param options.taskId - Optional task ID for billing tracking and event correlation
+     * @param options.emitTaskId - Whether to include taskId in emitted events (default: true)
+     * @returns Assistant response
+     * @throws SessionCancelledError if operation is cancelled
+     * @throws MaxIterationsExceededError if tool loop exceeds maximum iterations
+     * @throws LLMError if LLM call fails
+     */
+    run(input: string, options?: {
+        emitTaskId?: boolean;
+        executionContext?: ExecutionContext;
+        taskId?: string;
+    }): Promise<string>;
+    /**
+     * Send a message, queuing if the session is busy executing.
+     * If the session is idle, executes immediately via run().
+     * If the session is busy, queues the message and returns the queue position.
+     *
+     * @param input - User message content
+     * @param options - Optional execution options and attachments
+     * @param options.executionContext - Optional execution context for the LLM
+     * @param options.fileData - Optional file attachment
+     * @param options.imageData - Optional image attachment
+     * @returns Response string if executed, or queue info if queued
+     */
+    sendMessage(input: string, options?: {
+        executionContext?: ExecutionContext;
+        fileData?: unknown;
+        imageData?: unknown;
+    }): Promise<string | {
+        position: number;
+        queued: true;
+    }>;
+    /**
+     * Stream execution with real-time event emission.
+     * Unlike run(), this does not return a response directly - events are yielded via the agent's stream().
+     * Emits run:complete event when finished.
+     *
+     * @param input - User message
+     * @param options - Execution options with optional signal for cancellation
+     * @param options.executionContext - Optional execution context for the LLM
+     * @param options.signal - Optional AbortSignal for cancellation
+     * @param options.taskId - Optional task ID for concurrent task isolation (included in all emitted events)
+     */
+    streamRun(input: string, options?: {
+        executionContext?: ExecutionContext;
+        signal?: AbortSignal;
+        taskId?: string;
+    }): Promise<void>;
+}

package/dist/agent/core/interfaces/i-cipher-agent.d.ts

@@ -0,0 +1,125 @@
+import type { TerminationReason } from '../domain/agent/agent-state.js';
+import type { SessionMetadata } from '../domain/storage/history-types.js';
+import type { GenerateResponse, StreamingEvent, StreamOptions } from '../domain/streaming/types.js';
+import type { ConversationMetadata } from '../domain/system-prompt/types.js';
+/**
+ * Execution context for the agent
+ * Contains runtime information about how the agent is being executed
+ */
+export interface ExecutionContext {
+    /** Command type that initiated the execution (for command-specific prompt loading) */
+    commandType?: 'chat' | 'curate' | 'query';
+    /** Metadata about the conversation (for JSON input mode) */
+    conversationMetadata?: ConversationMetadata;
+    /** File reference instructions for agent to read files (for curate command with --files flag) */
+    fileReferenceInstructions?: string;
+    /** Whether running in JSON input mode (headless with conversation history) */
+    isJsonInputMode?: boolean;
+}
+/**
+ * Agent execution state (string union for external consumers).
+ */
+export type AgentExecutionState = 'aborted' | 'complete' | 'error' | 'executing' | 'idle' | 'tool_calling';
+/**
+ * Agent state information.
+ *
+ * Enhanced to include execution state, termination reason, timing,
+ * and tool metrics. Maintains backward compatibility with legacy fields.
+ */
+export interface AgentState {
+    /** Current iteration/turn count */
+    currentIteration: number;
+    /** Execution duration in milliseconds (if available) */
+    durationMs?: number;
+    /** End time of execution (if complete) */
+    endTime?: Date;
+    /** Legacy: execution history records */
+    executionHistory: string[];
+    /** Current execution state */
+    executionState: AgentExecutionState;
+    /** Start time of execution (if started) */
+    startTime?: Date;
+    /** Why the execution terminated (if complete) */
+    terminationReason?: TerminationReason;
+    /** Number of tool calls executed */
+    toolCallsExecuted: number;
+}
+/**
+ * Interface for the CipherAgent
+ * Provides an agentic execution layer on top of the LLM service
+ */
+export interface ICipherAgent {
+    /**
+     * Cancels the currently running turn for the agent's default session.
+     * Safe to call even if no run is in progress.
+     *
+     * @returns true if a run was in progress and was signaled to abort; false otherwise
+     */
+    cancel(): Promise<boolean>;
+    /**
+     * Delete a session completely (memory + history)
+     * @param sessionId - Session ID to delete
+     * @returns True if session existed and was deleted
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Execute the agent with user input.
+     * Uses the agent's default session (created during start()).
+     *
+     * @param input - User input string
+     * @param options - Optional execution options
+     * @param options.executionContext - Optional context for command-specific behavior (curate/query/chat)
+     * @param options.taskId - Optional task ID for event routing (required for concurrent task isolation)
+     * @returns Agent response
+     */
+    execute(input: string, options?: {
+        executionContext?: ExecutionContext;
+        taskId?: string;
+    }): Promise<string>;
+    /**
+     * Generate a complete response (waits for full completion).
+     * Wrapper around stream() that collects all events and returns final result.
+     * Uses the agent's default session (created during start()).
+     *
+     * @param input - User message
+     * @param options - Optional configuration (signal for cancellation, taskId for billing)
+     * @returns Complete response with content, usage, and tool calls
+     */
+    generate(input: string, options?: StreamOptions): Promise<GenerateResponse>;
+    /**
+     * Get session metadata without loading full history
+     * @param sessionId - Session ID
+     * @returns Session metadata or undefined if not found
+     */
+    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * Get current agent state
+     * @returns Current state information
+     */
+    getState(): AgentState;
+    /**
+     * List all persisted session IDs from history storage
+     * @returns Array of session IDs
+     */
+    listPersistedSessions(): Promise<string[]>;
+    /**
+     * Reset the agent to initial state
+     * Clears execution history and resets iteration counter
+     */
+    reset(): void;
+    /**
+     * Start the agent - initializes all services asynchronously
+     * Must be called before execute()
+     */
+    start(): Promise<void>;
+    /**
+     * Stream a response (yields events as they arrive).
+     * This is the recommended method for real-time streaming UI updates.
+     * Uses the agent's default session (created during start()).
+     *
+     * @param input - User message
+     * @param options - Optional configuration (signal for cancellation, taskId for billing)
+     * @returns AsyncIterator that yields StreamingEvent objects
+     */
+    stream(input: string, options?: StreamOptions): Promise<AsyncIterableIterator<StreamingEvent>>;
+}

package/dist/agent/core/interfaces/i-content-generator.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Content Generator interface for LLM providers.
+ *
+ * This interface provides a unified abstraction for all LLM backends,
+ * enabling the decorator pattern for cross-cutting concerns like:
+ * - Logging
+ * - Retry with backoff
+ * - Recording/replay (future)
+ *
+ * Based on gemini-cli's ContentGenerator pattern.
+ */
+import type { ToolSet } from '../domain/tools/types.js';
+import type { ExecutionContext } from './i-cipher-agent.js';
+import type { InternalMessage, ToolCall } from './message-types.js';
+/**
+ * Stream chunk type for distinguishing content types during streaming.
+ */
+export declare enum StreamChunkType {
+    /** Regular text content */
+    CONTENT = "content",
+    /** Thinking/reasoning content from models like Gemini */
+    THINKING = "thinking",
+    /** Tool call request */
+    TOOL_CALL = "tool_call"
+}
+/**
+ * Configuration for content generation.
+ */
+export interface GenerationConfig {
+    /** Maximum tokens in the response */
+    maxTokens?: number;
+    /** Temperature for randomness (0-1) */
+    temperature?: number;
+    /** Top-K sampling parameter */
+    topK?: number;
+    /** Top-P (nucleus) sampling parameter */
+    topP?: number;
+}
+/**
+ * Request to generate content from an LLM.
+ */
+export interface GenerateContentRequest {
+    /** Generation configuration */
+    config: GenerationConfig;
+    /** Conversation history */
+    contents: InternalMessage[];
+    /** Optional execution context */
+    executionContext?: ExecutionContext;
+    /** Model identifier */
+    model: string;
+    /** Optional system prompt */
+    systemPrompt?: string;
+    /** Tracking task ID for backend billing metrics (random UUID per request) */
+    taskId: string;
+    /** Available tools for function calling */
+    tools?: ToolSet;
+}
+/**
+ * Response from content generation.
+ */
+export interface GenerateContentResponse {
+    /** Generated text content */
+    content: string;
+    /** Reason why generation stopped */
+    finishReason: 'error' | 'max_tokens' | 'stop' | 'tool_calls';
+    /** Raw response from provider (for debugging) */
+    rawResponse?: unknown;
+    /** Tool calls requested by the model */
+    toolCalls?: ToolCall[];
+    /** Token usage statistics */
+    usage?: {
+        /** Tokens used for completion */
+        completionTokens: number;
+        /** Tokens used for prompt */
+        promptTokens: number;
+        /** Total tokens used */
+        totalTokens: number;
+    };
+}
+/**
+ * Chunk of streaming content generation.
+ */
+export interface GenerateContentChunk {
+    /** Incremental text content */
+    content?: string;
+    /** Reason why generation stopped (only on final chunk) */
+    finishReason?: 'error' | 'max_tokens' | 'stop' | 'tool_calls';
+    /** Whether this is the final chunk */
+    isComplete: boolean;
+    /** Provider-specific metadata */
+    providerMetadata?: Record<string, unknown>;
+    /**
+     * Raw API chunk data for native reasoning extraction.
+     * Used by models that return reasoning in native fields (OpenAI, Grok, Gemini).
+     */
+    rawChunk?: unknown;
+    /**
+     * Incremental reasoning/thinking content.
+     * For models that provide native reasoning fields (OpenAI o1/o3, Grok, Gemini).
+     */
+    reasoning?: string;
+    /** Unique ID for the reasoning block (for tracking across deltas) */
+    reasoningId?: string;
+    /** Tool calls (only on final chunk or when complete) */
+    toolCalls?: ToolCall[];
+    /**
+     * Type of this chunk for distinguishing content from thinking.
+     * Defaults to CONTENT if not specified.
+     */
+    type?: StreamChunkType;
+}
+/**
+ * Content Generator interface.
+ *
+ * All LLM providers implement this interface, enabling:
+ * - Consistent API across providers
+ * - Decorator pattern for cross-cutting concerns
+ * - Easy testing with fake implementations
+ */
+export interface IContentGenerator {
+    /**
+     * Estimate tokens synchronously (fast, local).
+     *
+     * Uses a simple estimation algorithm for quick token counting.
+     * May not be perfectly accurate but is fast and doesn't require API calls.
+     *
+     * @param content - Text to estimate tokens for
+     * @returns Estimated token count
+     */
+    estimateTokensSync(content: string): number;
+    /**
+     * Generate content (non-streaming).
+     *
+     * @param request - Generation request
+     * @returns Generated content response
+     */
+    generateContent(request: GenerateContentRequest): Promise<GenerateContentResponse>;
+    /**
+     * Generate content with streaming.
+     *
+     * Yields chunks as they are generated, allowing for
+     * progressive display of responses.
+     *
+     * @param request - Generation request
+     * @returns Async generator yielding content chunks
+     */
+    generateContentStream(request: GenerateContentRequest): AsyncGenerator<GenerateContentChunk>;
+}