byterover-cli 1.1.0 → 1.2.0

package/README.md

@@ -31,6 +31,7 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
       - Debian/Ubuntu: `sudo apt-get install libsecret-1-dev`
       - Red Hat-based: `sudo yum install libsecret-devel`
       - Arch Linux: `sudo pacman -S libsecret`
+- **WSL (Windows Subsystem for Linux)**: Supported with automatic file-based token storage fallback when keychain is unavailable
 
 ### Install globally via npm
 
@@ -99,7 +100,9 @@ The terminal UI includes:
 - **Command Completion**: Type `/` to see available commands with auto-completion
 - **Activity Log**: Real-time task status and execution progress
 - **Streaming Output**: Live responses from AI-powered operations
-- **File References**: Type `@` in curate mode to browse and attach files
+- **File References**: Type `@` in curate mode to browse and attach files (supports PDF)
+- **Dynamic Domains**: Automatically creates new knowledge domains as your context tree grows
+- **Session Persistence**: Sessions auto-resume after restart
 
 ### Using Commands
 
@@ -141,9 +144,10 @@ Use `/connectors` to manage integrations with your AI coding agents:
 /connectors
 ```
 
-ByteRover supports two connector types:
+ByteRover supports three connector types:
 - **Hook integration** (Claude Code): Direct injection via IDE settings for seamless integration
 - **Rules-based** (all agents): Generates agent-specific rule files (e.g., `CLAUDE.md`, `.cursorrules`) that instruct the agent how to read from and contribute to your context tree
+- **MCP integration** (Model Context Protocol): Exposes `brv-query` and `brv-curate` as MCP tools that AI agents can call directly
 
 ## Slash Commands Reference
 
@@ -159,7 +163,7 @@ ByteRover supports two connector types:
 ```
 /curate                                    # Interactive mode
 /curate "Auth uses JWT tokens"             # Autonomous mode with text
