byterover-cli 0.3.4 → 0.4.0

package/dist/infra/cipher/storage/dual-format-history-storage.d.ts

@@ -0,0 +1,77 @@
+import type { SessionMetadata } from '../../../core/domain/cipher/storage/history-types.js';
+import type { IHistoryStorage } from '../../../core/interfaces/cipher/i-history-storage.js';
+import type { InternalMessage } from '../../../core/interfaces/cipher/message-types.js';
+import type { BlobHistoryStorage } from './blob-history-storage.js';
+import type { GranularHistoryStorage } from './granular-history-storage.js';
+/**
+ * Dual-format history storage that routes between blob and granular storage.
+ *
+ * This router implements the "no migration" strategy:
+ * - NEW sessions → GranularHistoryStorage (message-per-key with streaming)
+ * - EXISTING sessions → BlobHistoryStorage (legacy single-blob format)
+ *
+ * Format detection:
+ * - Granular format: has a session record at ["session", sessionId]
+ * - Blob format: has a blob at "session-{sessionId}"
+ * - New session: neither exists, uses granular format
+ *
+ * This allows seamless coexistence of both formats without migration.
+ */
+export declare class DualFormatHistoryStorage implements IHistoryStorage {
+    private readonly blobStorage;
+    private readonly granularStorage;
+    constructor(blobStorage: BlobHistoryStorage, granularStorage: GranularHistoryStorage);
+    /**
+     * Delete all history for a session.
+     * Deletes from both storages to ensure complete cleanup.
+     */
+    deleteHistory(sessionId: string): Promise<void>;
+    /**
+     * Check if history exists for a session in either format.
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Get the underlying granular storage for advanced operations.
+     * Returns undefined if session is not in granular format.
+     */
+    getGranularStorage(sessionId: string): Promise<GranularHistoryStorage | undefined>;
+    /**
+     * Get metadata for a session from appropriate storage.
+     */
+    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * Check if a session uses granular format.
+     * Useful for consumers that want to use granular-specific features.
+     */
+    isGranularFormat(sessionId: string): Promise<boolean>;
+    /**
+     * List all session IDs from both storage formats.
+     */
+    listSessions(): Promise<string[]>;
+    /**
+     * Load conversation history for a session.
+     * Routes to appropriate storage based on session format.
+     */
+    loadHistory(sessionId: string): Promise<InternalMessage[] | undefined>;
+    /**
+     * Save conversation history for a session.
+     * Routes to appropriate storage based on session format.
+     *
+     * New sessions use granular format.
+     * Existing sessions stay in their original format.
+     */
+    saveHistory(sessionId: string, messages: InternalMessage[]): Promise<void>;
+    /**
+     * Detect which storage format a session uses.
+     *
+     * Priority:
+     * 1. Granular format (check first as it's the newer format)
+     * 2. Blob format (legacy)
+     * 3. None (new session)
+     */
+    private detectFormat;
+}
+/**
+ * Factory function to create DualFormatHistoryStorage.
+ */
+export declare function createDualFormatHistoryStorage(blobStorage: BlobHistoryStorage, granularStorage: GranularHistoryStorage): DualFormatHistoryStorage;

package/dist/infra/cipher/storage/dual-format-history-storage.js

