byterover-cli 0.3.4 → 0.4.0

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

@@ -0,0 +1,218 @@
+/**
+ * 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/cipher/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;
+}
+/**
+ * Message part stored at ["part", messageId, partId].
+ *
+ * Parts contain content that may be pruned independently:
+ * - Tool outputs (large, can be marked as compacted)
+ * - File attachments
+ * - Image data
+ *
+ * Parts are stored separately to enable:
+ * - Selective pruning of old tool outputs
+ * - Lazy loading of large content
+ * - Efficient streaming without loading all content
+ */
+export interface StoredPart {
+    /**
+     * 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 or file path
+     * - Text: raw text content
+     * - Image: base64 encoded data
+     *
+     * When compactedAt is set, this will be empty or contain a placeholder.
+     */
+    content: string;
+    /** Unix timestamp when part was created */
+    createdAt: number;
+    /** Original filename for file parts */
+    filename?: string;
+    /** Unique part identifier (UUID) */
+    id: string;
+    /** ID of the message this part belongs to */
+    messageId: string;
+    /** MIME type for file and image parts */
+    mimeType?: string;
+    /**
+     * 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';
+}
+/**
+ * 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)
+     */
+    keepTokens?: 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/core/domain/cipher/storage/message-storage-types.js

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+/**
+ * Placeholder message shown when tool output has been compacted.
+ */
+export const COMPACTED_TOOL_OUTPUT_PLACEHOLDER = '[Old tool result content cleared]';

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

@@ -6,6 +6,7 @@ export declare const ToolName: {
     readonly BASH_EXEC: 'bash_exec';
     readonly BASH_OUTPUT: 'bash_output';
     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';

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

@@ -6,6 +6,7 @@ export const ToolName = {
     BASH_EXEC: 'bash_exec',
     BASH_OUTPUT: 'bash_output',
     CREATE_KNOWLEDGE_TOPIC: 'create_knowledge_topic',
+    CURATE: 'curate',
     DELETE_MEMORY: 'delete_memory',
     DETECT_DOMAINS: 'detect_domains',
     EDIT_FILE: 'edit_file',

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"];
+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 type EventName = (typeof EVENT_VALUES)[number];
 export interface PropertyDict {
     [key: string]: any;

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

@@ -12,4 +12,9 @@ export const EVENT_VALUES = [
     'mem:pull',
     'mem:push',
     'mem:query',
+    'onboarding:init_completed',
+    'onboarding:curate_completed',
+    'onboarding:query_completed',
+    'onboarding:skipped',
+    'onboarding:completed',
 ];

package/dist/core/domain/entities/global-config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Parameters for creating a GlobalConfig instance.
+ */
+export interface GlobalConfigParams {
+    readonly deviceId: string;
+    readonly version: string;
+}
+/**
+ * Represents the global configuration stored in the user's config directory.
+ * Contains device-level settings that persist across all projects.
+ */
+export declare class GlobalConfig {
+    readonly deviceId: string;
+    readonly version: string;
+    private constructor();
+    /**
+     * Creates a new GlobalConfig with the given device ID and current version.
+     *
+     * @param deviceId - The unique device identifier (UUID v4)
+     * @returns A new GlobalConfig instance
+     * @throws Error if deviceId is empty
+     */
+    static create(deviceId: string): GlobalConfig;
+    /**
+     * Deserializes config from JSON format.
+     * Returns undefined for invalid JSON structure (graceful failure).
+     *
+     * @param json - The JSON object to deserialize
+     * @returns GlobalConfig instance or undefined if invalid
+     */
+    static fromJson(json: unknown): GlobalConfig | undefined;
+    /**
+     * Serializes the config to JSON format.
+     */
+    toJson(): Record<string, string>;
+}

package/dist/core/domain/entities/global-config.js

@@ -0,0 +1,66 @@
+import { GLOBAL_CONFIG_VERSION } from '../../../constants.js';
+/**
+ * Type guard for GlobalConfig JSON validation.
+ */
+const isGlobalConfigJson = (json) => {
+    if (typeof json !== 'object' || json === null || json === undefined)
+        return false;
+    const obj = json;
+    if (typeof obj.deviceId !== 'string' || obj.deviceId.trim().length === 0) {
+        return false;
+    }
+    if (typeof obj.version !== 'string') {
+        return false;
+    }
+    return true;
+};
+/**
+ * Represents the global configuration stored in the user's config directory.
+ * Contains device-level settings that persist across all projects.
+ */
+export class GlobalConfig {
+    deviceId;
+    version;
+    constructor(params) {
+        this.deviceId = params.deviceId;
+        this.version = params.version;
+    }
+    /**
+     * Creates a new GlobalConfig with the given device ID and current version.
+     *
+     * @param deviceId - The unique device identifier (UUID v4)
+     * @returns A new GlobalConfig instance
+     * @throws Error if deviceId is empty
+     */
+    static create(deviceId) {
+        if (deviceId.trim().length === 0) {
+            throw new Error('Device ID cannot be empty');
+        }
+        return new GlobalConfig({
+            deviceId,
+            version: GLOBAL_CONFIG_VERSION,
+        });
+    }
+    /**
+     * Deserializes config from JSON format.
+     * Returns undefined for invalid JSON structure (graceful failure).
+     *
+     * @param json - The JSON object to deserialize
+     * @returns GlobalConfig instance or undefined if invalid
+     */
+    static fromJson(json) {
+        if (!isGlobalConfigJson(json)) {
+            return undefined;
+        }
+        return new GlobalConfig(json);
+    }
+    /**
+     * Serializes the config to JSON format.
+     */
+    toJson() {
+        return {
+            deviceId: this.deviceId,
+            version: this.version,
+        };
+    }
+}

package/dist/core/domain/knowledge/directory-manager.d.ts

@@ -34,6 +34,16 @@ export declare const DirectoryManager: {
      * @returns Whether topic was created, updated, or skipped
      */
     createOrUpdateTopic(topicPath: string): Promise<CreateOrUpdateResult>;
+    /**
+     * Delete a topic/subtopic folder recursively.
+     * Removes the folder and all its contents.
+     *
+     * @param topicPath - Full path to topic folder to delete
+     * @returns Whether the topic was deleted
+     */
+    deleteTopicRecursive(topicPath: string): Promise<{
+        deleted: boolean;
+    }>;
     /**
      * Ensure the base knowledge structure exists.
      * Creates .brv/context-tree/ directory if it doesn't exist.

package/dist/core/domain/knowledge/directory-manager.js

@@ -43,6 +43,24 @@ export const DirectoryManager = {
             return { created: true, skipped: false, updated: false };
         }
     },
+    /**
+     * Delete a topic/subtopic folder recursively.
+     * Removes the folder and all its contents.
+     *
+     * @param topicPath - Full path to topic folder to delete
+     * @returns Whether the topic was deleted
+     */
+    async deleteTopicRecursive(topicPath) {
+        try {
+            await fs.access(topicPath);
+            await fs.rm(topicPath, { force: true, recursive: true });
+            return { deleted: true };
+        }
+        catch {
+            // Path doesn't exist or already deleted
+            return { deleted: false };
+        }
+    },
     /**
      * Ensure the base knowledge structure exists.
      * Creates .brv/context-tree/ directory if it doesn't exist.

package/dist/core/domain/knowledge/markdown-writer.d.ts

@@ -15,4 +15,13 @@ export declare const MarkdownWriter: {
      * Used for both topics and subtopics in the knowledge hierarchy.
      */
     generateContext(data: ContextData): string;
+    /**
+     * Merge two context.md contents into one.
+     * Combines snippets and relations, deduplicating where possible.
+     *
+     * @param sourceContent - Raw content from source context.md
+     * @param targetContent - Raw content from target context.md
+     * @returns Merged context.md content
+     */
+    mergeContexts(sourceContent: string, targetContent: string): string;
 };

package/dist/core/domain/knowledge/markdown-writer.js

@@ -1,4 +1,22 @@
-import { generateRelationsSection } from './relation-parser.js';
+import { generateRelationsSection, parseRelations } from './relation-parser.js';
+/**
+ * Extract snippets from context.md content.
+ * Removes relations section and splits by separator.
+ */
+function extractSnippetsFromContent(content) {
+    // Remove relations section if present
+    let snippetContent = content;
+    const relationsMatch = content.match(/## Relations[\s\S]*?(?=\n[^@\n]|$)/);
+    if (relationsMatch) {
+        snippetContent = content.replace(relationsMatch[0], '').trim();
+    }
+    // Split by separator and filter empty
+    const snippets = snippetContent
+        .split(/\n---\n/)
+        .map(s => s.trim())
+        .filter(s => s && s !== 'No context available.');
+    return snippets;
+}
 /**
  * Generates Markdown files for knowledge context.
  */
@@ -13,6 +31,38 @@ export const MarkdownWriter = {
         const relationsSection = generateRelationsSection(relations);
         return `${relationsSection}
 ${snippets.length > 0 ? snippets.map(s => `${s}`).join('\n\n---\n\n') : 'No context available.'}
+`;
+    },
+    /**
+     * Merge two context.md contents into one.
+     * Combines snippets and relations, deduplicating where possible.
+     *
+     * @param sourceContent - Raw content from source context.md
+     * @param targetContent - Raw content from target context.md
+     * @returns Merged context.md content
+     */
+    mergeContexts(sourceContent, targetContent) {
+        // Extract relations from both contents
+        const sourceRelations = parseRelations(sourceContent);
+        const targetRelations = parseRelations(targetContent);
+        // Merge and deduplicate relations
+        const mergedRelations = [...new Set([...sourceRelations, ...targetRelations])];
+        const sourceSnippets = extractSnippetsFromContent(sourceContent);
+        const targetSnippets = extractSnippetsFromContent(targetContent);
+        // Merge snippets (target first, then source)
+        // Deduplicate by exact match
+        const seenSnippets = new Set();
+        const mergedSnippets = [];
+        for (const snippet of [...targetSnippets, ...sourceSnippets]) {
+            if (!seenSnippets.has(snippet)) {
+                seenSnippets.add(snippet);
+                mergedSnippets.push(snippet);
+            }
+        }
+        // Generate merged content
+        const relationsSection = generateRelationsSection(mergedRelations);
+        return `${relationsSection}
+${mergedSnippets.length > 0 ? mergedSnippets.join('\n\n---\n\n') : 'No context available.'}
 `;
     },
 };

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

@@ -0,0 +1,152 @@
+import type { Execution, ExecutionStatus, ExecutionType, ToolCall, ToolCallInfo, ToolCallStatus, ToolCallUpdateOptions } from '../../domain/cipher/queue/types.js';
+/**
+ * Interface for agent execution storage.
+ *
+ * Manages the execution queue, tool call tracking, and consumer locks.
+ * Implementations can use different storage backends (SQLite, in-memory, etc.)
+ */
+export interface IAgentStorage {
+    /**
+     * Acquire consumer lock (register this consumer).
+     * Only ONE consumer can run at a time.
+     * @param consumerId - Unique ID for this consumer
+     * @returns true if lock acquired, false if another consumer is already running
+     */
+    acquireConsumerLock(consumerId: string): boolean;
+    /**
+     * Add a tool call record.
+     * @returns tool call id
+     */
+    addToolCall(executionId: string, info: ToolCallInfo): string;
+    /**
+     * Cleanup old executions, keep only maxKeep most recent completed/failed.
+     * @returns number of deleted executions
+     */
+    cleanupOldExecutions(maxKeep?: number): number;
+    /**
+     * Cleanup orphaned executions (status='running') from previous session crash.
+     * @returns number of orphaned executions
+     */
+    cleanupOrphanedExecutions(): number;
+    /**
+     * Cleanup stale consumers and orphan their executions.
+     * @param timeoutMs - heartbeat timeout (default 30 seconds)
+     * @returns number of orphaned executions
+     */
+    cleanupStaleConsumers(timeoutMs?: number): number;
+    /**
+     * Close storage connection.
+     */
+    close(): void;
+    /**
+     * Create a new execution.
+     * @param type - 'curate' or 'query'
+     * @param input - content (curate) or query string (query)
+     * @returns execution id
+     */
+    createExecution(type: ExecutionType, input: string): string;
+    /**
+     * Dequeue multiple executions at once (atomic batch SELECT + UPDATE).
+     * @param limit - max number of executions to dequeue
+     * @param consumerId - ID of the consumer claiming these executions
+     * @returns array of executions (may be empty if queue is empty)
+     */
+    dequeueBatch(limit: number, consumerId?: string): Execution[];
+    /**
+     * Dequeue next queued execution (atomic SELECT + UPDATE).
+     * @param consumerId - ID of the consumer claiming this execution
+     * @returns execution or null if queue is empty
+     */
+    dequeueExecution(consumerId?: string): Execution | null;
+    /**
+     * Get execution by id.
+     */
+    getExecution(id: string): Execution | null;
+    /**
+     * Get executions updated since timestamp (for incremental polling).
+     */
+    getExecutionsSince(timestamp: number): Execution[];
+    /**
+     * Get execution with all its tool calls (for UI display).
+     */
+    getExecutionWithToolCalls(id: string): null | {
+        execution: Execution;
+        toolCalls: ToolCall[];
+    };
+    /**
+     * Get all queued executions.
+     */
+    getQueuedExecutions(): Execution[];
+    /**
+     * Get recent executions (for UI display).
+     */
+    getRecentExecutions(limit?: number): Execution[];
+    /**
+     * Get all running executions.
+     */
+    getRunningExecutions(): Execution[];
+    /**
+     * Get all executions belonging to a specific consumer session.
+     * Returns executions ordered by created_at ASC (oldest first, newest last).
+     * @param consumerId - The consumer ID to filter by
+     */
+    getSessionExecutions(consumerId: string): Execution[];
+    /**
+     * Get queue statistics (queries DB directly for accurate counts).
+     */
+    getStats(): {
+        completed: number;
+        failed: number;
+        queued: number;
+        running: number;
+        total: number;
+    };
+    /**
+     * Get all tool calls for an execution.
+     */
+    getToolCalls(executionId: string): ToolCall[];
+    /**
+     * Check if any consumer is currently active (has recent heartbeat).
+     * @param timeoutMs - heartbeat timeout (default 30 seconds)
+     */
+    hasActiveConsumer(timeoutMs?: number): boolean;
+    /**
+     * Check if a specific consumer lock exists in the database.
+     * Used by Consumer to verify its lock is still valid after DB reconnection.
+     */
+    hasConsumerLock(consumerId: string): boolean;
+    /**
+     * Initialize storage.
+     */
+    initialize(options?: {
+        cleanupOrphans?: boolean;
+    }): Promise<void>;
+    /** Whether the storage has been initialized */
+    readonly initialized: boolean;
+    /**
+     * Check if the DB file has been replaced (different inode).
+     * Returns true if DB needs reconnection.
+     */
+    isDbFileChanged(): boolean;
+    /**
+     * Reconnect to the database (close and reinitialize).
+     * Use when DB file has been replaced by another process (e.g., brv init).
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Release consumer lock (unregister this consumer).
+     */
+    releaseConsumerLock(consumerId: string): void;
+    /**
+     * Update consumer heartbeat.
+     */
+    updateConsumerHeartbeat(consumerId: string): void;
+    /**
+     * Update execution status.
+     */
+    updateExecutionStatus(id: string, status: ExecutionStatus, result?: string, error?: string): void;
+    /**
+     * Update tool call status and result.
+     */
+    updateToolCall(id: string, status: ToolCallStatus, options?: ToolCallUpdateOptions): void;
+}

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

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

package/dist/core/interfaces/cipher/i-cipher-agent.d.ts

@@ -10,6 +10,8 @@ export interface ExecutionContext {
     commandType?: '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;
 }