byterover-cli 0.4.1 → 1.0.1

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

@@ -12,11 +12,17 @@ export interface IChatSession {
      */
     cancel(): void;
     /**
-     * Dispose of the session and clean up resources.
+     * 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 no longer needed.
+     * Should be called when session is permanently no longer needed.
      */
-    dispose?(): void;
+    dispose(): void;
     /**
      * Get the conversation history.
      *
@@ -49,8 +55,8 @@ export interface IChatSession {
      *
      * @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
+     * @param options.taskId - Optional task ID for concurrent task isolation (included in all emitted events)
      * @returns Assistant response
      * @throws SessionCancelledError if operation is cancelled
      * @throws MaxIterationsExceededError if tool loop exceeds maximum iterations
@@ -58,6 +64,42 @@ export interface IChatSession {
      */
     run(input: string, options?: {
         executionContext?: ExecutionContext;
-        mode?: 'autonomous' | 'default' | 'query';
+        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,5 +1,6 @@
 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
@@ -7,7 +8,7 @@ import type { ConversationMetadata } from '../../domain/cipher/system-prompt/typ
  */
 export interface ExecutionContext {
     /** Command type that initiated the execution (for command-specific prompt loading) */
-    commandType?: 'curate' | 'query';
+    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) */
@@ -48,6 +49,13 @@ export interface AgentState {
  * 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
@@ -55,12 +63,29 @@ export interface ICipherAgent {
      */
     deleteSession(sessionId: string): Promise<boolean>;
     /**
-     * Execute the agent with user input
+     * Execute the agent with user input.
+     * Uses the agent's default session (created during start()).
+     *
      * @param input - User input string
-     * @param sessionId - Optional session ID
+     * @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, sessionId?: string): Promise<string>;
+    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
@@ -87,4 +112,14 @@ export interface ICipherAgent {
      * 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

@@ -33,16 +33,14 @@ export interface GenerateContentRequest {
     config: GenerationConfig;
     /** Conversation history */
     contents: InternalMessage[];
-    /** Optional execution context (for autonomous mode, etc.) */
+    /** Optional execution context */
     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;
+    /** Tracking task ID for backend billing metrics (random UUID per request) */
+    taskId: string;
     /** Available tools for function calling */
     tools?: ToolSet;
 }

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

@@ -1,4 +1,4 @@
-import type { EditFileOptions, EditOperation, EditResult, FileContent, GlobOptions, GlobResult, ReadFileOptions, SearchOptions, SearchResult, WriteFileOptions, WriteResult } from '../../domain/cipher/file-system/types.js';
+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
@@ -32,6 +32,17 @@ export interface IFileSystem {
      * 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.
      *

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

@@ -21,23 +21,22 @@ export interface ILLMService {
      * - Returning final response
      *
      * @param textInput - User input text
-     * @param sessionId - Session ID for tracking the conversation
      * @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 (for autonomous mode, etc.)
-     * @param options.mode - Optional mode for system prompt ('autonomous' enables autonomous mode)
+     * @param options.executionContext - Optional execution context
+     * @param options.taskId - Task ID from usecase for billing tracking
      * @returns Final assistant response
      */
-    completeTask(textInput: string, sessionId: string, options?: {
+    completeTask(textInput: string, options?: {
         executionContext?: ExecutionContext;
         fileData?: FileData;
         imageData?: ImageData;
-        mode?: 'autonomous' | 'default' | 'query';
         signal?: AbortSignal;
         stream?: boolean;
+        taskId?: string;
     }): Promise<string>;
     /**
      * Get all available tools.

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

@@ -0,0 +1,24 @@
+import type { Todo } from '../../domain/cipher/todos/types.js';
+/**
+ * Interface for session-based todo storage.
+ *
+ * Implementations can use different storage backends (in-memory, persistent, etc.)
+ * to store and retrieve todo lists per session.
+ */
+export interface ITodoStorage {
+    /**
+     * Get todos for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Promise that resolves to array of todos, empty array if not found
+     */
+    get(sessionId: string): Promise<Todo[]>;
+    /**
+     * Update (replace) todos for a specific session.
+     *
+     * @param sessionId - Unique session identifier
+     * @param todos - Array of todos to store
+     * @returns Promise that resolves when todos are saved
+     */
+    update(sessionId: string, todos: Todo[]): Promise<void>;
+}

package/dist/core/interfaces/cipher/i-todo-storage.js

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

package/dist/core/interfaces/cipher/i-tool-plugin.d.ts

@@ -0,0 +1,90 @@
+import type { ToolExecutionResult } from '../../domain/cipher/tools/tool-error.js';
+/**
+ * Context provided to plugin hooks during tool execution.
+ * Contains metadata about the current tool invocation.
+ */
+export interface ToolHookContext {
+    /** Unique identifier for this tool call */
+    callId: string;
+    /** Session ID where the tool is being executed */
+    sessionId: string;
+    /** Name of the tool being executed */
+    toolName: string;
+}
+/**
+ * Result from a before-execute hook.
+ * Determines whether tool execution should proceed and allows argument modification.
+ */
+export interface BeforeHookResult {
+    /**
+     * Modified arguments to use for execution.
+     * If provided, these replace the original arguments.
+     */
+    args?: Record<string, unknown>;
+    /**
+     * Whether to proceed with tool execution.
+     * If false, execution is blocked and reason should explain why.
+     */
+    proceed: boolean;
+    /**
+     * Reason for blocking execution (when proceed is false).
+     * Used to generate an error message for the LLM.
+     */
+    reason?: string;
+}
+/**
+ * Plugin interface for extending tool execution behavior.
+ *
+ * Plugins can intercept tool execution at two points:
+ * 1. beforeExecute: Called before the tool runs. Can modify args or block execution.
+ * 2. afterExecute: Called after the tool completes. Can log, audit, or react to results.
+ *
+ * @example
+ * ```typescript
+ * const loggingPlugin: IToolPlugin = {
+ *   name: 'logging',
+ *   priority: 1,
+ *   beforeExecute(ctx, args) {
+ *     console.log(`[${ctx.toolName}] Starting with args:`, args)
+ *     return { proceed: true }
+ *   },
+ *   afterExecute(ctx, args, result) {
+ *     console.log(`[${ctx.toolName}] Completed:`, result.success ? 'success' : 'error')
+ *   }
+ * }
+ * ```
+ */
+export interface IToolPlugin {
+    /**
+     * Called after a tool has completed execution.
+     * Receives the original arguments and the execution result.
+     *
+     * Use for logging, auditing, analytics, or triggering side effects.
+     * Errors in afterExecute are caught and logged but don't affect the result.
+     *
+     * @param ctx - Hook context with tool metadata
+     * @param args - Arguments that were passed to the tool
+     * @param result - Result from tool execution
+     */
+    afterExecute?(ctx: ToolHookContext, args: Record<string, unknown>, result: ToolExecutionResult): Promise<void> | void;
+    /**
+     * Called before a tool is executed.
+     * Can inspect/modify arguments or block execution entirely.
+     *
+     * @param ctx - Hook context with tool metadata
+     * @param args - Arguments to be passed to the tool
+     * @returns Result indicating whether to proceed and optionally modified args
+     */
+    beforeExecute?(ctx: ToolHookContext, args: Record<string, unknown>): BeforeHookResult | Promise<BeforeHookResult>;
+    /**
+     * Unique name for this plugin.
+     * Used for logging and to allow unregistering by name.
+     */
+    name: string;
+    /**
+     * Execution priority (lower = earlier).
+     * Plugins with lower priority numbers execute first.
+     * Default is 100 if not specified.
+     */
+    priority?: number;
+}

package/dist/core/interfaces/cipher/i-tool-plugin.js

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

package/dist/core/interfaces/cipher/i-tool-provider.d.ts

@@ -1,5 +1,5 @@
 import type { ToolMarker } from '../../../infra/cipher/tools/tool-markers.js';
-import type { ToolSet } from '../../domain/cipher/tools/types.js';
+import type { ToolExecutionContext, ToolSet } from '../../domain/cipher/tools/types.js';
 /**
  * Interface for tool provider.
  * Manages tool registration, validation, and execution.
@@ -11,12 +11,13 @@ export interface IToolProvider {
      * @param toolName - Name of the tool to execute
      * @param args - Tool arguments (will be validated against schema)
      * @param sessionId - Optional session ID for context
+     * @param context - Optional execution context (includes metadata callback for streaming)
      * @returns Tool execution result
      * @throws ToolNotFoundError if tool doesn't exist
      * @throws ToolValidationError if input validation fails
      * @throws ToolExecutionError if execution fails
      */
-    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string): Promise<unknown>;
+    executeTool(toolName: string, args: Record<string, unknown>, sessionId?: string, context?: ToolExecutionContext): Promise<unknown>;
     /**
      * Get all registered tools in JSON Schema format.
      * Used to expose tools to the LLM.

package/dist/core/interfaces/cipher/i-tool-scheduler.d.ts

@@ -62,6 +62,10 @@ export interface ToolSchedulerContext {
      * Session ID for the current session.
      */
     sessionId: string;
+    /**
+     * Task ID for billing tracking (passed from usecase to subagents).
+     */
+    taskId?: string;
 }
 /**
  * Interface for the tool scheduler.

package/dist/core/interfaces/cipher/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cipher interfaces and types.
+ *
+ * This module re-exports all cipher-related interfaces, types, and utilities.
+ */
+export type { BlobMetadata, StoredBlob } from '../../domain/cipher/blob/types.js';
+export * from './cipher-services.js';
+export type { IAgentStorage } from './i-agent-storage.js';
+export type { IBlobStorage } from './i-blob-storage.js';
+export type { IChatSession } from './i-chat-session.js';
+export type { ICipherAgent } from './i-cipher-agent.js';
+export type { ICodingAgentLogParser } from './i-coding-agent-log-parser.js';
+export type { ICodingAgentLogWatcher } from './i-coding-agent-log-watcher.js';
+export type { IContentGenerator } from './i-content-generator.js';
+export type { IEventEmitter } from './i-event-emitter.js';
+export type { IFileSystem } from './i-file-system.js';
+export type { IHistoryStorage } from './i-history-storage.js';
+export type { IKeyStorage } from './i-key-storage.js';
+export type { ILlmProvider } from './i-llm-provider.js';
+export type { ILLMService } from './i-llm-service.js';
+export type { ILogger } from './i-logger.js';
+export type { IMessageFormatter } from './i-message-formatter.js';
+export type { IPolicyEngine } from './i-policy-engine.js';
+export type { IProcessService } from './i-process-service.js';
+export type { ISystemPromptContributor } from './i-system-prompt-contributor.js';
+export type { ITodoStorage } from './i-todo-storage.js';
+export type { ITokenizer } from './i-tokenizer.js';
+export type { IToolPlugin } from './i-tool-plugin.js';
+export type { IToolProvider } from './i-tool-provider.js';
+export type { IToolScheduler } from './i-tool-scheduler.js';
+export * from './llm-types.js';
+export * from './message-factory.js';
+export * from './message-type-guards.js';
+export * from './message-types.js';
+export * from './tokenizer-types.js';

package/dist/core/interfaces/cipher/index.js

@@ -0,0 +1,11 @@
+/**
+ * Cipher interfaces and types.
+ *
+ * This module re-exports all cipher-related interfaces, types, and utilities.
+ */
+export * from './cipher-services.js';
+export * from './llm-types.js';
+export * from './message-factory.js';
+export * from './message-type-guards.js';
+export * from './message-types.js';
+export * from './tokenizer-types.js';

package/dist/core/interfaces/cipher/message-factory.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Factory functions for creating validated message parts and messages.
+ *
+ * These factories provide a consistent way to create message parts with:
+ * - Proper type assignment
+ * - Optional metadata and synthetic flags
+ * - Default values where appropriate
+ *
+ */
+import type { FilePart, ImagePart, InternalMessage, ReasoningPart, TextPart, ToolCall, ToolPart, ToolStateCompleted, ToolStateError, ToolStatePending, ToolStateRunning } from './message-types.js';
+/**
+ * Common options for creating message parts.
+ */
+export interface PartOptions {
+    /** Part-level metadata for cache hints and custom data */
+    metadata?: {
+        [key: string]: unknown;
+        cacheControl?: {
+            type: 'ephemeral' | 'permanent';
+        };
+    };
+    /** Whether this is auto-generated content */
+    synthetic?: boolean;
+}
+/**
+ * Create a TextPart with the given text content.
+ */
+export declare function createTextPart(text: string, options?: PartOptions): TextPart;
+/**
+ * Create an ImagePart with the given image data.
+ */
+export declare function createImagePart(image: ImagePart['image'], mimeType?: string, options?: PartOptions): ImagePart;
+/**
+ * Create a FilePart with the given file data.
+ */
+export declare function createFilePart(data: FilePart['data'], mimeType: string, filename?: string, options?: PartOptions): FilePart;
+/**
+ * Create a ReasoningPart with the given thinking text.
+ */
+export declare function createReasoningPart(text: string, summary?: {
+    description: string;
+    subject: string;
+}, options?: PartOptions): ReasoningPart;
+/**
+ * Create a ToolPart in pending state.
+ */
+export declare function createToolPart(callId: string, toolName: string, input: Record<string, unknown>, options?: PartOptions): ToolPart;
+/**
+ * Create a ToolPart in running state.
+ */
+export declare function createRunningToolPart(callId: string, toolName: string, input: Record<string, unknown>, options?: PartOptions & {
+    startedAt?: number;
+}): ToolPart;
+/**
+ * Options for creating a completed tool part.
+ */
+export interface CreateCompletedToolPartOptions extends PartOptions {
+    additionalOptions?: {
+        attachments?: ToolStateCompleted['attachments'];
+        compactedAt?: number;
+        metadata?: Record<string, unknown>;
+        title?: string;
+    };
+    callId: string;
+    input: Record<string, unknown>;
+    output: string;
+    time?: {
+        end: number;
+        start: number;
+    };
+    toolName: string;
+}
+/**
+ * Create a ToolPart in completed state.
+ */
+export declare function createCompletedToolPart(options: CreateCompletedToolPartOptions): ToolPart;
+/**
+ * Options for creating an error tool part.
+ */
+export interface CreateErrorToolPartOptions extends PartOptions {
+    callId: string;
+    error: string;
+    input: Record<string, unknown>;
+    time?: {
+        end: number;
+        start: number;
+    };
+    toolName: string;
+}
+/**
+ * Create a ToolPart in error state.
+ */
+export declare function createErrorToolPart(options: CreateErrorToolPartOptions): ToolPart;
+/**
+ * Transition a tool state from pending to running.
+ */
+export declare function transitionToRunning(state: ToolStatePending, startedAt?: number): ToolStateRunning;
+/**
+ * Transition a tool state from running to completed.
+ */
+export declare function transitionToCompleted(state: ToolStateRunning, output: string, endedAt?: number, additionalOptions?: {
+    attachments?: ToolStateCompleted['attachments'];
+    metadata?: Record<string, unknown>;
+    title?: string;
+}): ToolStateCompleted;
+/**
+ * Transition a tool state from running to error.
+ */
+export declare function transitionToError(state: ToolStateRunning, error: string, endedAt?: number): ToolStateError;
+/**
+ * Create a ToolCall from function name and arguments.
+ */
+export declare function createToolCall(id: string, name: string, args: Record<string, unknown> | string): ToolCall;
+/**
+ * Options for creating internal messages.
+ */
+export interface MessageOptions {
+    /** Message-level metadata */
+    metadata?: {
+        [key: string]: unknown;
+        compactedAt?: number;
+        isSummary?: boolean;
+        summarizedMessageCount?: number;
+    };
+}
+/**
+ * Create a system message.
+ */
+export declare function createSystemMessage(content: string, options?: MessageOptions): InternalMessage;
+/**
+ * Create a user message with text content.
+ */
+export declare function createUserMessage(content: InternalMessage['content'] | string, options?: MessageOptions): InternalMessage;
+/**
+ * Create an assistant message with text content.
+ */
+export declare function createAssistantMessage(content: InternalMessage['content'] | string, additionalOptions?: {
+    reasoning?: string;
+    thought?: string;
+    thoughtSummary?: {
+        description: string;
+        subject: string;
+    };
+    toolCalls?: ToolCall[];
+}, options?: MessageOptions): InternalMessage;
+/**
+ * Create a tool result message.
+ */
+export declare function createToolResultMessage(content: InternalMessage['content'] | string, toolCallId: string, name: string, options?: MessageOptions): InternalMessage;
+/**
+ * Create a summary message (used by compression strategies).
+ */
+export declare function createSummaryMessage(summaryContent: string, summarizedMessageCount: number, options?: Omit<MessageOptions, 'metadata'> & {
+    additionalMetadata?: Record<string, unknown>;
+}): InternalMessage;