byterover-cli 0.2.1 → 0.3.0

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

@@ -0,0 +1,71 @@
+import type { AgentEventBus, SessionEventBus } from '../../../infra/cipher/events/event-emitter.js';
+import type { FileSystemService } from '../../../infra/cipher/file-system/file-system-service.js';
+import type { MemoryManager } from '../../../infra/cipher/memory/memory-manager.js';
+import type { ProcessService } from '../../../infra/cipher/process/process-service.js';
+import type { SimplePromptFactory } from '../../../infra/cipher/system-prompt/simple-prompt-factory.js';
+import type { ToolManager } from '../../../infra/cipher/tools/tool-manager.js';
+import type { ToolProvider } from '../../../infra/cipher/tools/tool-provider.js';
+import type { IBlobStorage } from './i-blob-storage.js';
+import type { ICodingAgentLogWatcher } from './i-coding-agent-log-watcher.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 { 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
+ * - SimplePromptFactory: Builds system prompts from simple YAML templates
+ * - FileSystemService: File system operations
+ * - ProcessService: Command execution
+ * - BlobStorage: Binary data storage
+ * - HistoryStorage: Conversation history persistence
+ * - MemoryManager: Agent memory system
+ * - ToolProvider: Provides available tools
+ * - CodingAgentLogWatcher: Watches coding agent logs for learning (optional)
+ */
+export interface CipherAgentServices {
+    agentEventBus: AgentEventBus;
+    blobStorage: IBlobStorage;
+    codingAgentLogWatcher?: ICodingAgentLogWatcher;
+    fileSystemService: FileSystemService;
+    historyStorage: IHistoryStorage;
+    memoryManager: MemoryManager;
+    policyEngine: IPolicyEngine;
+    processService: ProcessService;
+    promptFactory: SimplePromptFactory;
+    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/core/interfaces/cipher/cipher-services.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,78 @@
+import type { BlobMetadata, BlobStats, StoredBlob } from '../../domain/cipher/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>;
+    /**
+     * 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/core/interfaces/cipher/i-blob-storage.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,62 @@
+import type { Message } from '../../domain/cipher/session/types.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;
+    /**
+     * Dispose of the session and clean up resources.
+     * Removes event listeners to prevent memory leaks.
+     * Should be called when session is 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.mode - Optional mode for system prompt ('autonomous' enables autonomous mode)
+     * @param options.executionContext - Optional execution context
+     * @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?: {
+        executionContext?: import('./i-cipher-agent.js').ExecutionContext;
+        mode?: 'autonomous' | 'default' | 'query';
+    }): Promise<string>;
+}

package/dist/core/interfaces/cipher/i-chat-session.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,88 @@
+import type { TerminationReason } from '../../domain/cipher/agent/agent-state.js';
+import type { SessionMetadata } from '../../domain/cipher/storage/history-types.js';
+import type { ConversationMetadata } from '../../domain/cipher/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?: 'curate' | 'query';
+    /** Metadata about the conversation (for JSON input mode) */
+    conversationMetadata?: ConversationMetadata;
+    /** 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 {
+    /**
+     * 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
+     * @param input - User input string
+     * @param sessionId - Optional session ID
+     * @returns Agent response
+     */
+    execute(input: string, sessionId?: string): Promise<string>;
+    /**
+     * 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>;
+}

package/dist/core/interfaces/cipher/i-cipher-agent.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,20 @@
+import type { CleanSession } from '../../domain/entities/parser.js';
+import { Agent } from '../../domain/entities/agent.js';
+/**
+ * Interface for parsing coding agent log files.
+ * Implementations use the raw/clean parser pipeline to process log files
+ * from various coding agents (Claude Code, GitHub Copilot, Cursor, Codex, etc.).
+ */
+export interface ICodingAgentLogParser {
+    /**
+     * Parses coding agent log files using the configured IDE and chat log path.
+     *
+     * This method follows the two-phase raw/clean parser pipeline:
+     * 1. Raw Phase: Parse IDE-specific files, write to .brv/logs/{ide}/raw/
+     * 2. Clean Phase: Read from .brv/logs/{ide}/raw/, normalize to CleanSession format
+     *
+     * @returns A promise that resolves to a frozen array of CleanSession objects
+     * @throws Error if parsing fails at any phase
+     */
+    parse: (chatLogPath: string, ide: Agent) => Promise<readonly CleanSession[]>;
+}

package/dist/core/interfaces/cipher/i-coding-agent-log-parser.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,31 @@
+import type { CleanSession } from '../../domain/entities/parser.js';
+import { Agent } from '../../domain/entities/agent.js';
+/** Options for starting the coding agent log watcher. */
+export type CodingAgentLogWatcherOptions = {
+    codingAgentInfo: {
+        chatLogPath: string;
+        name: Agent;
+    };
+    /** Callback invoked when sessions are parsed from log files */
+    onCleanSession: (cleanSession: CleanSession) => Promise<void>;
+};
+/**
+ * Interface for watching coding agent log files and processing sessions.
+ * Implementations should handle the first watch (process existing files) differently from subsequent watches (only new/changed files).
+ */
+export interface ICodingAgentLogWatcher {
+    /**
+     * Checks if the watcher is currently active.
+     * @returns true if watching, false otherwise.
+     */
+    isWatching: () => boolean;
+    /**
+     * Starts watching the specified paths for coding agent log files.
+     * On initial start, processes existing files. Subsequent watches only process new or changed files.
+     * @param options Configuration options including paths and callback
+     * @throws Error if already watching or if paths are invalid
+     */
+    start: (options: CodingAgentLogWatcherOptions) => Promise<void>;
+    /** Stops watching for file changes and cleans up resources */
+    stop: () => Promise<void>;
+}

package/dist/core/interfaces/cipher/i-coding-agent-log-watcher.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,120 @@
+/**
+ * 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/cipher/tools/types.js';
+import type { ExecutionContext } from './i-cipher-agent.js';
+import type { InternalMessage, ToolCall } from './message-types.js';
+/**
+ * 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 (for autonomous mode, etc.) */
+    executionContext?: ExecutionContext;
+    /** Optional mode for system prompt ('autonomous' enables autonomous mode) */
+    mode?: 'autonomous' | 'default' | 'query';
+    /** Model identifier */
+    model: string;
+    /** Session identifier */
+    sessionId: string;
+    /** Optional system prompt */
+    systemPrompt?: 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;
+    /** Tool calls (only on final chunk or when complete) */
+    toolCalls?: ToolCall[];
+}
+/**
+ * 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>;
+}

package/dist/core/interfaces/cipher/i-content-generator.js

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export {};

package/dist/core/interfaces/cipher/i-event-emitter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Options for event listener registration.
+ */
+export interface EventListenerOptions {
+    /**
+     * AbortSignal for automatic listener cleanup.
+     * When the signal is aborted, the listener will be automatically removed.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Type-safe event emitter interface.
+ *
+ * @template TEventMap - Map of event names to their payload types
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   'user:login': { userId: string };
+ *   'user:logout': void;
+ * }
+ *
+ * const emitter: IEventEmitter<MyEvents> = ...;
+ *
+ * // Type-safe emission
+ * emitter.emit('user:login', { userId: '123' });
+ * emitter.emit('user:logout'); // No payload needed for void events
+ *
+ * // Type-safe listening
+ * emitter.on('user:login', (payload) => {
+ *   console.log(payload.userId); // TypeScript knows payload type
+ * });
+ *
+ * // AbortController cleanup
+ * const controller = new AbortController();
+ * emitter.on('user:login', handler, { signal: controller.signal });
+ * controller.abort(); // Automatically removes listener
+ * ```
+ */
+export interface IEventEmitter<TEventMap extends object> {
+    /**
+     * Emit an event with a payload.
+     *
+     * @param eventName - Name of the event to emit
+     * @param payload - Event payload (type-checked against TEventMap)
+     * @returns true if the event had listeners, false otherwise
+     */
+    emit<K extends keyof TEventMap>(eventName: K, ...payload: TEventMap[K] extends void ? [] : [TEventMap[K]]): boolean;
+    /**
+     * Remove an event listener.
+     *
+     * @param eventName - Name of the event
+     * @param listener - Callback function to remove
+     * @returns this (for chaining)
+     */
+    off<K extends keyof TEventMap>(eventName: K, listener: TEventMap[K] extends void ? () => void : (payload: TEventMap[K]) => void): this;
+    /**
+     * Register an event listener.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function (receives typed payload)
+     * @param options - Listener options (e.g., AbortSignal for cleanup)
+     * @returns this (for chaining)
+     */
+    on<K extends keyof TEventMap>(eventName: K, listener: TEventMap[K] extends void ? () => void : (payload: TEventMap[K]) => void, options?: EventListenerOptions): this;
+    /**
+     * Register a one-time event listener.
+     * The listener will be automatically removed after the first invocation.
+     *
+     * @param eventName - Name of the event to listen for
+     * @param listener - Callback function (receives typed payload)
+     * @param options - Listener options (e.g., AbortSignal for cleanup)
+     * @returns this (for chaining)
+     */
+    once<K extends keyof TEventMap>(eventName: K, listener: TEventMap[K] extends void ? () => void : (payload: TEventMap[K]) => void, options?: EventListenerOptions): this;
+}

package/dist/core/interfaces/cipher/i-event-emitter.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/cipher/i-file-system.d.ts

@@ -0,0 +1,68 @@
+import type { EditFileOptions, EditOperation, EditResult, FileContent, GlobOptions, GlobResult, ReadFileOptions, SearchOptions, SearchResult, WriteFileOptions, WriteResult } from '../../domain/cipher/file-system/types.js';
+/**
+ * Interface for file system operations.
+ * Provides secure, validated access to the file system with comprehensive
+ * path validation, size limits, and allow/block list enforcement.
+ */
+export interface IFileSystem {
+    /**
+     * Edit a file by replacing strings.
+     * Supports single replacement (requires unique match) or replace-all.
+     *
+     * @param filePath - Path to the file (relative or absolute)
+     * @param operation - Edit operation (old string, new string, replace-all flag)
+     * @param options - Edit options (encoding)
+     * @returns Edit result with replacements count and bytes written
+     * @throws FileNotFoundError if file doesn't exist
+     * @throws StringNotFoundError if old string not found
+     * @throws StringNotUniqueError if old string appears multiple times (and replaceAll=false)
+     */
+    editFile(filePath: string, operation: EditOperation, options?: EditFileOptions): Promise<EditResult>;
+    /**
+     * Find files matching a glob pattern.
+     *
+     * @param pattern - Glob pattern (e.g., src/\*\*\/\*.ts, \*.json)
+     * @param options - Glob options (cwd, max results, metadata)
+     * @returns Glob result with matched files and metadata
+     * @throws InvalidPatternError if pattern is invalid
+     */
+    globFiles(pattern: string, options?: GlobOptions): Promise<GlobResult>;
+    /**
+     * Initialize the file system service.
+     * Performs setup and validation of configuration.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Read the contents of a file.
+     *
+     * @param filePath - Path to the file (relative or absolute)
+     * @param options - Read options (pagination, encoding)
+     * @returns File content with metadata
+     * @throws FileNotFoundError if file doesn't exist
+     * @throws PathNotAllowedError if path is not in allowed paths
+     * @throws FileTooLargeError if file exceeds size limit
+     */
+    readFile(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
+    /**
+     * Search file contents for a pattern.
+     * Supports regex patterns and context lines.
+     *
+     * @param pattern - Search pattern (regex)
+     * @param options - Search options (glob filter, cwd, max results, context lines, case sensitivity)
+     * @returns Search result with matches and context
+     * @throws InvalidPatternError if pattern is invalid regex
+     */
+    searchContent(pattern: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Write content to a file.
+     * Overwrites existing files. Can create parent directories if requested.
+     *
+     * @param filePath - Path to the file (relative or absolute)
+     * @param content - Content to write
+     * @param options - Write options (directory creation, encoding)
+     * @returns Write result with path and bytes written
+     * @throws PathNotAllowedError if path is not in allowed paths
+     * @throws InvalidExtensionError if file has blocked extension
+     */
+    writeFile(filePath: string, content: string, options?: WriteFileOptions): Promise<WriteResult>;
+}

package/dist/core/interfaces/cipher/i-file-system.js

@@ -0,0 +1 @@
+export {};