byterover-cli 1.5.0 → 1.7.0

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

@@ -1,84 +0,0 @@
-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>;
-    /**
-     * 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/core/interfaces/cipher/i-chat-session.d.ts

@@ -1,107 +0,0 @@
-import type { Message } from '../../domain/cipher/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/core/interfaces/cipher/i-cipher-agent.d.ts

@@ -1,125 +0,0 @@
-import type { TerminationReason } from '../../domain/cipher/agent/agent-state.js';
-import type { SessionMetadata } from '../../domain/cipher/storage/history-types.js';
-import type { GenerateResponse, StreamingEvent, StreamOptions } from '../../domain/cipher/streaming/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?: '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/core/interfaces/cipher/i-content-generator.d.ts

@@ -1,148 +0,0 @@
-/**
- * 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';
-/**
- * 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>;
-}

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

@@ -1,79 +0,0 @@
-import type { EditFileOptions, EditOperation, EditResult, FileContent, GlobOptions, GlobResult, ListDirectoryOptions, ListDirectoryResult, 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>;
-    /**
-     * List files and directories in a path.
-     * Returns a tree structure with default ignore patterns for build artifacts.
-     *
-     * @param dirPath - Path to directory (relative or absolute)
-     * @param options - List options (ignore patterns, max results)
-     * @returns Directory listing with tree structure
-     * @throws DirectoryNotFoundError if directory doesn't exist
-     * @throws PathNotAllowedError if path is not in allowed paths
-     */
-    listDirectory(dirPath: string, options?: ListDirectoryOptions): Promise<ListDirectoryResult>;
-    /**
-     * 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-history-storage.d.ts

@@ -1,53 +0,0 @@
-import type { SessionMetadata } from '../../domain/cipher/storage/history-types.js';
-import type { InternalMessage } from '../cipher/message-types.js';
-/**
- * Interface for session history persistence.
- *
- * Implementations can use different storage backends (blob storage, database, etc.)
- * to persist and restore conversation history across sessions.
- */
-export interface IHistoryStorage {
-    /**
-     * Delete all history for a specific session.
-     *
-     * @param sessionId - Unique session identifier
-     * @returns Promise that resolves when history is deleted
-     */
-    deleteHistory(sessionId: string): Promise<void>;
-    /**
-     * Check if history exists for a specific session.
-     *
-     * @param sessionId - Unique session identifier
-     * @returns Promise that resolves to true if history exists
-     */
-    exists(sessionId: string): Promise<boolean>;
-    /**
-     * Get metadata for a specific session without loading full history.
-     *
-     * @param sessionId - Unique session identifier
-     * @returns Promise that resolves to session metadata or undefined if not found
-     */
-    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
-    /**
-     * List all session IDs that have persisted history.
-     *
-     * @returns Promise that resolves to array of session IDs
-     */
-    listSessions(): Promise<string[]>;
-    /**
-     * Load conversation history for a specific session.
-     *
-     * @param sessionId - Unique session identifier
-     * @returns Promise that resolves to array of messages, or undefined if session not found
-     */
-    loadHistory(sessionId: string): Promise<InternalMessage[] | undefined>;
-    /**
-     * Save conversation history for a specific session.
-     * Overwrites any existing history for the session.
-     *
-     * @param sessionId - Unique session identifier
-     * @param messages - Array of messages to persist
-     * @returns Promise that resolves when history is saved
-     */
-    saveHistory(sessionId: string, messages: InternalMessage[]): Promise<void>;
-}

package/dist/core/interfaces/cipher/i-llm-service.d.ts

@@ -1,61 +0,0 @@
-import type { ContextManager, FileData, ImageData } from '../../../infra/cipher/llm/context/context-manager.js';
-import type { LLMServiceConfig } from '../../../infra/cipher/llm/internal-llm-service.js';
-import type { ToolSet } from '../../domain/cipher/tools/types.js';
-import type { ExecutionContext } from './i-cipher-agent.js';
-/**
- * LLM Service interface.
- *
- * Defines the contract for LLM service implementations.
- * Services handle the agentic loop, tool calling, and context management.
- *
- * Based on dexto's ILLMService pattern.
- */
-export interface ILLMService {
-    /**
-     * Complete a task with agentic tool calling support.
-     *
-     * Main entry point for executing user requests with tool support.
-     * The service handles:
-     * - Adding user message to context
-     * - Agentic loop (LLM → tool calls → LLM)
-     * - Returning final response
-     *
-     * @param textInput - User input text
-     * @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 the response (optional)
-     * @param options.executionContext - Optional execution context
-     * @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.
-     *
-     * @returns Tool set with JSON Schema definitions
-     */
-    getAllTools(): Promise<ToolSet>;
-    /**
-     * Get service configuration.
-     *
-     * @returns Service configuration including model, provider, token limits
-     */
-    getConfig(): LLMServiceConfig;
-    /**
-     * Get the context manager instance.
-     *
-     * Allows access to conversation history and context management.
-     *
-     * @returns Context manager instance
-     */
-    getContextManager(): ContextManager<unknown>;
-}