byterover-cli 0.4.1 → 1.0.0

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

@@ -1,18 +1,47 @@
 /**
  * Internal representation of messages in a conversation.
  * Standardizes message format across different LLM providers.
+ *
+ * Based on OpenCode's structured message parts pattern with:
+ * - Discriminated union parts (text, image, file, reasoning, tool)
+ * - Tool state machine (pending → running → completed/error)
+ * - Part-level metadata (synthetic flag, cache control)
+ * - Tool output attachments
  */
+/**
+ * Base interface for all message parts.
+ * Provides common metadata fields for cache hints and synthetic content marking.
+ */
+export interface BasePart {
+    /**
+     * Part-level metadata for cache hints and custom data.
+     * Used for Anthropic cache control and provider-specific features.
+     */
+    metadata?: {
+        /** Custom metadata fields */
+        [key: string]: unknown;
+        /** Anthropic cache control hint */
+        cacheControl?: {
+            type: 'ephemeral' | 'permanent';
+        };
+    };
+    /**
+     * Whether this is auto-generated content (e.g., "File saved", "Tool completed").
+     * Synthetic parts can be filtered or styled differently in UI.
+     */
+    synthetic?: boolean;
+}
 /**
  * Text content part
  */
-export interface TextPart {
+export interface TextPart extends BasePart {
     text: string;
     type: 'text';
 }
 /**
  * Image content part
  */
-export interface ImagePart {
+export interface ImagePart extends BasePart {
     image: ArrayBuffer | Buffer | string | Uint8Array | URL;
     mimeType?: string;
     type: 'image';
@@ -20,16 +49,238 @@ export interface ImagePart {
 /**
  * File content part
  */
-export interface FilePart {
+export interface FilePart extends BasePart {
     data: ArrayBuffer | Buffer | string | Uint8Array | URL;
     filename?: string;
     mimeType: string;
     type: 'file';
 }
 /**
- * Union type for message content parts
+ * Reasoning/thinking content part.
+ * Represents structured thinking traces from models like Gemini or Claude.
+ */
+export interface ReasoningPart extends BasePart {
+    /**
+     * Parsed summary for display in UI.
+     * Extracted from the raw text for easier rendering.
+     */
+    summary?: {
+        /** Detailed description of the thought */
+        description: string;
+        /** Brief subject of the thought */
+        subject: string;
+    };
+    /** Raw reasoning/thinking text from the model */
+    text: string;
+    type: 'reasoning';
+}
+/**
+ * Tool call in pending state (received from LLM, not yet started).
+ */
+export interface ToolStatePending {
+    /** Parsed input arguments */
+    input: Record<string, unknown>;
+    status: 'pending';
+}
+/**
+ * Tool call in running state (execution started).
+ */
+export interface ToolStateRunning {
+    /** Parsed input arguments */
+    input: Record<string, unknown>;
+    /** Unix timestamp when execution started */
+    startedAt: number;
+    status: 'running';
+}
+/**
+ * Tool call in completed state (execution finished successfully).
+ */
+export interface ToolStateCompleted {
+    /** Attachments produced by the tool (images, files) */
+    attachments?: AttachmentPart[];
+    /** Unix timestamp when this output was marked as compacted (for pruning) */
+    compactedAt?: number;
+    /** Parsed input arguments */
+    input: Record<string, unknown>;
+    /** Additional metadata about the execution */
+    metadata?: Record<string, unknown>;
+    /** Tool output content */
+    output: string;
+    status: 'completed';
+    /** Execution timing */
+    time: {
+        end: number;
+        start: number;
+    };
+    /** Human-readable title for display */
+    title?: string;
+}
+/**
+ * Tool call in error state (execution failed).
+ */
+export interface ToolStateError {
+    /** Error message */
+    error: string;
+    /** Parsed input arguments */
+    input: Record<string, unknown>;
+    status: 'error';
+    /** Execution timing (may have partial timing if failed mid-execution) */
+    time: {
+        end: number;
+        start: number;
+    };
+}
+/**
+ * Union of all tool states.
+ */
+export type ToolState = ToolStateCompleted | ToolStateError | ToolStatePending | ToolStateRunning;
+/**
+ * Attachment produced by a tool (image, file).
+ * Used for MCP tools that return binary content.
+ */
+export interface AttachmentPart {
+    /** Base64-encoded data or data URL */
+    data: string;
+    /** Original filename if available */
+    filename?: string;
+    /** MIME type of the attachment */
+    mime: string;
+    type: 'file' | 'image';
+}
+/**
+ * Tool call part with state machine.
+ * Tracks the full lifecycle of a tool call from pending to completed/error.
+ *
+ * This replaces the separate tool tracking in the execution queue,
+ * integrating tool state directly into message parts for:
+ * - Better conversation history representation
+ * - Efficient compaction (can mark individual tool outputs as compacted)
+ * - Rich UI feedback during execution
  */
-export type MessagePart = FilePart | ImagePart | TextPart;
+export interface ToolPart extends BasePart {
+    /** Unique identifier for this tool call */
+    callId: string;
+    /** Current state of the tool call */
+    state: ToolState;
+    /** Name of the tool being called */
+    toolName: string;
+    type: 'tool';
+}
+/**
+ * Snapshot part - captures code/file state at a point in time.
+ * Used for tracking state before/after operations for undo/revert.
+ */
+export interface SnapshotPart extends BasePart {
+    /** Unique identifier for this snapshot */
+    id: string;
+    /** Snapshot data as JSON string */
+    snapshot: string;
+    /** Unix timestamp when snapshot was taken */
+    timestamp: number;
+    type: 'snapshot';
+}
+/**
+ * Patch part - represents a file diff/change.
+ * Used for tracking file modifications and enabling rich diff views.
+ */
+export interface PatchPart extends BasePart {
+    /** Unified diff content */
+    diff: string;
+    /** Path to the file that was modified */
+    filePath: string;
+    /** Unique identifier for this patch */
+    id: string;
+    /** Number of lines added */
+    linesAdded: number;
+    /** Number of lines removed */
+    linesRemoved: number;
+    type: 'patch';
+}
+/**
+ * Step start part - marks the beginning of an execution step.
+ * Used for tracking multi-step operations and providing progress feedback.
+ */
+export interface StepStartPart extends BasePart {
+    /** Unique identifier for this step */
+    id: string;
+    /** Step index (0-based) */
+    stepIndex: number;
+    /** Unix timestamp when step started */
+    timestamp: number;
+    type: 'step_start';
+}
+/**
+ * Step finish part - marks the end of an execution step with cost/token info.
+ * Used for tracking per-step costs and providing detailed analytics.
+ */
+export interface StepFinishPart extends BasePart {
+    /** Cost in dollars for this step */
+    cost: number;
+    /** Why this step finished */
+    finishReason: 'max_tokens' | 'stop' | 'tool_calls';
+    /** Unique identifier for this step */
+    id: string;
+    /** Step index (0-based) */
+    stepIndex: number;
+    /** Unix timestamp when step finished */
+    timestamp: number;
+    /** Token usage for this step */
+    tokens: {
+        /** Cache tokens (read/write) */
+        cache?: {
+            read: number;
+            write: number;
+        };
+        /** Input tokens consumed */
+        input: number;
+        /** Output tokens generated */
+        output: number;
+        /** Reasoning tokens (if extended thinking enabled) */
+        reasoning?: number;
+    };
+    type: 'step_finish';
+}
+/**
+ * Compaction part - marks a context compaction boundary.
+ * Inserted when context is compacted to preserve summary of removed content.
+ */
+export interface CompactionPart extends BasePart {
+    /** IDs of messages that were compacted */
+    compactedMessageIds: string[];
+    /** Unique identifier for this compaction */
+    id: string;
+    /** Summary of the compacted content */
+    summary: string;
+    /** Unix timestamp when compaction occurred */
+    timestamp: number;
+    /** Number of tokens saved by compaction */
+    tokensSaved: number;
+    type: 'compaction';
+}
+/**
+ * Retry part - tracks retry attempts for failed operations.
+ * Used for debugging and providing visibility into retry behavior.
+ */
+export interface RetryPart extends BasePart {
+    /** Current retry attempt number (1-based) */
+    attempt: number;
+    /** Error message from the failed attempt */
+    errorMessage: string;
+    /** Unique identifier for this retry */
+    id: string;
+    /** Maximum number of retry attempts */
+    maxAttempts: number;
+    /** Unix timestamp of next retry (if scheduled) */
+    nextRetryAt?: number;
+    /** What operation is being retried */
+    operation: string;
+    type: 'retry';
+}
+/**
+ * Union type for message content parts.
+ * Discriminated by the `type` field.
+ */
+export type MessagePart = CompactionPart | FilePart | ImagePart | PatchPart | ReasoningPart | RetryPart | SnapshotPart | StepFinishPart | StepStartPart | TextPart | ToolPart;
 /**
  * Tool call made by the assistant
  */
@@ -68,6 +319,29 @@ export interface InternalMessage {
      * - null if an assistant message only contains tool calls.
      */
     content: Array<MessagePart> | null | string;
+    /**
+     * Message-level metadata for compression and tracking.
+     * Used by compression strategies to mark summary messages and track compaction.
+     */
+    metadata?: {
+        /** Custom metadata fields */
+        [key: string]: unknown;
+        /**
+         * Unix timestamp when this message was created via compaction.
+         * Present on summary messages created by compression strategies.
+         */
+        compactedAt?: number;
+        /**
+         * Whether this message is a summary of prior conversation.
+         * When true, messages before this point can be filtered at read-time.
+         */
+        isSummary?: boolean;
+        /**
+         * Number of messages that were summarized into this one.
+         * Present when isSummary is true.
+         */
+        summarizedMessageCount?: number;
+    };
     /**
      * Name of the tool that produced this result.
      * Only present in tool messages.

package/dist/core/interfaces/cipher/message-types.js

@@ -1,5 +1,11 @@
 /**
  * Internal representation of messages in a conversation.
  * Standardizes message format across different LLM providers.
+ *
+ * Based on OpenCode's structured message parts pattern with:
+ * - Discriminated union parts (text, image, file, reasoning, tool)
+ * - Tool state machine (pending → running → completed/error)
+ * - Part-level metadata (synthetic flag, cache control)
+ * - Tool output attachments
  */
 export {};

package/dist/core/interfaces/cipher/sanitization-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Types for tool output sanitization.
+ *
+ * These types define the structure of sanitized tool results,
+ * enabling consistent handling of tool outputs across the system.
+ *
+ */
+import type { MessagePart } from './message-types.js';
+/**
+ * Resource kind categories for media content.
+ */
+export type ResourceKind = 'audio' | 'binary' | 'image' | 'video';
+/**
+ * Resource descriptor created during tool output sanitization.
+ * Tracks media resources that were extracted and potentially stored as blobs.
+ */
+export interface ResourceDescriptor {
+    /** Original filename if available */
+    filename?: string;
+    /** Kind of resource based on MIME type */
+    kind: ResourceKind;
+    /** MIME type of the resource */
+    mimeType: string;
+    /** Size in bytes if known */
+    size?: number;
+    /** URI reference to the resource (e.g., "blob:abc123") */
+    uri: string;
+}
+/**
+ * Metadata about the tool execution.
+ */
+export interface ToolExecutionMeta {
+    /** Any additional metadata from the tool */
+    additionalMeta?: Record<string, unknown>;
+    /** Duration of tool execution in milliseconds (if tracked) */
+    durationMs?: number;
+    /** Whether the tool execution succeeded */
+    success: boolean;
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Name of the tool that was executed */
+    toolName: string;
+}
+/**
+ * Result of sanitizing a tool output.
+ *
+ * Contains the sanitized content parts, resource descriptors for any
+ * media that was extracted, and metadata about the tool execution.
+ */
+export interface SanitizedToolResult {
+    /** Sanitized content parts ready for message storage */
+    content: MessagePart[];
+    /** Metadata about the tool execution */
+    meta: ToolExecutionMeta;
+    /**
+     * Resource descriptors for media extracted during sanitization.
+     * These may reference blob storage if media was persisted.
+     */
+    resources?: ResourceDescriptor[];
+}
+/**
+ * Options for the tool result sanitization process.
+ */
+export interface SanitizeToolResultOptions {
+    /**
+     * Blob storage for persisting large media.
+     * If not provided, large media will be truncated or omitted.
+     */
+    blobStorage?: import('./i-blob-storage.js').IBlobStorage;
+    /** Duration of tool execution in milliseconds */
+    durationMs?: number;
+    /**
+     * Maximum size in bytes for inline media (default: 5KB).
+     * Media larger than this will be stored as blob references.
+     */
+    maxInlineMediaBytes?: number;
+    /**
+     * Maximum length for text content (default: 8000 chars).
+     * Longer text will be truncated with head + tail pattern.
+     */
+    maxTextLength?: number;
+    /** Whether the tool execution succeeded */
+    success: boolean;
+    /** Unique identifier for this tool call */
+    toolCallId: string;
+    /** Name of the tool that produced the output */
+    toolName: string;
+}
+/**
+ * Result of normalizing raw tool output to MessagePart array.
+ * Intermediate step in the sanitization pipeline.
+ */
+export interface NormalizedToolOutput {
+    /** MIME types detected in the output */
+    detectedMimeTypes: string[];
+    /** Whether any binary content was detected */
+    hasBinaryContent: boolean;
+    /** Normalized content parts */
+    parts: MessagePart[];
+}
+/**
+ * Result of persisting media to blob storage.
+ * Intermediate step in the sanitization pipeline.
+ */
+export interface PersistMediaResult {
+    /** Number of blobs created */
+    blobsCreated: number;
+    /** Total bytes stored */
+    bytesStored: number;
+    /** Parts with blob references replacing inline data */
+    parts: MessagePart[];
+    /** Resource descriptors for persisted media */
+    resources: ResourceDescriptor[];
+}
+/**
+ * Configuration for text truncation.
+ */
+export interface TextTruncationConfig {
+    /** Characters to keep from the start (default: 4000) */
+    headLength: number;
+    /** Maximum total length (default: 8000) */
+    maxLength: number;
+    /** Placeholder text for omitted content */
+    placeholder: string;
+    /** Characters to keep from the end (default: 1000) */
+    tailLength: number;
+}
+/**
+ * Default text truncation configuration.
+ */
+export declare const DEFAULT_TEXT_TRUNCATION: TextTruncationConfig;
+/**
+ * Default maximum inline media size (5KB).
+ */
+export declare const DEFAULT_MAX_INLINE_MEDIA_BYTES: number;
+/**
+ * MIME types that should always be stored as blobs regardless of size.
+ */
+export declare const ALWAYS_BLOB_MIME_TYPES: string[];
+/**
+ * Check if a MIME type should always be stored as a blob.
+ */
+export declare function shouldAlwaysBlob(mimeType: string): boolean;
+/**
+ * Infer resource kind from MIME type.
+ */
+export declare function inferResourceKind(mimeType: string): ResourceKind;

package/dist/core/interfaces/cipher/sanitization-types.js

@@ -0,0 +1,46 @@
+/**
+ * Types for tool output sanitization.
+ *
+ * These types define the structure of sanitized tool results,
+ * enabling consistent handling of tool outputs across the system.
+ *
+ */
+/**
+ * Default text truncation configuration.
+ */
+export const DEFAULT_TEXT_TRUNCATION = {
+    headLength: 4000,
+    maxLength: 8000,
+    placeholder: '\n... [{count} chars omitted] ...\n',
+    tailLength: 1000,
+};
+/**
+ * Default maximum inline media size (5KB).
+ */
+export const DEFAULT_MAX_INLINE_MEDIA_BYTES = 5 * 1024;
+/**
+ * MIME types that should always be stored as blobs regardless of size.
+ */
+export const ALWAYS_BLOB_MIME_TYPES = [
+    'audio/',
+    'video/',
+];
+/**
+ * Check if a MIME type should always be stored as a blob.
+ */
+export function shouldAlwaysBlob(mimeType) {
+    return ALWAYS_BLOB_MIME_TYPES.some((prefix) => mimeType.toLowerCase().startsWith(prefix));
+}
+/**
+ * Infer resource kind from MIME type.
+ */
+export function inferResourceKind(mimeType) {
+    const lower = mimeType.toLowerCase();
+    if (lower.startsWith('image/'))
+        return 'image';
+    if (lower.startsWith('audio/'))
+        return 'audio';
+    if (lower.startsWith('video/'))
+        return 'video';
+    return 'binary';
+}

package/dist/core/interfaces/executor/i-curate-executor.d.ts

@@ -0,0 +1,34 @@
+import type { ICipherAgent } from '../cipher/i-cipher-agent.js';
+/**
+ * Options for executing curate with an injected agent.
+ * Agent uses its default session (Single-Session pattern).
+ */
+export interface CurateExecuteOptions {
+    /** Context content to curate */
+    content: string;
+    /** Optional file paths for --files flag */
+    files?: string[];
+    /** Task ID for event routing (required for concurrent task isolation) */
+    taskId: string;
+}
+/**
+ * ICurateExecutor - Executes curate tasks with an injected CipherAgent.
+ *
+ * This is NOT a UseCase (which orchestrates business logic).
+ * It's an Executor that wraps agent.execute() with curate-specific options.
+ *
+ * Architecture:
+ * - TaskProcessor injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - Executor focuses solely on curate execution
+ */
+export interface ICurateExecutor {
+    /**
+     * Execute curate with an injected agent.
+     *
+     * @param agent - Long-lived CipherAgent (managed by caller)
+     * @param options - Execution options (content, file references)
+     * @returns Result string from agent execution
+     */
+    executeWithAgent(agent: ICipherAgent, options: CurateExecuteOptions): Promise<string>;
+}

package/dist/core/interfaces/executor/i-curate-executor.js

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

package/dist/core/interfaces/executor/i-query-executor.d.ts

@@ -0,0 +1,32 @@
+import type { ICipherAgent } from '../cipher/i-cipher-agent.js';
+/**
+ * Options for executing query with an injected agent.
+ * Agent uses its default session (Single-Session pattern).
+ */
+export interface QueryExecuteOptions {
+    /** Query content to search in context tree */
+    query: string;
+    /** Task ID for event routing (required for concurrent task isolation) */
+    taskId: string;
+}
+/**
+ * IQueryExecutor - Executes query tasks with an injected CipherAgent.
+ *
+ * This is NOT a UseCase (which orchestrates business logic).
+ * It's an Executor that wraps agent.execute() with query-specific options.
+ *
+ * Architecture:
+ * - TaskProcessor injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - Executor focuses solely on query execution
+ */
+export interface IQueryExecutor {
+    /**
+     * Execute query with an injected agent.
+     *
+     * @param agent - Long-lived CipherAgent (managed by caller)
+     * @param options - Execution options (query)
+     * @returns Result string from agent execution
+     */
+    executeWithAgent(agent: ICipherAgent, options: QueryExecuteOptions): Promise<string>;
+}

package/dist/core/interfaces/executor/i-query-executor.js

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

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

@@ -0,0 +1,2 @@
+export * from './i-curate-executor.js';
+export * from './i-query-executor.js';

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

@@ -0,0 +1,2 @@
+export * from './i-curate-executor.js';
+export * from './i-query-executor.js';

package/dist/core/interfaces/instance/i-instance-discovery.d.ts

@@ -0,0 +1,45 @@
+import type { InstanceInfo } from '../../domain/instance/types.js';
+/**
+ * Result of instance discovery.
+ *
+ * - no_instance: No .brv/ directory found in tree
+ * - instance_crashed: Found instance.json but pid is dead
+ */
+export type DiscoveryResult = {
+    found: false;
+    reason: 'instance_crashed' | 'no_instance';
+} | {
+    found: true;
+    instance: InstanceInfo;
+    projectRoot: string;
+};
+/**
+ * Interface for discovering running instances via walk-up directory search.
+ *
+ * Architecture notes (Section 5 - Transport Discovery):
+ * Walk up directory tree to find .brv/instance.json, verify pid alive.
+ */
+export interface IInstanceDiscovery {
+    /**
+     * Discovers a running instance starting from the given directory.
+     *
+     * Walk-up algorithm:
+     * 1. Start from `fromDir`
+     * 2. Check if .brv/instance.json exists
+     * 3. If yes, verify pid is alive
+     * 4. If no, walk up to parent directory
+     * 5. Repeat until root or found
+     *
+     * @param fromDir - Starting directory (usually cwd)
+     * @returns DiscoveryResult with instance info and project root if found
+     */
+    discover: (fromDir: string) => Promise<DiscoveryResult>;
+    /**
+     * Finds the project root by walking up from a directory.
+     * Returns the directory containing .brv/ or undefined if not found.
+     *
+     * @param fromDir - Starting directory
+     * @returns Project root path or undefined
+     */
+    findProjectRoot: (fromDir: string) => Promise<string | undefined>;
+}

package/dist/core/interfaces/instance/i-instance-discovery.js

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