byterover-cli 1.5.0 → 1.7.0

package/dist/agent/core/domain/system-prompt/types.d.ts

@@ -0,0 +1,175 @@
+import type { MemoryManager } from '../../../infra/memory/memory-manager.js';
+import type { EnvironmentContext } from '../environment/types.js';
+/**
+ * Conversation metadata for execution context
+ */
+export interface ConversationMetadata {
+    /** ID of the conversation */
+    conversationId: string;
+    /** Title of the conversation */
+    title: string;
+}
+/**
+ * Context passed to system prompt contributors at runtime.
+ * This allows contributors to access runtime dependencies and configuration.
+ */
+export interface SystemPromptContext {
+    /** Additional context properties */
+    [key: string]: unknown;
+    /** Set of available tool marker strings */
+    availableMarkers?: Set<string>;
+    /** Array of available tool names */
+    availableTools?: string[];
+    /** Metadata about the conversation (for JSON input mode) */
+    conversationMetadata?: ConversationMetadata;
+    /** Whether running in JSON input mode (headless with conversation history) */
+    isJsonInputMode?: boolean;
+}
+/**
+ * Extended context for contributor execution.
+ * Includes runtime dependencies needed by contributors.
+ */
+export interface ContributorContext {
+    /** Available markers and their descriptions */
+    availableMarkers?: Record<string, string>;
+    /** List of available tool names */
+    availableTools?: string[];
+    /** Type of command being executed */
+    commandType?: 'chat' | 'curate' | 'query';
+    /** Metadata about the current conversation */
+    conversationMetadata?: {
+        conversationId?: string;
+        title?: string;
+    };
+    /** Environment context with working directory, git status, file tree, etc. */
+    environmentContext?: EnvironmentContext;
+    /** Instructions for file reference handling */
+    fileReferenceInstructions?: string;
+    /** Memory manager instance for accessing memories */
+    memoryManager?: MemoryManager;
+}
+/**
+ * Interface for system prompt contributors.
+ *
+ * Contributors generate portions of the system prompt that are
+ * combined by the SystemPromptManager.
+ */
+export interface SystemPromptContributor {
+    /**
+     * Generate the content for this contributor.
+     *
+     * @param context - Runtime context with dependencies
+     * @returns Prompt content string
+     */
+    getContent(context: ContributorContext): Promise<string>;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+}
+/**
+ * Configuration for a static contributor.
+ * Static contributors return the base system prompt from YAML or custom content.
+ */
+export interface StaticContributorConfig {
+    /** Optional category for YAML file (e.g., 'base', 'contributors') */
+    category?: string;
+    /** Optional custom content to return (overrides YAML) */
+    content?: string;
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Optional filename for YAML file (without .yml extension) */
+    filename?: string;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'static';
+}
+/**
+ * Configuration for a date-time contributor.
+ * Provides current date and time in ISO format.
+ */
+export interface DateTimeContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'dateTime';
+}
+/**
+ * Options for memory contributor configuration.
+ * Controls how memories are retrieved and formatted in the system prompt.
+ */
+export interface MemoryContributorOptions {
+    /** Whether to include tags in memory display (default: true) */
+    includeTags?: boolean;
+    /** Whether to include timestamps in memory display (default: false) */
+    includeTimestamps?: boolean;
+    /** Maximum number of memories to include */
+    limit?: number;
+    /** Only include pinned memories (for hybrid approach, default: false) */
+    pinnedOnly?: boolean;
+    /** Filter by memory source (agent, system, or user) */
+    source?: 'agent' | 'system' | 'user';
+}
+/**
+ * Configuration for a memory contributor.
+ * Retrieves and formats agent memories for inclusion in the system prompt.
+ */
+export interface MemoryContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Options for memory retrieval and formatting */
+    options?: MemoryContributorOptions;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'memory';
+}
+/**
+ * Configuration for an execution mode contributor.
+ * Provides context-specific instructions based on execution mode (e.g., JSON input mode).
+ */
+export interface ExecutionModeContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'executionMode';
+}
+/**
+ * Configuration for a marker-based prompt contributor.
+ * Generates prompt sections based on available tool markers.
+ */
+export interface MarkerPromptContributorConfig {
+    /** Whether this contributor is enabled (default: true) */
+    enabled?: boolean;
+    /** Unique identifier for this contributor */
+    id: string;
+    /** Priority for ordering (lower = higher priority) */
+    priority: number;
+    /** Type discriminator */
+    type: 'markerPrompt';
+}
+/**
+ * Union type for all contributor configurations.
+ * Uses discriminated union for type-safe contributor creation.
+ */
+export type ContributorConfig = DateTimeContributorConfig | ExecutionModeContributorConfig | MarkerPromptContributorConfig | MemoryContributorConfig | StaticContributorConfig;
+/**
+ * Configuration for the system prompt manager.
+ */
+export interface SystemPromptConfig {
+    /** Array of contributor configurations */
+    contributors: ContributorConfig[];
+}

