byterover-cli 0.4.0 → 1.0.0

package/dist/core/domain/cipher/llm/types.js

@@ -0,0 +1,60 @@
+/**
+ * LLM Provider types and constants.
+ *
+ * This module defines the core types for LLM provider abstraction,
+ */
+/**
+ * Supported LLM providers as a const array for runtime validation.
+ */
+export const LLM_PROVIDERS = ['claude', 'gemini', 'openrouter'];
+/**
+ * Supported file types for multimodal input.
+ */
+export const SUPPORTED_FILE_TYPES = ['audio', 'image', 'pdf'];
+/**
+ * MIME type to file type mapping.
+ * Used to determine supported file types from MIME types.
+ */
+export const MIME_TYPE_TO_FILE_TYPE = {
+    // PDF
+    'application/pdf': 'pdf',
+    // Audio
+    'audio/aac': 'audio',
+    'audio/m4a': 'audio',
+    'audio/mp3': 'audio',
+    'audio/mpeg': 'audio',
+    'audio/ogg': 'audio',
+    'audio/wav': 'audio',
+    'audio/wave': 'audio',
+    'audio/webm': 'audio',
+    'audio/x-wav': 'audio',
+    // Images
+    'image/gif': 'image',
+    'image/jpeg': 'image',
+    'image/jpg': 'image',
+    'image/png': 'image',
+    'image/webp': 'image',
+};
+/**
+ * Get all allowed MIME types.
+ * @returns Array of allowed MIME type strings
+ */
+export function getAllowedMimeTypes() {
+    return Object.keys(MIME_TYPE_TO_FILE_TYPE);
+}
+/**
+ * Get file type from MIME type.
+ * @param mimeType - MIME type string
+ * @returns SupportedFileType or undefined if not supported
+ */
+export function getFileTypeFromMimeType(mimeType) {
+    return MIME_TYPE_TO_FILE_TYPE[mimeType];
+}
+/**
+ * Check if a MIME type is supported.
+ * @param mimeType - MIME type string
+ * @returns true if the MIME type is supported
+ */
+export function isSupportedMimeType(mimeType) {
+    return mimeType in MIME_TYPE_TO_FILE_TYPE;
+}

package/dist/core/domain/cipher/storage/message-storage-types.d.ts

@@ -102,20 +102,89 @@ export interface StoredMessage {
     /** Unix timestamp of last update */
     updatedAt: number;
 }
