byterover-cli 1.8.0 → 2.1.0

package/dist/agent/infra/llm/context/context-manager.js

@@ -1,4 +1,5 @@
 import { getErrorMessage } from '../../../../server/utils/error-helpers.js';
+import { COMPACTED_TOOL_OUTPUT_PLACEHOLDER } from '../../../core/domain/storage/message-storage-types.js';
 import { NoOpLogger } from '../../../core/interfaces/i-logger.js';
 import { AsyncMutex } from './async-mutex.js';
 import { MiddleRemovalStrategy, OldestRemovalStrategy } from './compression/index.js';
@@ -30,6 +31,16 @@ export class ContextManager {
     mutex = new AsyncMutex();
     /** Callback for persistence failure events */
     onPersistenceFailed;
+    /**
+     * Whether in-memory messages have diverged from storage (e.g. after compression).
+     * When true, the next persist call falls back to full saveHistory().
+     */
+    persistDirty = false;
+    /**
+     * Number of messages already persisted to storage.
+     * Used to determine whether appendMessage() or saveHistory() should be called.
+     */
+    persistedCount = 0;
     /** Retry configuration for persistence operations */
     persistenceRetry;
     sessionId;
@@ -82,7 +93,7 @@ export class ContextManager {
         await this.mutex.withLock(async () => {
             this.messages.push(message);
             try {
-                await this.persistHistory();
+                await this.persistMessage(message);
             }
             catch (error) {
                 this.logger.error('Failed to persist history after assistant message', { error, sessionId: this.sessionId });
@@ -102,7 +113,7 @@ export class ContextManager {
         await this.mutex.withLock(async () => {
             this.messages.push(message);
             try {
-                await this.persistHistory();
+                await this.persistMessage(message);
             }
             catch (error) {
                 this.logger.error('Failed to persist history after system message', { error, sessionId: this.sessionId });
@@ -117,20 +128,22 @@ export class ContextManager {
      * @param toolName - Name of the tool being called
      * @param input - Parsed input arguments
      */
-    addToolCallPending(callId, toolName, input) {
-        const toolPart = {
-            callId,
-            state: { input, status: 'pending' },
-            toolName,
-            type: 'tool',
-        };
-        // Find the last assistant message and add the tool part
-        const lastAssistantIdx = this.findLastAssistantMessageIndex();
-        if (lastAssistantIdx === -1) {
-            this.logger.warn('No assistant message found to add tool call', { callId, sessionId: this.sessionId });
-            return;
-        }
-        this.addToolPartToMessage(lastAssistantIdx, toolPart);
+    async addToolCallPending(callId, toolName, input) {
+        await this.mutex.withLock(async () => {
+            const toolPart = {
+                callId,
+                state: { input, status: 'pending' },
+                toolName,
+                type: 'tool',
+            };
+            // Find the last assistant message and add the tool part
+            const lastAssistantIdx = this.findLastAssistantMessageIndex();
+            if (lastAssistantIdx === -1) {
+                this.logger.warn('No assistant message found to add tool call', { callId, sessionId: this.sessionId });
+                return;
+            }
+            this.addToolPartToMessage(lastAssistantIdx, toolPart);
+        });
     }
     /**
      * Add a tool result message to the conversation.
@@ -180,7 +193,7 @@ export class ContextManager {
             this.messages.push(message);
             // Persist within the lock to ensure ordering consistency
             try {
-                await this.persistHistory();
+                await this.persistMessage(message);
             }
             catch (error) {
                 this.logger.error('Failed to persist history after tool result', { error, sessionId: this.sessionId });
@@ -200,30 +213,61 @@ export class ContextManager {
             content,
             role: 'user',
         };
-        this.messages.push(message);
-        try {
-            await this.persistHistory();
-        }
-        catch (error) {
-            this.logger.error('Failed to persist history after user message', { error, sessionId: this.sessionId });
-        }
+        await this.mutex.withLock(async () => {
+            this.messages.push(message);
+            try {
+                await this.persistMessage(message);
+            }
+            catch (error) {
+                this.logger.error('Failed to persist history after user message', { error, sessionId: this.sessionId });
+            }
+        });
     }
     /**
      * Clear all messages from the conversation history.
      * Also clears persisted history if storage is enabled.
      */
     async clearHistory() {
-        this.messages = [];
-        // Clear persisted history if storage enabled
-        if (this.historyStorage) {
-            try {
-                await this.historyStorage.deleteHistory(this.sessionId);
-                // Debug logging removed for cleaner user experience
-            }
-            catch (error) {
-                this.logger.error('Failed to clear persisted history', { error, sessionId: this.sessionId });
+        await this.mutex.withLock(async () => {
+            this.messages = [];
+            this.persistedCount = 0;
+            this.persistDirty = false;
+            // Clear persisted history if storage enabled
+            if (this.historyStorage) {
+                try {
+                    await this.historyStorage.deleteHistory(this.sessionId);
+                }
+                catch (error) {
+                    this.logger.error('Failed to clear persisted history', { error, sessionId: this.sessionId });
+                }
             }
+        });
+    }
+    /**
+     * Compress messages using the strategy chain and replace in-memory state.
+     * Called by AgentLLMService when context exceeds the threshold.
+     *
+     * Delegates to compressHistoryIfNeeded() which iterates compressionStrategies
+     * (EscalatedCompression → MiddleRemoval → OldestRemoval) until the history
+     * fits within the token budget.
+     *
+     * @param systemPromptTokens - Tokens reserved for the system prompt
+     * @param targetHistoryBudget - Target token budget for message history.
+     *   When provided, overrides maxInputTokens for threshold/budget calculations
+     *   so the strategy chain compresses to the caller's target (e.g. 70% utilization)
+     *   rather than the full context window.
+     * @returns The compressed message array (same reference as this.messages)
+     */
+    async compressAndReplace(systemPromptTokens, targetHistoryBudget) {
+        const targetMaxTokens = targetHistoryBudget
+            ? targetHistoryBudget + systemPromptTokens
+            : undefined;
+        const compressed = await this.compressHistoryIfNeeded(systemPromptTokens, undefined, targetMaxTokens);
+        if (compressed !== this.messages) {
+            this.messages = compressed;
+            this.persistDirty = true;
         }
+        return this.messages;
     }
     /**
      * Compress messages by removing oldest messages until total tokens fit within the budget.
@@ -239,7 +283,10 @@ export class ContextManager {
             totalTokens -= messageTokens[toRemoveIndex];
             toRemoveIndex += 1;
         }
-        this.messages = this.messages.slice(toRemoveIndex);
+        if (toRemoveIndex > 0) {
+            this.messages = this.messages.slice(toRemoveIndex);
+            this.persistDirty = true;
+        }
     }
     /**
      * Flush any pending history writes to storage.
@@ -358,12 +405,11 @@ export class ContextManager {
             const history = await this.historyStorage.loadHistory(this.sessionId);
             if (history && history.length > 0) {
                 this.messages = history;
+                this.persistedCount = history.length;
                 this.isInitialized = true;
-                // Debug logging removed for cleaner user experience
                 return true;
             }
             this.isInitialized = true;
-            // Debug logging removed for cleaner user experience
             return false;
         }
         catch (error) {
@@ -372,6 +418,64 @@ export class ContextManager {
             return false;
         }
     }
+    /**
+     * Mark old tool outputs as compacted in-memory.
+     * Traverses messages backwards, counting user turns. After `protectedTurns`
+     * user turns, replaces tool message content with a placeholder.
+     *
+     * This is a non-destructive alternative to `compressMessage()` — it reduces
+     * token usage without removing messages from the array.
+     *
+     * @param protectedTurns - Number of recent user turns to protect (default: 2)
+     * @returns Number of tool messages compacted
+     */
+    markToolOutputsCompacted(protectedTurns = 2) {
+        let userTurnCount = 0;
+        let compactedCount = 0;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const message = this.messages[i];
+            if (message.role === 'user') {
+                userTurnCount++;
+            }
+            // Only compact tool messages beyond the protected turns
+            if (message.role === 'tool' && userTurnCount > protectedTurns) {
+                // Skip already-compacted messages
+                if (message.content === COMPACTED_TOOL_OUTPUT_PLACEHOLDER)
+                    continue;
+                this.messages[i] = {
+                    ...message,
+                    content: COMPACTED_TOOL_OUTPUT_PLACEHOLDER,
+                };
+                compactedCount++;
+            }
+        }
+        if (compactedCount > 0) {
+            this.persistDirty = true;
+        }
+        return compactedCount;
+    }
+    /**
+     * Reload messages from storage, replacing in-memory state.
+     * Used after compaction boundary creation to discard pre-boundary messages.
+     *
+     * GranularHistoryStorage.loadHistory() already stops at compaction boundaries,
+     * so this effectively trims in-memory state to only post-boundary messages.
+     */
+    async reloadFromStorage() {
+        if (!this.historyStorage)
+            return;
+        await this.mutex.withLock(async () => {
+            try {
+                const history = await this.historyStorage.loadHistory(this.sessionId);
+                this.messages = history ?? [];
+                this.persistedCount = this.messages.length;
+                this.persistDirty = false;
+            }
+            catch (error) {
+                this.logger.error('Failed to reload history from storage', { error, sessionId: this.sessionId });
+            }
+        });
+    }
     /**
      * Update a tool call's state.
      * Used for transitioning through pending → running → completed/error.
@@ -379,33 +483,35 @@ export class ContextManager {
      * @param callId - ID of the tool call to update
      * @param stateUpdate - New state
      */
-    updateToolCallState(callId, stateUpdate) {
-        // Find the tool part with this callId
-        for (let msgIdx = this.messages.length - 1; msgIdx >= 0; msgIdx--) {
-            const message = this.messages[msgIdx];
-            if (!Array.isArray(message.content))
-                continue;
-            for (let partIdx = 0; partIdx < message.content.length; partIdx++) {
-                const part = message.content[partIdx];
-                if (part.type === 'tool' && part.callId === callId) {
-                    // Update the tool part state
-                    const updatedPart = {
-                        ...part,
-                        state: stateUpdate,
-                    };
-                    // Create new content array with updated part
-                    const newContent = [...message.content];
-                    newContent[partIdx] = updatedPart;
-                    // Update the message
-                    this.messages[msgIdx] = {
-                        ...message,
-                        content: newContent,
-                    };
-                    return;
+    async updateToolCallState(callId, stateUpdate) {
+        await this.mutex.withLock(async () => {
+            // Find the tool part with this callId
+            for (let msgIdx = this.messages.length - 1; msgIdx >= 0; msgIdx--) {
+                const message = this.messages[msgIdx];
+                if (!Array.isArray(message.content))
+                    continue;
+                for (let partIdx = 0; partIdx < message.content.length; partIdx++) {
+                    const part = message.content[partIdx];
+                    if (part.type === 'tool' && part.callId === callId) {
+                        // Update the tool part state
+                        const updatedPart = {
+                            ...part,
+                            state: stateUpdate,
+                        };
+                        // Create new content array with updated part
+                        const newContent = [...message.content];
+                        newContent[partIdx] = updatedPart;
+                        // Update the message
+                        this.messages[msgIdx] = {
+                            ...message,
+                            content: newContent,
+                        };
+                        return;
+                    }
                 }
             }
-        }
-        this.logger.warn('Tool call not found for state update', { callId, sessionId: this.sessionId });
+            this.logger.warn('Tool call not found for state update', { callId, sessionId: this.sessionId });
+        });
     }
     // ==================== PRIVATE METHODS ====================
     /**
@@ -434,26 +540,30 @@ export class ContextManager {
      * Compress conversation history if needed to fit within token limits.
      *
      * This method applies compression strategies sequentially until the history
-     * fits within the available token budget (maxInputTokens - systemPromptTokens).
+     * fits within the available token budget.
      *
      * @param systemPromptTokens - Tokens used by system prompt (reserved, not compressible)
      * @param messagesToCompress - Messages to compress (defaults to all messages)
+     * @param targetMaxTokens - Override for maxInputTokens. When provided, the method
+     *   uses this as the total token ceiling (system + history) instead of this.maxInputTokens.
+     *   This allows the caller to target a lower utilization (e.g. 70%) rather than 100%.
      * @returns Compressed message history
      */
-    async compressHistoryIfNeeded(systemPromptTokens, messagesToCompress) {
+    async compressHistoryIfNeeded(systemPromptTokens, messagesToCompress, targetMaxTokens) {
+        const effectiveMaxTokens = targetMaxTokens ?? this.maxInputTokens;
         const messages = messagesToCompress ?? this.messages;
         // Calculate current token usage
         const currentHistoryTokens = countMessagesTokens(messages, this.tokenizer);
         const totalTokens = systemPromptTokens + currentHistoryTokens;
         // No compression needed
-        if (totalTokens <= this.maxInputTokens) {
+        if (totalTokens <= effectiveMaxTokens) {
             // Debug logging removed for cleaner user experience
             return messages;
         }
         // Debug logging removed for cleaner user experience
         // Calculate target token budget for history
         // Reserve space for system prompt
-        const maxHistoryTokens = this.maxInputTokens - systemPromptTokens;
+        const maxHistoryTokens = effectiveMaxTokens - systemPromptTokens;
         // Apply compression strategies sequentially
         let compressedHistory = messages;
         for (const strategy of this.compressionStrategies) {
@@ -463,7 +573,7 @@ export class ContextManager {
             // Check if we've met the token limit
             const compressedTokens = countMessagesTokens(compressedHistory, this.tokenizer);
             const newTotal = systemPromptTokens + compressedTokens;
-            if (newTotal <= this.maxInputTokens) {
+            if (newTotal <= effectiveMaxTokens) {
                 // Debug logging removed for cleaner user experience
                 break;
             }
@@ -471,12 +581,12 @@ export class ContextManager {
         // Final token count
         const finalTokens = countMessagesTokens(compressedHistory, this.tokenizer);
         const finalTotal = systemPromptTokens + finalTokens;
-        if (finalTotal > this.maxInputTokens) {
+        if (finalTotal > effectiveMaxTokens) {
             // Keep warning as it's important for users to know
             this.logger.warn('Unable to compress below token limit', {
+                effectiveMaxTokens,
                 finalTokens,
                 finalTotal,
-                maxInputTokens: this.maxInputTokens,
                 sessionId: this.sessionId,
                 systemPromptTokens,
             });
@@ -513,6 +623,43 @@ export class ContextManager {
             .join('\n');
         return this.tokenizer.countTokens(text);
     }
+    /**
+     * Execute a persistence operation with exponential backoff retry logic.
+     */
+    async executeWithRetry(operation) {
+        const { baseDelayMs, maxRetries, multiplier } = this.persistenceRetry;
+        let lastError;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                await operation();
+                return;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (attempt < maxRetries) {
+                    const delay = baseDelayMs * multiplier ** (attempt - 1);
+                    this.logger.warn(`Persistence attempt ${attempt}/${maxRetries} failed, retrying in ${delay}ms`, {
+                        error: lastError.message,
+                        sessionId: this.sessionId,
+                    });
+                    // eslint-disable-next-line no-await-in-loop
+                    await this.sleep(delay);
+                }
+            }
+        }
+        this.logger.error(`Persistence failed after ${maxRetries} attempts`, {
+            error: lastError?.message,
+            sessionId: this.sessionId,
+        });
+        if (this.onPersistenceFailed && lastError) {
+            this.onPersistenceFailed({
+                attempts: maxRetries,
+                error: lastError,
+                sessionId: this.sessionId,
+            });
+        }
+    }
     /**
      * Find the index of the last assistant message.
      *
@@ -538,7 +685,7 @@ export class ContextManager {
     }
     /**
      * Persist current conversation history to storage with retry logic.
-     * This is called automatically after each message is added.
+     * This is the full-save fallback path — saves the entire message array.
      *
      * Uses exponential backoff for retries:
      * - Attempt 1: immediate
@@ -553,43 +700,31 @@ export class ContextManager {
         if (!this.historyStorage) {
             return;
         }
-        const { baseDelayMs, maxRetries, multiplier } = this.persistenceRetry;
-        let lastError;
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            try {
-                // Store InternalMessage directly (no conversion needed)
-                // eslint-disable-next-line no-await-in-loop
-                await this.historyStorage.saveHistory(this.sessionId, this.messages);
-                return; // Success - exit early
-            }
-            catch (error) {
-                lastError = error instanceof Error ? error : new Error(String(error));
-                if (attempt < maxRetries) {
-                    // Calculate exponential backoff delay
-                    const delay = baseDelayMs * multiplier ** (attempt - 1);
-                    this.logger.warn(`Persistence attempt ${attempt}/${maxRetries} failed, retrying in ${delay}ms`, {
-                        error: lastError.message,
-                        sessionId: this.sessionId,
-                    });
-                    // Wait before next retry
-                    // eslint-disable-next-line no-await-in-loop
-                    await this.sleep(delay);
-                }
-            }
-        }
-        // All retries exhausted
-        this.logger.error(`Persistence failed after ${maxRetries} attempts`, {
-            error: lastError?.message,
-            sessionId: this.sessionId,
+        await this.executeWithRetry(async () => {
+            await this.historyStorage.saveHistory(this.sessionId, this.messages);
+            this.persistedCount = this.messages.length;
+            this.persistDirty = false;
         });
-        // Invoke callback if configured
-        if (this.onPersistenceFailed && lastError) {
-            this.onPersistenceFailed({
-                attempts: maxRetries,
-                error: lastError,
-                sessionId: this.sessionId,
-            });
+    }
+    /**
+     * Persist a single message incrementally.
+     * Falls back to full saveHistory() if in-memory state has diverged from storage.
+     *
+     * @param message - The single message to persist
+     */
+    async persistMessage(message) {
+        if (!this.historyStorage) {
+            return;
         }
+        if (this.persistDirty) {
+            // In-memory diverged from storage (e.g. after compressMessage) — full sync needed
+            await this.persistHistory();
+            return;
+        }
+        await this.executeWithRetry(async () => {
+            await this.historyStorage.appendMessage(this.sessionId, message);
+            this.persistedCount++;
+        });
     }
     /**
      * Sanitize tool result for storage.

package/dist/agent/infra/llm/context/deferred-effects.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Deferred effects pattern for ensuring side-effects (like event emissions)
+ * only execute after database operations succeed.
+ *
+ * Usage:
+ *   const effects = new DeferredEffects()
+ *   effects.defer(() => bus.emit('event', data))
+ *   await databaseOperation()
+ *   effects.flush()  // Only fires events after DB success
+ *
+ * On error:
+ *   effects.discard()  // Silently drops queued effects
+ */
+export declare class DeferredEffects {
+    private queue;
+    /**
+     * Queue a callback to execute later.
+     *
+     * @param fn - Side-effect callback to defer
+     */
+    defer(fn: () => void): void;
+    /**
+     * Discard all queued effects without executing them.
+     */
+    discard(): void;
+    /**
+     * Execute all queued effects and clear the queue.
+     */
+    flush(): void;
+}

package/dist/agent/infra/llm/context/deferred-effects.js

@@ -0,0 +1,40 @@
+/**
+ * Deferred effects pattern for ensuring side-effects (like event emissions)
+ * only execute after database operations succeed.
+ *
+ * Usage:
+ *   const effects = new DeferredEffects()
+ *   effects.defer(() => bus.emit('event', data))
+ *   await databaseOperation()
+ *   effects.flush()  // Only fires events after DB success
+ *
+ * On error:
+ *   effects.discard()  // Silently drops queued effects
+ */
+export class DeferredEffects {
+    queue = [];
+    /**
+     * Queue a callback to execute later.
+     *
+     * @param fn - Side-effect callback to defer
+     */
+    defer(fn) {
+        this.queue.push(fn);
+    }
+    /**
+     * Discard all queued effects without executing them.
+     */
+    discard() {
+        this.queue = [];
+    }
+    /**
+     * Execute all queued effects and clear the queue.
+     */
+    flush() {
+        const effects = this.queue;
+        this.queue = [];
+        for (const fn of effects) {
+            fn();
+        }
+    }
+}

package/dist/agent/infra/llm/formatters/gemini-formatter.d.ts

@@ -73,7 +73,7 @@ export declare class GeminiMessageFormatter implements IMessageFormatter<Content
  * Required for Gemini 3+ preview models.
  *
  * The "active loop" starts from the last user text message in the conversation.
- * Only the first function call in each model turn needs a thought signature.
+ * All function calls in each model turn need a thought signature.
  *
  * @param contents Array of Content objects formatted for Gemini API
  * @param model The model being used (only applies to Gemini 3+ models)

package/dist/agent/infra/llm/formatters/gemini-formatter.js

@@ -321,7 +321,7 @@ export class GeminiMessageFormatter {
  * Required for Gemini 3+ preview models.
  *
  * The "active loop" starts from the last user text message in the conversation.
- * Only the first function call in each model turn needs a thought signature.
+ * All function calls in each model turn need a thought signature.
  *
  * @param contents Array of Content objects formatted for Gemini API
  * @param model The model being used (only applies to Gemini 3+ models)
@@ -355,7 +355,7 @@ export function ensureActiveLoopHasThoughtSignatures(contents, model) {
             continue;
         }
         const newParts = [...content.parts];
-        const updatedContent = addThoughtSignatureToFirstFunctionCall(newParts, content);
+        const updatedContent = addThoughtSignatureToAllFunctionCalls(newParts, content);
         if (updatedContent) {
             newContents[i] = updatedContent;
         }
@@ -363,10 +363,11 @@ export function ensureActiveLoopHasThoughtSignatures(contents, model) {
     return newContents;
 }
 /**
- * Adds thought signature to the first function call in parts if missing.
+ * Adds thought signature to ALL function calls in parts that are missing one.
  * Returns updated content or null if no modification needed.
  */
-function addThoughtSignatureToFirstFunctionCall(parts, content) {
+function addThoughtSignatureToAllFunctionCalls(parts, content) {
+    let modified = false;
     for (let j = 0; j < parts.length; j++) {
         const part = parts[j];
         if (!part || !('functionCall' in part) || !part.functionCall) {
@@ -374,7 +375,7 @@ function addThoughtSignatureToFirstFunctionCall(parts, content) {
         }
         // Check if thoughtSignature already exists using type guard
         if (hasThoughtSignature(part) && part.thoughtSignature) {
-            return null; // Already has signature, no modification needed
+            continue;
         }
         // Add synthetic thought signature
         const partWithSignature = {
@@ -382,10 +383,13 @@ function addThoughtSignatureToFirstFunctionCall(parts, content) {
             thoughtSignature: SYNTHETIC_THOUGHT_SIGNATURE,
         };
         parts[j] = partWithSignature;
-        return {
-            ...content,
-            parts,
-        };
+        modified = true;
+    }
+    if (!modified) {
+        return null;
     }
-    return null; // No function call found
+    return {
+        ...content,
+        parts,
+    };
 }

package/dist/agent/infra/llm/generators/ai-sdk-content-generator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AI SDK Content Generator
+ *
+ * Universal IContentGenerator adapter wrapping any AI SDK LanguageModel.
+ * Replaces per-provider content generators with one unified implementation.
+ */
+import type { LanguageModel } from 'ai';
+import type { GenerateContentChunk, GenerateContentRequest, GenerateContentResponse, IContentGenerator } from '../../../core/interfaces/i-content-generator.js';
+/**
+ * Configuration for AiSdkContentGenerator.
+ */
+export interface AiSdkContentGeneratorConfig {
+    /** Characters per token ratio for token estimation */
+    charsPerToken?: number;
+    /** AI SDK LanguageModel instance */
+    model: LanguageModel;
+}
+/**
+ * Universal content generator that wraps any AI SDK LanguageModel.
+ *
+ * Implements IContentGenerator by delegating to the AI SDK's
+ * generateText() and streamText() functions. This single adapter
+ * replaces all per-provider content generators (Anthropic, OpenAI,
+ * Google, OpenRouter) with one unified implementation.
+ */
+export declare class AiSdkContentGenerator implements IContentGenerator {
+    private readonly charsPerToken;
+    private readonly model;
+    constructor(config: AiSdkContentGeneratorConfig);
+    estimateTokensSync(content: string): number;
+    generateContent(request: GenerateContentRequest): Promise<GenerateContentResponse>;
+    generateContentStream(request: GenerateContentRequest): AsyncGenerator<GenerateContentChunk>;
+}