@@ -0,0 +1,149 @@
+/**
+ * Dual-format history storage that routes between blob and granular storage.
+ *
+ * This router implements the "no migration" strategy:
+ * - NEW sessions → GranularHistoryStorage (message-per-key with streaming)
+ * - EXISTING sessions → BlobHistoryStorage (legacy single-blob format)
+ *
+ * Format detection:
+ * - Granular format: has a session record at ["session", sessionId]
+ * - Blob format: has a blob at "session-{sessionId}"
+ * - New session: neither exists, uses granular format
+ *
+ * This allows seamless coexistence of both formats without migration.
+ */
+export class DualFormatHistoryStorage {
+    blobStorage;
+    granularStorage;
+    constructor(blobStorage, granularStorage) {
+        this.blobStorage = blobStorage;
+        this.granularStorage = granularStorage;
+    }
+    /**
+     * Delete all history for a session.
+     * Deletes from both storages to ensure complete cleanup.
+     */
+    async deleteHistory(sessionId) {
+        const format = await this.detectFormat(sessionId);
+        if (format === 'granular') {
+            await this.granularStorage.deleteHistory(sessionId);
+        }
+        else if (format === 'blob') {
+            await this.blobStorage.deleteHistory(sessionId);
+        }
+        // For 'none', nothing to delete
+    }
+    /**
+     * Check if history exists for a session in either format.
+     */
+    async exists(sessionId) {
+        const format = await this.detectFormat(sessionId);
+        return format !== 'none';
+    }
+    /**
+     * Get the underlying granular storage for advanced operations.
+     * Returns undefined if session is not in granular format.
+     */
+    async getGranularStorage(sessionId) {
+        const format = await this.detectFormat(sessionId);
+        if (format === 'granular' || format === 'none') {
+            return this.granularStorage;
+        }
+        return undefined;
+    }
+    /**
+     * Get metadata for a session from appropriate storage.
+     */
+    async getSessionMetadata(sessionId) {
+        const format = await this.detectFormat(sessionId);
+        if (format === 'granular') {
+            return this.granularStorage.getSessionMetadata(sessionId);
+        }
+        if (format === 'blob') {
+            return this.blobStorage.getSessionMetadata(sessionId);
+        }
+        return undefined;
+    }
+    /**
+     * Check if a session uses granular format.
+     * Useful for consumers that want to use granular-specific features.
+     */
+    async isGranularFormat(sessionId) {
+        const format = await this.detectFormat(sessionId);
+        return format === 'granular';
+    }
+    /**
+     * List all session IDs from both storage formats.
+     */
+    async listSessions() {
+        const [blobSessions, granularSessions] = await Promise.all([
+            this.blobStorage.listSessions(),
+            this.granularStorage.listSessions(),
+        ]);
+        // Combine and deduplicate (shouldn't have duplicates, but be safe)
+        const allSessions = new Set([...blobSessions, ...granularSessions]);
+        return [...allSessions];
+    }
+    /**
+     * Load conversation history for a session.
+     * Routes to appropriate storage based on session format.
+     */
+    async loadHistory(sessionId) {
+        const format = await this.detectFormat(sessionId);
+        if (format === 'granular') {
+            return this.granularStorage.loadHistory(sessionId);
+        }
+        if (format === 'blob') {
+            return this.blobStorage.loadHistory(sessionId);
+        }
+        // New session - return undefined (no history yet)
+        return undefined;
+    }
+    /**
+     * Save conversation history for a session.
+     * Routes to appropriate storage based on session format.
+     *
+     * New sessions use granular format.
+     * Existing sessions stay in their original format.
+     */
+    async saveHistory(sessionId, messages) {
+        const format = await this.detectFormat(sessionId);
+        if (format === 'granular') {
+            return this.granularStorage.saveHistory(sessionId, messages);
+        }
+        if (format === 'blob') {
+            // Keep existing blob sessions in blob format
+            return this.blobStorage.saveHistory(sessionId, messages);
+        }
+        // New session - use granular format
+        return this.granularStorage.saveHistory(sessionId, messages);
+    }
+    /**
+     * Detect which storage format a session uses.
+     *
+     * Priority:
+     * 1. Granular format (check first as it's the newer format)
+     * 2. Blob format (legacy)
+     * 3. None (new session)
+     */
+    async detectFormat(sessionId) {
+        // Check granular format first (newer, preferred)
+        const isGranular = await this.granularStorage.exists(sessionId);
+        if (isGranular) {
+            return 'granular';
+        }
+        // Check blob format (legacy)
+        const isBlob = await this.blobStorage.exists(sessionId);
+        if (isBlob) {
+            return 'blob';
+        }
+        // New session
+        return 'none';
+    }
+}
+/**
+ * Factory function to create DualFormatHistoryStorage.
+ */
+export function createDualFormatHistoryStorage(blobStorage, granularStorage) {
+    return new DualFormatHistoryStorage(blobStorage, granularStorage);
+}

package/dist/infra/cipher/storage/granular-history-storage.d.ts