-/curate "API docs" @src/api.ts @README.md  # With file references (max 5)
+/curate "API docs" @src/api.ts @README.md  # With file references (max 5, supports PDF)
 ```
 
 **Query example:**
@@ -219,7 +223,7 @@ ByteRover supports two connector types:
 **Options:**
 - `-y, --yes`: Skip confirmation prompt
 
-**Note:** This command does NOT affect the context tree—it only clears the conversation history and starts a new session.
+**Note:** Sessions are stateful and auto-resume after restart. Use `/new` to start fresh—this clears conversation history but does NOT affect the context tree.
 
 ### Project Setup
 

package/dist/commands/mcp.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+/**
+ * MCP command - starts the MCP server for coding agent integration.
+ *
+ * This command is spawned by coding agents (Claude Code, Cursor, Windsurf)
+ * and connects to a running brv instance via Socket.IO.
+ */
+export default class Mcp extends Command {
+    static description: string;
+    static examples: string[];
+    static hidden: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/mcp.js

@@ -0,0 +1,61 @@
+import { Command } from '@oclif/core';
+import { NoInstanceRunningError } from '../core/domain/errors/connection-error.js';
+import { ByteRoverMcpServer } from '../infra/mcp/index.js';
+/**
+ * MCP command - starts the MCP server for coding agent integration.
+ *
+ * This command is spawned by coding agents (Claude Code, Cursor, Windsurf)
+ * and connects to a running brv instance via Socket.IO.
+ */
+export default class Mcp extends Command {
+    static description = `Start MCP server for coding agent integration
+
+Connects to a running brv instance via Socket.IO.
+Requires: brv running in another terminal.
+
+Exposes tools:
+- brv-query: Query the context tree
+- brv-curate: Curate context to the tree`;
+    static examples = [
+        '# Start MCP server (typically called by coding agents)',
+        '<%= config.bin %> <%= command.id %>',
+    ];
+    static hidden = true; // Called by agents, not users directly
+    async run() {
+        try {
+            const server = new ByteRoverMcpServer({
+                version: this.config.version,
+                workingDirectory: process.cwd(),
+            });
+            // Graceful shutdown
+            const cleanup = async () => {
+                await server.stop();
+                // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+                process.exit(0);
+            };
+            process.on('SIGTERM', cleanup);
+            process.on('SIGINT', cleanup);
+            await server.start();
+            // Keep the process alive - MCP server runs on stdio
+            // The process will be terminated by SIGTERM/SIGINT or when the parent process closes stdin
+            await new Promise((resolve) => {
+                process.stdin.on('close', () => {
+                    resolve();
+                });
+                process.stdin.on('end', () => {
+                    resolve();
+                });
+            });
+            await server.stop();
+        }
+        catch (error) {
+            if (error instanceof NoInstanceRunningError) {
+                this.logToStderr('Error: No ByteRover instance running.');
+                this.logToStderr('Start one with: brv');
+                // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+                process.exit(1);
+            }
+            throw error;
+        }
+    }
+}

package/dist/core/domain/cipher/agent-events/types.d.ts

@@ -497,11 +497,13 @@ export interface SessionEventMap {
      * Emitted when a chunk of content is received (streaming).
      * @property {string} content - Content of the chunk
      * @property {boolean} [isComplete] - Whether this is the final chunk
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {'reasoning' | 'text'} type - Type of chunk (text or reasoning)
      */
     'llmservice:chunk': {
         content: string;
         isComplete?: boolean;
+        taskId?: string;
         type: 'reasoning' | 'text';
     };
     /**
@@ -509,32 +511,38 @@ export interface SessionEventMap {
      * @property {number} compressedTokens - Token count after compression
      * @property {number} originalTokens - Token count before compression
      * @property {'middle_removal' | 'oldest_removal' | 'summary'} strategy - Compression strategy used
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:contextCompressed': {
         compressedTokens: number;
         originalTokens: number;
         strategy: 'middle_removal' | 'oldest_removal' | 'summary';
+        taskId?: string;
     };
     /**
      * Emitted when context is approaching the token limit.
      * @property {number} currentTokens - Current token count
      * @property {number} maxTokens - Maximum allowed tokens
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {number} utilizationPercent - Percentage of context used (0-100)
      */
     'llmservice:contextOverflow': {
         currentTokens: number;
         maxTokens: number;
+        taskId?: string;
         utilizationPercent: number;
     };
     /**
      * Emitted when old tool outputs are pruned to save context space.
      * @property {number} pruneCount - Number of tool outputs pruned
      * @property {'manual' | 'overflow'} reason - Why pruning was triggered
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {number} tokensSaved - Estimated tokens saved
      */
     'llmservice:contextPruned': {
         pruneCount: number;
         reason: 'manual' | 'overflow';
+        taskId?: string;
         tokensSaved: number;
     };
     /**
@@ -543,32 +551,38 @@ export interface SessionEventMap {
      * @property {Record<string, unknown>} args - Arguments that were repeated
      * @property {'exact_repeat' | 'oscillation'} loopType - Type of loop detected
      * @property {number} repeatCount - Number of times the pattern repeated
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the tool involved in the loop
      */
     'llmservice:doomLoopDetected': {
         args: Record<string, unknown>;
         loopType: 'exact_repeat' | 'oscillation';
         repeatCount: number;
+        taskId?: string;
         toolName: string;
     };
     /**
      * Emitted when an error occurs during LLM service operation.
      * @property {string} [code] - Error code (optional)
      * @property {string} error - Error message
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:error': {
         code?: string;
         error: string;
+        taskId?: string;
     };
     /**
      * Emitted when tool output is truncated due to size.
      * @property {number} originalLength - Original output length before truncation
      * @property {string} savedToFile - Path to file where full output was saved
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the tool that produced the output
      */
     'llmservice:outputTruncated': {
         originalLength: number;
         savedToFile: string;
+        taskId?: string;
         toolName: string;
     };
     /**
@@ -578,6 +592,7 @@ export interface SessionEventMap {
      * @property {boolean} [partial] - Whether this is a partial response (e.g., max iterations reached)
      * @property {string} [provider] - LLM provider name
      * @property {string} [reasoning] - Internal reasoning (if available)
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {TokenUsage} [tokenUsage] - Token usage statistics
      */
     'llmservice:response': {
@@ -586,30 +601,38 @@ export interface SessionEventMap {
         partial?: boolean;
         provider?: string;
         reasoning?: string;
+        taskId?: string;
         tokenUsage?: TokenUsage;
     };
     /**
      * Emitted when LLM service starts thinking/processing.
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
-    'llmservice:thinking': void;
+    'llmservice:thinking': void | {
+        taskId?: string;
+    };
     /**
      * Emitted when LLM generates a thought (Gemini models only).
      * @property {string} description - Detailed thought description
      * @property {string} subject - Brief thought subject
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:thought': {
         description: string;
         subject: string;
+        taskId?: string;
     };
     /**
      * Emitted when LLM requests a tool call.
      * @property {Record<string, unknown>} args - Arguments for the tool
      * @property {string} [callId] - Unique identifier for this tool call
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the tool to execute
      */
     'llmservice:toolCall': {
         args: Record<string, unknown>;
         callId?: string;
+        taskId?: string;
         toolName: string;
     };
     /**
@@ -617,11 +640,13 @@ export interface SessionEventMap {
      * Allows tools to push real-time updates (e.g., bash output streaming).
      * @property {string} callId - Tool call identifier
      * @property {Record<string, unknown>} metadata - The metadata update
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the tool streaming metadata
      */
     'llmservice:toolMetadata': {
         callId: string;
         metadata: Record<string, unknown>;
+        taskId?: string;
         toolName: string;
     };
     /**
@@ -632,6 +657,7 @@ export interface SessionEventMap {
      * @property {Record<string, unknown>} [metadata] - Execution metadata (duration, tokens, etc.)
      * @property {unknown} [result] - Tool execution result
      * @property {boolean} success - Whether execution succeeded
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {string} toolName - Name of the executed tool
      */
     'llmservice:toolResult': {
@@ -641,32 +667,39 @@ export interface SessionEventMap {
         metadata?: Record<string, unknown>;
         result?: unknown;
         success: boolean;
+        taskId?: string;
         toolName: string;
     };
     /**
      * Emitted when LLM receives unsupported input.
      * @property {string} reason - Reason why input is unsupported
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:unsupportedInput': {
         reason: string;
+        taskId?: string;
     };
     /**
      * Emitted when LLM service encounters a warning (e.g., max iterations reached).
      * @property {string} message - Warning message
      * @property {string} [model] - Model identifier
      * @property {string} [provider] - LLM provider name
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'llmservice:warning': {
         message: string;
         model?: string;
         provider?: string;
+        taskId?: string;
     };
     /**
      * Emitted when queued messages are dequeued for processing.
      * @property {number} count - Number of messages that were dequeued
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'message:dequeued': {
         count: number;
+        taskId?: string;
     };
     /**
      * Emitted when a message is queued because session is busy.
@@ -675,6 +708,7 @@ export interface SessionEventMap {
      * @property {string} message.content - Message text content
      * @property {number} message.queuedAt - Timestamp when queued
      * @property {number} position - Position in the queue (1-based)
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'message:queued': {
         message: {
@@ -683,6 +717,7 @@ export interface SessionEventMap {
             queuedAt: number;
         };
         position: number;
+        taskId?: string;
     };
     /**
      * Emitted when a session run completes (streaming API lifecycle event).
@@ -690,20 +725,24 @@ export interface SessionEventMap {
      * @property {Error} [error] - Error if terminated due to error
      * @property {'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout'} finishReason - Why execution terminated
      * @property {number} stepCount - Number of agentic steps completed
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'run:complete': {
         durationMs: number;
         error?: Error;
         finishReason: 'cancelled' | 'error' | 'max-iterations' | 'stop' | 'timeout';
         stepCount: number;
+        taskId?: string;
     };
     /**
      * Emitted when session status changes.
      * Tracks the lifecycle state of a session (idle, busy, retry, waiting).
      * @property {SessionStatusType} status - The new session status
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'session:statusChanged': {
         status: SessionStatusType;
+        taskId?: string;
     };
     /**
      * Emitted when an execution step finishes.
@@ -711,20 +750,24 @@ export interface SessionEventMap {
      * @property {number} cost - Cost in dollars for this step
      * @property {'max_tokens' | 'stop' | 'tool_calls'} finishReason - Why step finished
      * @property {number} stepIndex - Step index (0-based)
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      * @property {StepTokenUsage} tokens - Token usage for this step
      */
     'step:finished': {
         cost: number;
         finishReason: 'max_tokens' | 'stop' | 'tool_calls';
         stepIndex: number;
+        taskId?: string;
         tokens: StepTokenUsage;
     };
     /**
      * Emitted when an execution step starts.
      * @property {number} stepIndex - Step index (0-based)
+     * @property {string} [taskId] - Optional task ID for concurrent task isolation
      */
     'step:started': {
         stepIndex: number;
+        taskId?: string;
     };
 }
 /**

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

@@ -26,22 +26,76 @@ export const AGENT_VALUES = [
  * Defines which connectors each agent supports and which is the default.
  */
 export const AGENT_CONNECTOR_CONFIG = {
-    Amp: { default: 'rules', supported: ['rules'] },
-    'Augment Code': { default: 'rules', supported: ['rules'] },
-    'Claude Code': { default: 'hook', supported: ['rules', 'hook'] },
-    Cline: { default: 'rules', supported: ['rules'] },
-    Codex: { default: 'rules', supported: ['rules'] },
-    Cursor: { default: 'rules', supported: ['rules'] },
-    'Gemini CLI': { default: 'rules', supported: ['rules'] },
-    'Github Copilot': { default: 'rules', supported: ['rules'] },
-    Junie: { default: 'rules', supported: ['rules'] },
-    'Kilo Code': { default: 'rules', supported: ['rules'] },
-    Kiro: { default: 'rules', supported: ['rules'] },
-    Qoder: { default: 'rules', supported: ['rules'] },
-    'Qwen Code': { default: 'rules', supported: ['rules'] },
-    'Roo Code': { default: 'rules', supported: ['rules'] },
-    'Trae.ai': { default: 'rules', supported: ['rules'] },
-    Warp: { default: 'rules', supported: ['rules'] },
-    Windsurf: { default: 'rules', supported: ['rules'] },
-    Zed: { default: 'rules', supported: ['rules'] },
+    Amp: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Augment Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Claude Code': {
+        default: 'hook',
+        supported: ['rules', 'hook', 'mcp'],
+    },
+    Cline: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Codex: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Cursor: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Gemini CLI': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Github Copilot': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Junie: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Kilo Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Kiro: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Qoder: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Qwen Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Roo Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Trae.ai': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Warp: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Windsurf: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Zed: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
 };

package/dist/core/domain/entities/connector-type.d.ts

@@ -4,6 +4,7 @@
  *
  * - 'rules': Agent reads instructions from a rule file (e.g., CLAUDE.md)
  * - 'hook': Instructions are injected on each prompt via agent hooks
+ * - 'mcp': Agent uses mcp tools to interact with brv
  */
-export declare const CONNECTOR_TYPES: readonly ["rules", "hook"];
+export declare const CONNECTOR_TYPES: readonly ["rules", "hook", "mcp"];
 export type ConnectorType = (typeof CONNECTOR_TYPES)[number];

package/dist/core/domain/entities/connector-type.js

@@ -4,5 +4,6 @@
  *
  * - 'rules': Agent reads instructions from a rule file (e.g., CLAUDE.md)
  * - 'hook': Instructions are injected on each prompt via agent hooks
+ * - 'mcp': Agent uses mcp tools to interact with brv
  */
-export const CONNECTOR_TYPES = ['rules', 'hook'];
+export const CONNECTOR_TYPES = ['rules', 'hook', 'mcp'];

package/dist/core/interfaces/connectors/connector-types.d.ts

@@ -1,4 +1,13 @@
 import type { ConnectorType } from '../../domain/entities/connector-type.js';
+/**
+ * Instructions for manual MCP setup when automatic configuration is not possible.
+ */
+export type ManualInstallInstructions = {
+    /** The config content to copy (JSON or TOML formatted) */
+    configContent: string;
+    /** Guide URL or step-by-step instructions */
+    guide: string;
+};
 /**
  * Result of a connector installation operation.
  */
@@ -7,8 +16,12 @@ export type ConnectorInstallResult = {
     alreadyInstalled: boolean;
     /** Path to the configuration/rule file */
     configPath: string;
+    /** Instructions for manual setup (present when requiresManualSetup is true) */
+    manualInstructions?: ManualInstallInstructions;
     /** Human-readable message describing the result */
     message: string;
+    /** Whether this requires manual setup by the user */
+    requiresManualSetup?: boolean;
     /** Whether the installation was successful */
     success: boolean;
 };

package/dist/core/interfaces/i-mcp-config-writer.d.ts

@@ -0,0 +1,40 @@
+import type { McpServerConfig } from '../../infra/connectors/mcp/mcp-connector-config.js';
+/**
+ * Result of checking if MCP config exists.
+ */
+export type McpConfigExistsResult = {
+    /** Whether the config file exists */
+    fileExists: boolean;
+    /** Whether the BRV MCP server entry exists in the config */
+    serverExists: boolean;
+};
+/**
+ * Interface for writing MCP server configurations to agent config files.
+ * Different implementations handle different file formats (JSON, TOML, etc.).
+ */
+export interface IMcpConfigWriter {
+    /**
+     * Check if the config file and BRV server entry exist.
+     *
+     * @param filePath - Absolute path to the config file
+     * @returns Object indicating file and server existence
+     */
+    exists(filePath: string): Promise<McpConfigExistsResult>;
+    /**
+     * Remove the BRV MCP server entry from the config file.
+     * Does not delete the file, only removes the server entry.
+     *
+     * @param filePath - Absolute path to the config file
+     * @returns True if the server was removed, false if it didn't exist
+     */
+    remove(filePath: string): Promise<boolean>;
+    /**
+     * Write the MCP server configuration to the config file.
+     * Creates the file if it doesn't exist.
+     * Preserves existing configuration.
+     *
+     * @param filePath - Absolute path to the config file
+     * @param serverConfig - The MCP server configuration to write
+     */
+    write(filePath: string, serverConfig: McpServerConfig): Promise<void>;
+}

package/dist/core/interfaces/i-mcp-config-writer.js

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

package/dist/core/interfaces/i-rule-template-service.d.ts

@@ -1,13 +1,15 @@
 import { Agent } from '../domain/entities/agent.js';
+import { ConnectorType } from '../domain/entities/connector-type.js';
 /**
  * Interface for rule template service operations.
  */
 export interface IRuleTemplateService {
     /**
-     * Generates rule content based on the provided agent.
+     * Generates rule content based on the provided agent and connector type.
      *
      * @param agent The agent for which to generate the rule content.
+     * @param type The connector type (rules or mcp). Defaults to 'rules'.
      * @returns Promise resolving to the generated rule content.
      */
-    generateRuleContent: (agent: Agent) => Promise<string>;
+    generateRuleContent: (agent: Agent, type: ConnectorType) => Promise<string>;
 }

package/dist/core/interfaces/transport/i-transport-client.d.ts

@@ -54,6 +54,13 @@ export interface ITransportClient {
      * Returns the current connection state.
      */
     getState: () => ConnectionState;
+    /**
+     * Checks if the socket is actually connected and responsive.
+     * Verifies bidirectional communication by sending a ping and waiting for response.
+     * @param timeoutMs - Timeout in milliseconds (default: 2000)
+     * @returns true if socket is connected and responsive, false otherwise
+     */
+    isConnected: (timeoutMs?: number) => Promise<boolean>;
     /**
      * Joins a room for targeted broadcasts.
      * @param room - The room identifier to join

package/dist/infra/cipher/agent/cipher-agent.d.ts

@@ -158,6 +158,14 @@ export declare class CipherAgent extends BaseAgent implements ICipherAgent {
      * @returns AsyncIterator that yields StreamingEvent objects
      */
     stream(input: string, options?: StreamOptions): Promise<AsyncIterableIterator<StreamingEvent>>;
+    /**
+     * Switch the default session to a different session ID.
+     * The session must already exist (created via createSession).
+     *
+     * @param sessionId - The session ID to switch to
+     * @throws Error if session does not exist
+     */
+    switchDefaultSession(sessionId: string): void;
     private getHistoryStorageInternal;
     private getSessionIdInternal;
     private getSessionManagerInternal;

package/dist/infra/cipher/agent/cipher-agent.js

@@ -520,6 +520,22 @@ export class CipherAgent extends BaseAgent {
         };
         return iterator;
     }
+    /**
+     * Switch the default session to a different session ID.
+     * The session must already exist (created via createSession).
+     *
+     * @param sessionId - The session ID to switch to
+     * @throws Error if session does not exist
+     */
+    switchDefaultSession(sessionId) {
+        this.ensureStarted();
+        // Verify the session exists
+        const session = this.getSessionManagerInternal().getSession(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} does not exist. Create it first with createSession().`);
+        }
+        this._sessionId = sessionId;
+    }
     // === Private Helpers (alphabetical order) ===
     getHistoryStorageInternal() {
         const storage = this.services?.historyStorage;

package/dist/infra/cipher/llm/context/context-manager.d.ts

@@ -178,6 +178,14 @@ export declare class ContextManager<T> {
      * Also clears persisted history if storage is enabled.
      */
     clearHistory(): Promise<void>;
+    /**
+     * Compress messages by removing oldest messages until total tokens fit within the budget.
+     * This directly modifies the internal messages array by slicing from the beginning.
+     *
+     * @param maxTokens - Maximum token budget allowed
+     * @param messageTokens - Array of token counts corresponding to each message
+     */
+    compressMessage(maxTokens: number, messageTokens: number[]): void;
     /**
      * Flush any pending history writes to storage.
      * Provides explicit durability guarantee - ensures all messages