+/**
+ * Tool state as stored in StoredPart.
+ * Mirrors the ToolState types from message-types.ts but optimized for storage.
+ */
+export interface StoredToolState {
+    /** Attachments produced by the tool (images, files) */
+    attachments?: Array<{
+        /** Base64-encoded data or data URL */
+        data: string;
+        /** Original filename if available */
+        filename?: string;
+        /** MIME type of the attachment */
+        mime: string;
+        /** Attachment type */
+        type: 'file' | 'image';
+    }>;
+    /** Unique identifier for this tool call */
+    callId: string;
+    /** Unix timestamp when execution completed */
+    completedAt?: number;
+    /** Error message (only for 'error' status) */
+    error?: string;
+    /** Parsed input arguments */
+    input?: Record<string, unknown>;
+    /** Tool output content (only for 'completed' status) */
+    output?: string;
+    /** Unix timestamp when execution started */
+    startedAt?: number;
+    /** Current status of the tool call */
+    status: 'completed' | 'error' | 'pending' | 'running';
+    /** Human-readable title for display */
+    title?: string;
+}
+/**
+ * Reasoning summary as stored in StoredPart.
+ */
+export interface StoredReasoningSummary {
+    /** Detailed description of the thought */
+    description: string;
+    /** Brief subject of the thought */
+    subject: string;
+}
+/**
+ * Part-level metadata as stored in StoredPart.
+ */
+export interface StoredPartMetadata {
+    /** Custom metadata fields */
+    [key: string]: unknown;
+    /** Anthropic cache control hint */
+    cacheControl?: {
+        type: 'ephemeral' | 'permanent';
+    };
+    /** Whether this is auto-generated content */
+    synthetic?: boolean;
+}
 /**
  * Message part stored at ["part", messageId, partId].
  *
  * Parts contain content that may be pruned independently:
  * - Tool outputs (large, can be marked as compacted)
+ * - Tool calls with state machine (pending → running → completed/error)
  * - File attachments
  * - Image data
+ * - Reasoning/thinking traces
  *
  * Parts are stored separately to enable:
  * - Selective pruning of old tool outputs
  * - Lazy loading of large content
  * - Efficient streaming without loading all content
+ * - Tool state tracking with full lifecycle
+ *
+ * Blob references:
+ * - Large binary content (>5KB) can be stored in blob storage
+ * - When stored as blob, content contains "@blob:{id}" reference
+ * - Blob refs are resolved lazily at format-time via BlobReferenceResolver
  */
 export interface StoredPart {
+    /**
+     * Blob reference ID (without @ prefix) when content is stored externally.
+     * Present when isBlob is true. The actual data can be retrieved from
+     * blob storage using this ID.
+     */
+    blobRef?: string;
     /**
      * Unix timestamp when this part was marked as compacted.
      * If set, the original content has been cleared to save space,
@@ -125,11 +194,14 @@ export interface StoredPart {
     /**
      * The actual content of the part.
      * - Tool output: string (JSON or text)
-     * - File: base64 encoded data or file path
+     * - File: base64 encoded data, file path, or blob reference (@blob:id)
      * - Text: raw text content
-     * - Image: base64 encoded data
+     * - Image: base64 encoded data or blob reference (@blob:id)
+     * - Reasoning: thinking text from the model
+     * - Tool: empty (state stored in toolState)
      *
      * When compactedAt is set, this will be empty or contain a placeholder.
+     * When isBlob is true, this contains the blob reference string.
      */
     content: string;
     /** Unix timestamp when part was created */
@@ -138,17 +210,42 @@ export interface StoredPart {
     filename?: string;
     /** Unique part identifier (UUID) */
     id: string;
+    /**
+     * Whether the content field contains a blob reference.
+     * When true, content should be resolved via BlobReferenceResolver
+     * before use (at format-time for LLM requests).
+     */
+    isBlob?: boolean;
     /** ID of the message this part belongs to */
     messageId: string;
+    /**
+     * Part-level metadata for cache hints and custom data.
+     * Follows OpenCode's pattern for part metadata.
+     */
+    metadata?: StoredPartMetadata;
     /** MIME type for file and image parts */
     mimeType?: string;
+    /**
+     * Reasoning summary for 'reasoning' type parts.
+     * Contains parsed subject and description for display.
+     */
+    reasoningSummary?: StoredReasoningSummary;
     /**
      * For tool_output parts, the name of the tool.
      * Used for display and filtering.
      */
     toolName?: string;
-    /** Type of part content */
-    type: 'compaction' | 'file' | 'image' | 'text' | 'tool_output';
+    /**
+     * Tool state for 'tool' type parts.
+     * Tracks the full lifecycle: pending → running → completed/error.
+     * Only present when type is 'tool'.
+     */
+    toolState?: StoredToolState;
+    /**
+     * Type of part content.
+     * Extended with 'tool' for tool calls with state machine and 'reasoning' for thinking traces.
+     */
+    type: 'compaction' | 'file' | 'image' | 'reasoning' | 'text' | 'tool' | 'tool_output';
 }
 /**
  * Placeholder message shown when tool output has been compacted.
@@ -197,9 +294,21 @@ export interface PruneToolOutputsOptions {
     /**
      * Target token count to keep in tool outputs.
      * Tool outputs beyond this (from oldest) will be marked as compacted.
-     * Default: 40000 (same as OpenCode)
+     * Default: 40000 (same as OpenCode PRUNE_PROTECT)
      */
     keepTokens?: number;
+    /**
+     * Minimum tokens that must be recoverable to perform pruning.
+     * If pruning would save less than this, skip it entirely.
+     * Default: 20000 (same as OpenCode PRUNE_MINIMUM)
+     */
+    minimumTokens?: number;
+    /**
+     * Number of recent user turns to protect from pruning.
+     * Tool outputs in these turns will not be compacted.
+     * Default: 2
+     */
+    protectedTurns?: number;
     /**
      * Session ID to prune tool outputs from.
      */

package/dist/core/domain/cipher/streaming/types.d.ts

@@ -0,0 +1,119 @@
+import type { ExecutionContext } from '../../../interfaces/cipher/i-cipher-agent.js';
+import type { TokenUsage } from '../agent-events/types.js';
+/**
+ * Streaming event names for CipherAgent.stream()
+ * These are the events exposed via the streaming API for real-time chat UIs.
+ */
+export declare const STREAMING_EVENT_NAMES: readonly ["llmservice:thinking", "llmservice:chunk", "llmservice:response", "llmservice:toolCall", "llmservice:toolResult", "llmservice:error", "llmservice:warning", "message:queued", "message:dequeued", "run:complete"];
+export type StreamingEventName = (typeof STREAMING_EVENT_NAMES)[number];
+/**
+ * Union type of all streaming events with their payloads.
+ * Uses 'name' property as discriminant for type narrowing.
+ */
+export type StreamingEvent = {
+    args: Record<string, unknown>;
+    callId?: string;
+    name: 'llmservice:toolCall';
+    sessionId: string;
+    taskId?: string;
+    toolName: string;
+} | {
+    callId?: string;
+    error?: string;
+    name: 'llmservice:toolResult';
+    result?: unknown;
+    sessionId: string;
+    success: boolean;
+    taskId?: string;
+    toolName: string;
+} | {
+    code?: string;
+    error: string;
+    name: 'llmservice:error';
+    recoverable?: boolean;
+    sessionId: string;
+    taskId?: string;
+} | {
+    content: string;
+    isComplete?: boolean;
+    name: 'llmservice:chunk';
+    sessionId: string;
+    taskId?: string;
+    type: 'reasoning' | 'text';
+} | {
+    content: string;
+    model?: string;
+    name: 'llmservice:response';
+    partial?: boolean;
+    provider?: string;
+    reasoning?: string;
+    sessionId: string;
+    taskId?: string;
+    tokenUsage?: TokenUsage;
+} | {
+    count: number;
+    name: 'message:dequeued';
+    sessionId: string;
+    taskId?: string;
+} | {
+    durationMs: number;
+    error?: Error;
+    finishReason: 'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout';
+    name: 'run:complete';
+    sessionId: string;
+    stepCount: number;
+    taskId?: string;
+} | {
+    message: string;
+    name: 'llmservice:warning';
+    sessionId: string;
+    taskId?: string;
+} | {
+    message: {
+        content: string;
+        id: string;
+        queuedAt: number;
+    };
+    name: 'message:queued';
+    position: number;
+    sessionId: string;
+    taskId?: string;
+} | {
+    name: 'llmservice:thinking';
+    sessionId: string;
+    taskId?: string;
+};
+/**
+ * Options for stream() method
+ */
+export interface StreamOptions {
+    /** Execution context */
+    executionContext?: ExecutionContext;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Task ID for concurrent task isolation (included in all emitted events) */
+    taskId?: string;
+}
+/**
+ * Complete response from generate() method (wrapper around stream)
+ */
+export interface GenerateResponse {
+    /** The final response content */
+    content: string;
+    /** Internal reasoning (if available) */
+    reasoning?: string;
+    /** Session ID */
+    sessionId: string;
+    /** Tool calls made during execution */
+    toolCalls: Array<{
+        args: Record<string, unknown>;
+        callId: string;
+        result?: {
+            data: unknown;
+            success: boolean;
+        };
+        toolName: string;
+    }>;
+    /** Token usage statistics */
+    usage: TokenUsage;
+}

package/dist/core/domain/cipher/streaming/types.js

@@ -0,0 +1,16 @@
+/**
+ * Streaming event names for CipherAgent.stream()
+ * These are the events exposed via the streaming API for real-time chat UIs.
+ */
+export const STREAMING_EVENT_NAMES = [
+    'llmservice:thinking',
+    'llmservice:chunk',
+    'llmservice:response',
+    'llmservice:toolCall',
+    'llmservice:toolResult',
+    'llmservice:error',
+    'llmservice:warning',
+    'message:queued',
+    'message:dequeued',
+    'run:complete',
+];

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

@@ -1,3 +1,5 @@
+import type { MemoryManager } from '../../../../infra/cipher/memory/memory-manager.js';
+import type { EnvironmentContext } from '../../../../infra/cipher/system-prompt/environment-context-builder.js';
 /**
  * Conversation metadata for execution context
  */
@@ -23,6 +25,48 @@ export interface SystemPromptContext {
     /** 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.

package/dist/core/domain/cipher/todos/types.d.ts

@@ -21,6 +21,11 @@ export interface Todo {
      * Example: "Run tests", "Build the project"
      */
     content: string;
+    /**
+     * Unique identifier for the todo item.
+     * Used for tracking and updating individual todos.
+     */
+    id: string;
     /**
      * Current status of the todo.
      * - pending: Not yet started
@@ -48,10 +53,39 @@ export interface WriteTodosResult {
      * Content to send back to the LLM.
      */
     llmContent: string;
+    /**
+     * Structured metadata for tool consumption.
+     */
+    metadata: {
+        todos: Todo[];
+    };
     /**
      * Display content for rendering to user.
      */
     returnDisplay: {
         todos: Todo[];
     };
+    /**
+     * Smart title showing incomplete count.
+     */
+    title: string;
+}
+/**
+ * Result of read_todos tool execution.
+ */
+export interface ReadTodosResult {
+    /**
+     * JSON formatted list of all todos.
+     */
+    content: string;
+    /**
+     * Structured metadata for tool consumption.
+     */
+    metadata: {
+        todos: Todo[];
+    };
+    /**
+     * Smart title showing incomplete count.
+     */
+    title: string;
 }

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

@@ -5,20 +5,23 @@
 export declare const ToolName: {
     readonly BASH_EXEC: 'bash_exec';
     readonly BASH_OUTPUT: 'bash_output';
+    readonly BATCH: 'batch';
     readonly CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic';
     readonly CURATE: 'curate';
     readonly DELETE_MEMORY: 'delete_memory';
-    readonly DETECT_DOMAINS: 'detect_domains';
     readonly EDIT_FILE: 'edit_file';
     readonly EDIT_MEMORY: 'edit_memory';
-    readonly FIND_KNOWLEDGE_TOPICS: 'find_knowledge_topics';
     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 SPEC_ANALYZE: 'spec_analyze';
+    readonly TASK: 'task';
     readonly WRITE_FILE: 'write_file';
     readonly WRITE_MEMORY: 'write_memory';
     readonly WRITE_TODOS: 'write_todos';

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

@@ -5,20 +5,23 @@
 export const ToolName = {
     BASH_EXEC: 'bash_exec',
     BASH_OUTPUT: 'bash_output',
+    BATCH: 'batch',
     CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic',
     CURATE: 'curate',
     DELETE_MEMORY: 'delete_memory',
-    DETECT_DOMAINS: 'detect_domains',
     EDIT_FILE: 'edit_file',
     EDIT_MEMORY: 'edit_memory',
-    FIND_KNOWLEDGE_TOPICS: 'find_knowledge_topics',
     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',
+    SPEC_ANALYZE: 'spec_analyze',
+    TASK: 'task',
     WRITE_FILE: 'write_file',
     WRITE_MEMORY: 'write_memory',
     WRITE_TODOS: 'write_todos',

package/dist/core/domain/cipher/tools/types.d.ts

@@ -1,9 +1,28 @@
 import type { ZodSchema } from 'zod';
+/**
+ * Callback function for tools to push metadata updates during execution.
+ * Called by tools to stream real-time updates to the UI/LLM.
+ */
+export type MetadataCallback = (update: ToolMetadataUpdate) => void;
 /**
  * Risk level for tool execution.
  * Used for logging, auditing, and policy decisions.
  */
 export type RiskLevel = 'critical' | 'high' | 'low' | 'medium';
+/**
+ * Real-time metadata update from a tool during execution.
+ * Allows tools to push incremental updates (e.g., streaming bash output).
+ */
+export interface ToolMetadataUpdate {
+    /** Additional custom metadata */
+    [key: string]: unknown;
+    /** Human-readable description of current status */
+    description?: string;
+    /** Streamed output content (e.g., bash stdout/stderr) */
+    output?: string;
+    /** Progress indicator (0-100) */
+    progress?: number;
+}
 /**
  * Semantic category for tools.
  * Helps classify tools by their primary function.
@@ -63,8 +82,20 @@ export interface Tool {
  * Contains metadata about the execution environment.
  */
 export interface ToolExecutionContext {
+    /**
+     * Callback for streaming metadata updates during execution.
+     * Tools can use this to push real-time output (e.g., bash streaming).
+     */
+    metadata?: MetadataCallback;
     /** Session ID if available */
     sessionId?: string;
+    /**
+     * Abort signal for cancelling long-running operations.
+     * Tools should check this signal periodically and abort gracefully.
+     */
+    signal?: AbortSignal;
+    /** Task ID from usecase for billing tracking */
+    taskId?: string;
 }
 /**
  * Tool set exposed to the LLM.

package/dist/core/domain/entities/event.d.ts

@@ -1,7 +1,7 @@
 /**
  * Array of all supported Events.
  */
-export declare const EVENT_VALUES: readonly ["auth:signed_in", "auth:signed_out", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed"];
+export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
 export type EventName = (typeof EVENT_VALUES)[number];
 export interface PropertyDict {
     [key: string]: any;

package/dist/core/domain/entities/event.js

@@ -2,7 +2,8 @@
  * Array of all supported Events.
  */
 export const EVENT_VALUES = [
-    'auth:signed_in',
+    'repl',
+    'auth:sign_in',
     'auth:signed_out',
     'space:init',
     'space:changed',
@@ -17,4 +18,5 @@ export const EVENT_VALUES = [
     'onboarding:query_completed',
     'onboarding:skipped',
     'onboarding:completed',
+    'init'
 ];

package/dist/core/domain/errors/connection-error.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Base error for client connection failures.
+ */
+export declare class ConnectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when no running instance is found.
+ */
+export declare class NoInstanceRunningError extends ConnectionError {
+    constructor();
+}
+/**
+ * Error thrown when instance is found but process has crashed.
+ */
+export declare class InstanceCrashedError extends ConnectionError {
+    constructor(projectRoot?: string);
+}
+/**
+ * Error thrown when connection to instance fails.
+ */
+export declare class ConnectionFailedError extends ConnectionError {
+    readonly originalError?: Error;
+    readonly port?: number;
+    constructor(port?: number, originalError?: Error);
+}
+/**
+ * Error thrown when connection times out.
+ */
+export declare class ConnectionTimeoutError extends ConnectionError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}