byterover-cli 1.6.0 → 1.7.1

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

@@ -0,0 +1,327 @@
+/**
+ * Types for granular message and part storage.
+ *
+ * This module defines the storage format for the new granular history system,
+ * where messages and parts are stored separately to enable:
+ * - Streaming message loading (newest to oldest)
+ * - Selective tool output pruning
+ * - Compaction boundary markers
+ *
+ * Storage key structure:
+ * - ["session", sessionId] → SessionRecord
+ * - ["message", sessionId, messageId] → StoredMessage
+ * - ["part", messageId, partId] → StoredPart
+ */
+import type { ToolCall } from '../../interfaces/message-types.js';
+/**
+ * Session-level record stored at ["session", sessionId].
+ * Contains metadata and acts as a marker for granular format detection.
+ */
+export interface SessionRecord {
+    /** Unix timestamp when session was created */
+    createdAt: number;
+    /** ID of the latest compaction boundary message, if any */
+    lastCompactionMessageId?: string;
+    /** Total number of messages in the session */
+    messageCount: number;
+    /** ID of the most recent message for efficient iteration */
+    newestMessageId?: string;
+    /** ID of the oldest message for complete traversal */
+    oldestMessageId?: string;
+    /** Unique session identifier */
+    sessionId: string;
+    /** Optional user-provided or auto-generated title */
+    title?: string;
+    /** Unix timestamp of last update */
+    updatedAt: number;
+}
+/**
+ * Individual message stored at ["message", sessionId, messageId].
+ *
+ * Messages are stored individually to enable:
+ * - Streaming from newest to oldest
+ * - Efficient single-message updates
+ * - Compaction boundary markers
+ */
+export interface StoredMessage {
+    /**
+     * Flag indicating this is a compaction boundary.
+     * When loading history, stop at the first compaction boundary.
+     * Messages before this point are summarized and not needed.
+     */
+    compactionBoundary?: boolean;
+    /**
+     * Summary content if this is a compaction boundary message.
+     * Contains the LLM-generated summary of prior conversation.
+     */
+    compactionSummary?: string;
+    /**
+     * The text content of the message.
+     * - null for assistant messages with only tool calls
+     * - string for most messages
+     */
+    content: null | string;
+    /** Unix timestamp when message was created */
+    createdAt: number;
+    /** Unique message identifier (UUID) */
+    id: string;
+    /**
+     * Name of the tool that produced this result.
+     * Only present for tool messages.
+     */
+    name?: string;
+    /** ID of the next message (toward newest) for linked traversal */
+    nextMessageId?: string;
+    /** IDs of parts associated with this message, in order */
+    partIds: string[];
+    /** ID of the previous message (toward oldest) for linked traversal */
+    prevMessageId?: string;
+    /** Optional reasoning text from the model */
+    reasoning?: string;
+    /** Message role */
+    role: 'assistant' | 'system' | 'tool' | 'user';
+    /** Session this message belongs to */
+    sessionId: string;
+    /** Raw thought text from the model (Gemini) */
+    thought?: string;
+    /** Parsed thought summary (Gemini) */
+    thoughtSummary?: {
+        description: string;
+        subject: string;
+    };
+    /**
+     * ID of the tool call this message is responding to.
+     * Only present for tool messages.
+     */
+    toolCallId?: string;
+    /**
+     * Tool calls made by the assistant.
+     * Only present for assistant messages requesting tool execution.
+     */
+    toolCalls?: ToolCall[];
+    /** 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,
+     * and a placeholder message should be shown instead.
+     */
+    compactedAt?: number;
+    /**
+     * The actual content of the part.
+     * - Tool output: string (JSON or text)
+     * - File: base64 encoded data, file path, or blob reference (@blob:id)
+     * - Text: raw text content
+     * - 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 */
+    createdAt: number;
+    /** Original filename for file parts */
+    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;
+    /**
+     * 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.
+ */
+export declare const COMPACTED_TOOL_OUTPUT_PLACEHOLDER = "[Old tool result content cleared]";
+/**
+ * Result of loading messages with compaction awareness.
+ */
+export interface LoadMessagesResult {
+    /** Whether a compaction boundary was reached */
+    hitCompactionBoundary: boolean;
+    /** Loaded messages in chronological order (oldest first) */
+    messages: StoredMessageWithParts[];
+}
+/**
+ * StoredMessage combined with its resolved parts.
+ * Used when converting back to InternalMessage format.
+ */
+export interface StoredMessageWithParts extends StoredMessage {
+    /** Resolved part objects (not just IDs) */
+    parts: StoredPart[];
+}
+/**
+ * Configuration for message streaming.
+ */
+export interface StreamMessagesOptions {
+    /**
+     * Maximum number of messages to load.
+     * Useful for preview/summary views.
+     */
+    limit?: number;
+    /**
+     * Session ID to stream messages from.
+     */
+    sessionId: string;
+    /**
+     * Whether to stop at the first compaction boundary.
+     * Default: true
+     */
+    stopAtCompaction?: boolean;
+}
+/**
+ * Configuration for tool output pruning.
+ */
+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 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.
+     */
+    sessionId: string;
+}
+/**
+ * Compaction operation result.
+ */
+export interface CompactionResult {
+    /** Number of parts that were compacted */
+    compactedCount: number;
+    /** New compaction boundary message ID */
+    compactionMessageId?: string;
+    /** Estimated tokens saved */
+    tokensSaved: number;
+}

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

@@ -0,0 +1,119 @@
+import type { ExecutionContext } from '../../interfaces/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/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',
+};