@@ -0,0 +1,65 @@
+import type { SessionMetadata } from '../../../core/domain/cipher/storage/history-types.js';
+import type { IHistoryStorage } from '../../../core/interfaces/cipher/i-history-storage.js';
+import type { InternalMessage } from '../../../core/interfaces/cipher/message-types.js';
+import { MessageStorageService } from './message-storage-service.js';
+/**
+ * Granular history storage implementation using MessageStorageService.
+ *
+ * This implementation stores messages individually, enabling:
+ * - Streaming message loading (newest to oldest)
+ * - Selective tool output pruning
+ * - Compaction boundary markers
+ *
+ * This is used for NEW sessions only. Existing sessions use BlobHistoryStorage.
+ */
+export declare class GranularHistoryStorage implements IHistoryStorage {
+    private readonly messageStorage;
+    constructor(messageStorage: MessageStorageService);
+    /**
+     * Append a single message to the session.
+     * More efficient than saveHistory for incremental updates.
+     */
+    appendMessage(sessionId: string, message: InternalMessage): Promise<void>;
+    /**
+     * Delete all history for a session.
+     */
+    deleteHistory(sessionId: string): Promise<void>;
+    /**
+     * Check if history exists for a session.
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Get metadata for a session without loading full history.
+     */
+    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * List all session IDs with persisted history.
+     */
+    listSessions(): Promise<string[]>;
+    /**
+     * Load conversation history for a session.
+     * Stops at compaction boundaries for efficient loading.
+     */
+    loadHistory(sessionId: string): Promise<InternalMessage[] | undefined>;
+    /**
+     * Save conversation history for a session.
+     *
+     * This is a complete replacement - it's more efficient to use
+     * appendMessage() for incremental updates.
+     */
+    saveHistory(sessionId: string, messages: InternalMessage[]): Promise<void>;
+    /**
+     * Stream messages from newest to oldest.
+     * More memory efficient for large histories.
+     *
+     * @yields InternalMessage - Messages from the session history
+     */
+    streamHistory(sessionId: string, options?: {
+        limit?: number;
+        stopAtCompaction?: boolean;
+    }): AsyncGenerator<InternalMessage>;
+}
+/**
+ * Factory function to create GranularHistoryStorage.
+ */
+export declare function createGranularHistoryStorage(messageStorage: MessageStorageService): GranularHistoryStorage;

package/dist/infra/cipher/storage/granular-history-storage.js

@@ -0,0 +1,118 @@
+/**
+ * Granular history storage implementation using MessageStorageService.
+ *
+ * This implementation stores messages individually, enabling:
+ * - Streaming message loading (newest to oldest)
+ * - Selective tool output pruning
+ * - Compaction boundary markers
+ *
+ * This is used for NEW sessions only. Existing sessions use BlobHistoryStorage.
+ */
+export class GranularHistoryStorage {
+    messageStorage;
+    constructor(messageStorage) {
+        this.messageStorage = messageStorage;
+    }
+    /**
+     * Append a single message to the session.
+     * More efficient than saveHistory for incremental updates.
+     */
+    async appendMessage(sessionId, message) {
+        await this.messageStorage.saveMessage(sessionId, message);
+    }
+    /**
+     * Delete all history for a session.
+     */
+    async deleteHistory(sessionId) {
+        await this.messageStorage.deleteSession(sessionId);
+    }
+    /**
+     * Check if history exists for a session.
+     */
+    async exists(sessionId) {
+        return this.messageStorage.hasSession(sessionId);
+    }
+    /**
+     * Get metadata for a session without loading full history.
+     */
+    async getSessionMetadata(sessionId) {
+        const session = await this.messageStorage.getSession(sessionId);
+        if (!session) {
+            return undefined;
+        }
+        return {
+            createdAt: session.createdAt,
+            lastActivity: session.updatedAt,
+            messageCount: session.messageCount,
+            sessionId: session.sessionId,
+            title: session.title,
+        };
+    }
+    /**
+     * List all session IDs with persisted history.
+     */
+    async listSessions() {
+        return this.messageStorage.listSessions();
+    }
+    /**
+     * Load conversation history for a session.
+     * Stops at compaction boundaries for efficient loading.
+     */
+    async loadHistory(sessionId) {
+        const hasSession = await this.messageStorage.hasSession(sessionId);
+        if (!hasSession) {
+            return undefined;
+        }
+        const result = await this.messageStorage.loadMessages(sessionId, { stopAtCompaction: true });
+        return this.messageStorage.toInternalMessages(result.messages);
+    }
+    /**
+     * Save conversation history for a session.
+     *
+     * This is a complete replacement - it's more efficient to use
+     * appendMessage() for incremental updates.
+     */
+    async saveHistory(sessionId, messages) {
+        // Check if session exists
+        const existingSession = await this.messageStorage.getSession(sessionId);
+        if (existingSession) {
+            // For existing sessions, we need to detect what's new
+            // Load existing messages to find the last one
+            const existingResult = await this.messageStorage.loadMessages(sessionId, { stopAtCompaction: false });
+            const existingCount = existingResult.messages.length;
+            if (messages.length > existingCount) {
+                // Append only new messages
+                const newMessages = messages.slice(existingCount);
+                await this.messageStorage.saveMessages(sessionId, newMessages);
+            }
+            // If messages.length <= existingCount, nothing to do
+            // We don't delete messages in this implementation
+        }
+        else {
+            // New session - save all messages
+            await this.messageStorage.saveMessages(sessionId, messages);
+        }
+    }
+    /**
+     * Stream messages from newest to oldest.
+     * More memory efficient for large histories.
+     *
+     * @yields InternalMessage - Messages from the session history
+     */
+    async *streamHistory(sessionId, options) {
+        const stream = this.messageStorage.streamMessages({
+            limit: options?.limit,
+            sessionId,
+            stopAtCompaction: options?.stopAtCompaction ?? true,
+        });
+        for await (const storedMessage of stream) {
+            yield this.messageStorage.toInternalMessage(storedMessage);
+        }
+    }
+}
+/**
+ * Factory function to create GranularHistoryStorage.
+ */
+export function createGranularHistoryStorage(messageStorage) {
+    return new GranularHistoryStorage(messageStorage);
+}