package/dist/agent/core/domain/tools/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Known tool names.
+ * These constants ensure type safety and prevent typos.
+ */
+export declare const ToolName: {
+    readonly BASH_EXEC: 'bash_exec';
+    readonly BASH_OUTPUT: 'bash_output';
+    readonly BATCH: 'batch';
+    readonly CODE_EXEC: 'code_exec';
+    readonly CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic';
+    readonly CURATE: 'curate';
+    readonly DELETE_MEMORY: 'delete_memory';
+    readonly EDIT_FILE: 'edit_file';
+    readonly EDIT_MEMORY: 'edit_memory';
+    readonly GLOB_FILES: 'glob_files';
+    readonly GREP_CONTENT: 'grep_content';
+    readonly KILL_PROCESS: 'kill_process';
+    readonly LIST_DIRECTORY: 'list_directory';
+    readonly LIST_MEMORIES: 'list_memories';
+    readonly READ_FILE: 'read_file';
+    readonly READ_MEMORY: 'read_memory';
+    readonly READ_TODOS: 'read_todos';
+    readonly SEARCH_HISTORY: 'search_history';
+    readonly SEARCH_KNOWLEDGE: 'search_knowledge';
+    readonly SPEC_ANALYZE: 'spec_analyze';
+    readonly WRITE_FILE: 'write_file';
+    readonly WRITE_MEMORY: 'write_memory';
+    readonly WRITE_TODOS: 'write_todos';
+};
+/**
+ * Union type of all known tool names.
+ */
+export type KnownTool = (typeof ToolName)[keyof typeof ToolName];

package/dist/agent/core/domain/tools/constants.js

@@ -0,0 +1,29 @@
+/**
+ * Known tool names.
+ * These constants ensure type safety and prevent typos.
+ */
+export const ToolName = {
+    BASH_EXEC: 'bash_exec',
+    BASH_OUTPUT: 'bash_output',
+    BATCH: 'batch',
+    CODE_EXEC: 'code_exec',
+    CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic',
+    CURATE: 'curate',
+    DELETE_MEMORY: 'delete_memory',
+    EDIT_FILE: 'edit_file',
+    EDIT_MEMORY: 'edit_memory',
+    GLOB_FILES: 'glob_files',
+    GREP_CONTENT: 'grep_content',
+    KILL_PROCESS: 'kill_process',
+    LIST_DIRECTORY: 'list_directory',
+    LIST_MEMORIES: 'list_memories',
+    READ_FILE: 'read_file',
+    READ_MEMORY: 'read_memory',
+    READ_TODOS: 'read_todos',
+    SEARCH_HISTORY: 'search_history',
+    SEARCH_KNOWLEDGE: 'search_knowledge',
+    SPEC_ANALYZE: 'spec_analyze',
+    WRITE_FILE: 'write_file',
+    WRITE_MEMORY: 'write_memory',
+    WRITE_TODOS: 'write_todos',
+};

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>>;
+}