package/dist/infra/cipher/storage/message-storage-service.d.ts

@@ -0,0 +1,108 @@
+import type { CompactionResult, LoadMessagesResult, PruneToolOutputsOptions, SessionRecord, StoredMessage, StoredMessageWithParts, StreamMessagesOptions } from '../../../core/domain/cipher/storage/message-storage-types.js';
+import type { IKeyStorage } from '../../../core/interfaces/cipher/i-key-storage.js';
+import type { InternalMessage } from '../../../core/interfaces/cipher/message-types.js';
+/**
+ * Service for granular message and part storage.
+ *
+ * Handles the conversion between InternalMessage format and the granular
+ * StoredMessage/StoredPart format, enabling:
+ * - Streaming message loading (newest to oldest)
+ * - Selective tool output pruning
+ * - Compaction boundary markers
+ *
+ * Key structure:
+ * - ["session", sessionId] → SessionRecord
+ * - ["message", sessionId, messageId] → StoredMessage
+ * - ["part", messageId, partId] → StoredPart
+ */
+export declare class MessageStorageService {
+    private readonly keyStorage;
+    constructor(keyStorage: IKeyStorage);
+    /**
+     * Delete a session and all its messages and parts.
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Get the session record, if it exists.
+     */
+    getSession(sessionId: string): Promise<SessionRecord | undefined>;
+    /**
+     * Check if a session exists in granular format.
+     */
+    hasSession(sessionId: string): Promise<boolean>;
+    /**
+     * Insert a compaction boundary marker.
+     * Creates a special message that signals where to stop loading history.
+     */
+    insertCompactionBoundary(sessionId: string, summary: string): Promise<StoredMessage>;
+    /**
+     * List all session IDs in granular format.
+     */
+    listSessions(): Promise<string[]>;
+    /**
+     * Load messages from a session, stopping at compaction boundary.
+     * Returns messages in chronological order (oldest first).
+     */
+    loadMessages(sessionId: string, options?: {
+        stopAtCompaction?: boolean;
+    }): Promise<LoadMessagesResult>;
+    /**
+     * Prune old tool outputs by marking them as compacted.
+     * Keeps the most recent tool outputs up to the specified token limit.
+     */
+    pruneToolOutputs(options: PruneToolOutputsOptions): Promise<CompactionResult>;
+    /**
+     * Save a single message with its parts.
+     * Updates the session record to maintain linked list pointers.
+     */
+    saveMessage(sessionId: string, message: InternalMessage): Promise<StoredMessage>;
+    /**
+     * Save multiple messages in order.
+     * More efficient than calling saveMessage multiple times.
+     */
+    saveMessages(sessionId: string, messages: InternalMessage[]): Promise<StoredMessage[]>;
+    /**
+     * Create or update a session record.
+     */
+    saveSession(session: SessionRecord): Promise<void>;
+    /**
+     * Stream messages from newest to oldest using an async generator.
+     * More memory efficient for large histories.
+     *
+     * @yields StoredMessageWithParts - Messages from the session history
+     */
+    streamMessages(options: StreamMessagesOptions): AsyncGenerator<StoredMessageWithParts>;
+    /**
+     * Convert a single stored message with parts back to InternalMessage format.
+     */
+    toInternalMessage(message: StoredMessageWithParts): InternalMessage;
+    /**
+     * Convert loaded messages back to InternalMessage format.
+     */
+    toInternalMessages(messages: StoredMessageWithParts[]): InternalMessage[];
+    /**
+     * Extract parts from an InternalMessage.
+     */
+    private extractParts;
+    /**
+     * Load parts for a message.
+     */
+    private loadParts;
+    private messageKey;
+    private messagePrefix;
+    private partKey;
+    private partPrefix;
+    /**
+     * Serialize file content for storage.
+     */
+    private serializeFileContent;
+    /**
+     * Serialize image content for storage.
+     */
+    private serializeImageContent;
+    private sessionKey;
+}
+/**
+ * Factory function to create MessageStorageService.
+ */
+export declare function createMessageStorageService(keyStorage: IKeyStorage): MessageStorageService;