byterover-cli 1.1.0 → 1.2.1

package/dist/infra/mcp/mcp-server.js

@@ -0,0 +1,178 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createTransportClientFactory } from '../transport/transport-client-factory.js';
+import { registerBrvCurateTool, registerBrvQueryTool } from './tools/index.js';
+/** Reconnection configuration */
+const RECONNECT_DELAY_MS = 1000;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+const RECONNECT_BACKOFF_MULTIPLIER = 1.5;
+/**
+ * ByteRover MCP Server.
+ *
+ * Exposes brv-query and brv-curate as MCP tools for coding agents.
+ * Connects to a running brv instance via Socket.IO transport.
+ *
+ * Architecture:
+ * - Coding agent spawns `brv mcp` process
+ * - MCP server connects to running brv instance via Socket.IO
+ * - MCP tools create tasks via transport
+ * - Tasks are executed by the existing agent process
+ */
+export class ByteRoverMcpServer {
+    client;
+    config;
+    currentReconnectDelay = RECONNECT_DELAY_MS;
+    isReconnecting = false;
+    reconnectTimer;
+    server;
+    transport;
+    constructor(config) {
+        this.config = config;
+        this.server = new McpServer({
+            name: 'byterover',
+            version: config.version,
+        });
+        // Register tools with lazy client getter
+        // Client will be set when start() is called
+        registerBrvQueryTool(this.server, () => this.client, () => this.config.workingDirectory);
+        registerBrvCurateTool(this.server, () => this.client, () => this.config.workingDirectory);
+    }
+    /**
+     * Starts the MCP server.
+     *
+     * 1. Connects to running brv instance via Socket.IO
+     * 2. Starts MCP server with stdio transport
+     *
+     * @throws NoInstanceRunningError - No brv instance is running
+     * @throws ConnectionFailedError - Failed to connect to brv instance
+     */
+    async start() {
+        this.log('Starting MCP server...');
+        this.log(`Working directory: ${this.config.workingDirectory}`);
+        // Connect to running brv instance
+        const factory = createTransportClientFactory();
+        this.log('Connecting to brv instance...');
+        let connectionResult;
+        try {
+            connectionResult = await factory.connect(this.config.workingDirectory);
+        }
+        catch (error) {
+            this.log(`Connection failed: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+        const { client, projectRoot } = connectionResult;
+        this.client = client;
+        this.log(`Connected to brv instance at ${projectRoot}`);
+        this.log(`Client ID: ${client.getClientId()}`);
+        this.log(`Initial connection state: ${client.getState()}`);
+        // Monitor connection state changes and handle reconnection
+        this.setupStateChangeHandler(client);
+        // Start MCP server with stdio transport
+        this.transport = new StdioServerTransport();
+        await this.server.connect(this.transport);
+        this.log('MCP server started and ready for tool calls');
+        // Log client state periodically to debug connection issues
+        setInterval(() => {
+            if (this.client) {
+                this.log(`[heartbeat] Client state: ${this.client.getState()}, ID: ${this.client.getClientId()}`);
+            }
+            else {
+                this.log('[heartbeat] Client is undefined!');
+            }
+        }, 10_000);
+    }
+    /**
+     * Stops the MCP server.
+     *
+     * Disconnects from the brv instance.
+     */
+    async stop() {
+        // Clear any pending reconnection timer
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        this.isReconnecting = false;
+        if (this.client) {
+            await this.client.disconnect();
+            this.client = undefined;
+        }
+    }
+    /**
+     * Attempts to reconnect to the brv instance.
+     * Uses exponential backoff for retry delays.
+     */
+    async attemptReconnect() {
+        if (this.isReconnecting) {
+            this.log('Reconnection already in progress, skipping...');
+            return;
+        }
+        this.isReconnecting = true;
+        this.log(`Attempting to reconnect in ${this.currentReconnectDelay}ms...`);
+        this.reconnectTimer = setTimeout(async () => {
+            try {
+                const factory = createTransportClientFactory();
+                const result = await factory.connect(this.config.workingDirectory);
+                // Disconnect old client if it exists
+                if (this.client) {
+                    try {
+                        await this.client.disconnect();
+                    }
+                    catch {
+                        // Ignore disconnect errors on old client
+                    }
+                }
+                this.client = result.client;
+                this.log(`Reconnected successfully! Client ID: ${result.client.getClientId()}`);
+                // Reset backoff delay on successful connection
+                this.currentReconnectDelay = RECONNECT_DELAY_MS;
+                this.isReconnecting = false;
+                // Set up state change handler for the new client
+                this.setupStateChangeHandler(result.client);
+            }
+            catch (error) {
+                this.log(`Reconnection failed: ${error instanceof Error ? error.message : String(error)}`);
+                // Increase delay with exponential backoff (capped at max)
+                this.currentReconnectDelay = Math.min(this.currentReconnectDelay * RECONNECT_BACKOFF_MULTIPLIER, RECONNECT_MAX_DELAY_MS);
+                this.isReconnecting = false;
+                // Schedule next reconnection attempt
+                this.attemptReconnect();
+            }
+        }, this.currentReconnectDelay);
+    }
+    /**
+     * Log to stderr (stdout is reserved for MCP protocol).
+     */
+    log(msg) {
+        process.stderr.write(`[brv-mcp] ${msg}\n`);
+    }
+    /**
+     * Sets up the state change handler for a client.
+     * Handles disconnection by triggering auto-reconnect.
+     */
+    setupStateChangeHandler(client) {
+        client.onStateChange((state) => {
+            const timestamp = new Date().toISOString();
+            this.log(`[${timestamp}] Connection state changed: ${state}`);
+            switch (state) {
+                case 'connected': {
+                    this.log(`[${timestamp}] Connected to brv instance.`);
+                    // Reset backoff delay on successful connection
+                    this.currentReconnectDelay = RECONNECT_DELAY_MS;
+                    this.isReconnecting = false;
+                    break;
+                }
+                case 'disconnected': {
+                    this.log(`[${timestamp}] Socket disconnected from brv instance. Initiating reconnection...`);
+                    // Trigger auto-reconnect
+                    this.attemptReconnect();
+                    break;
+                }
+                case 'reconnecting': {
+                    this.log(`[${timestamp}] Socket.IO attempting to reconnect...`);
+                    break;
+                }
+            }
+        });
+    }
+}

package/dist/infra/mcp/tools/brv-curate-tool.d.ts

@@ -0,0 +1,23 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { ITransportClient } from '../../../core/interfaces/transport/index.js';
+export declare const BrvCurateInputSchema: z.ZodObject<{
+    context: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    context: string;
+    files?: string[] | undefined;
+}, {
+    context: string;
+    files?: string[] | undefined;
+}>;
+/**
+ * Registers the brv-curate tool with the MCP server.
+ *
+ * This tool allows coding agents to store context to the ByteRover context tree.
+ * Use it to save patterns, architectural decisions, error solutions, or insights.
+ *
+ * Uses fire-and-forget pattern: returns immediately after queueing the task.
+ * The curation is processed asynchronously by the ByteRover agent.
+ */
+export declare function registerBrvCurateTool(server: McpServer, getClient: () => ITransportClient | undefined, getWorkingDirectory: () => string): void;

package/dist/infra/mcp/tools/brv-curate-tool.js

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+export const BrvCurateInputSchema = z.object({
+    context: z.string().describe('Knowledge to store: patterns, decisions, errors, or insights about the codebase'),
+    files: z
+        .array(z.string())
+        .max(5)
+        .optional()
+        .describe('Optional file paths with critical context to include (max 5 files)'),
+});
+/**
+ * Registers the brv-curate tool with the MCP server.
+ *
+ * This tool allows coding agents to store context to the ByteRover context tree.
+ * Use it to save patterns, architectural decisions, error solutions, or insights.
+ *
+ * Uses fire-and-forget pattern: returns immediately after queueing the task.
+ * The curation is processed asynchronously by the ByteRover agent.
+ */
+export function registerBrvCurateTool(server, getClient, getWorkingDirectory) {
+    server.registerTool('brv-curate', {
+        description: 'Store context to the ByteRover context tree. Save patterns, decisions, or insights.',
+        inputSchema: BrvCurateInputSchema,
+        title: 'ByteRover Curate',
+    }, async ({ context, files }) => {
+        const client = getClient();
+        if (!client) {
+            return {
+                content: [{ text: 'Error: Not connected to ByteRover instance. Run "brv" first.', type: 'text' }],
+                isError: true,
+            };
+        }
+        // Check connection state before making request
+        const state = client.getState();
+        if (state !== 'connected') {
+            return {
+                content: [{ text: `Error: Socket not connected. Current state: ${state}. Ensure "brv" is running.`, type: 'text' }],
+                isError: true,
+            };
+        }
+        try {
+            const taskId = randomUUID();
+            // Create task via transport (same pattern as brv curate command)
+            await client.request('task:create', {
+                clientCwd: getWorkingDirectory(),
+                content: context,
+                taskId,
+                type: 'curate',
+                ...(files?.length ? { files } : {}),
+            });
+            // Fire-and-forget: return immediately after task is queued
+            // Curation is processed asynchronously by the ByteRover agent
+            return {
+                content: [{
+                        text: `✓ Context queued for curation (taskId: ${taskId}). The curation will be processed asynchronously.`,
+                        type: 'text',
+                    }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ text: `Error: ${message}`, type: 'text' }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/infra/mcp/tools/brv-query-tool.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { ITransportClient } from '../../../core/interfaces/transport/index.js';
+export declare const BrvQueryInputSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+/**
+ * Registers the brv-query tool with the MCP server.
+ *
+ * This tool allows coding agents to query the ByteRover context tree
+ * for patterns, decisions, implementation details, or any stored knowledge.
+ */
+export declare function registerBrvQueryTool(server: McpServer, getClient: () => ITransportClient | undefined, getWorkingDirectory: () => string): void;

package/dist/infra/mcp/tools/brv-query-tool.js

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { waitForTaskResult } from './task-result-waiter.js';
+export const BrvQueryInputSchema = z.object({
+    query: z.string().describe('Natural language question about the codebase or project'),
+});
+/**
+ * Registers the brv-query tool with the MCP server.
+ *
+ * This tool allows coding agents to query the ByteRover context tree
+ * for patterns, decisions, implementation details, or any stored knowledge.
+ */
+export function registerBrvQueryTool(server, getClient, getWorkingDirectory) {
+    server.registerTool('brv-query', {
+        description: 'Query the ByteRover context tree for patterns, decisions, or implementation details.',
+        inputSchema: BrvQueryInputSchema,
+        title: 'ByteRover Query',
+    }, async ({ query }) => {
+        const timestamp = new Date().toISOString();
+        process.stderr.write(`[brv-mcp] [${timestamp}] brv-query tool called with query: ${query.slice(0, 50)}...\n`);
+        const client = getClient();
+        process.stderr.write(`[brv-mcp] [${timestamp}] Client exists: ${client}\n`);
+        if (!client) {
+            process.stderr.write(`[brv-mcp] [${timestamp}] ERROR: Client is undefined\n`);
+            return {
+                content: [{ text: 'Error: Not connected to ByteRover instance. Run "brv" first.', type: 'text' }],
+                isError: true,
+            };
+        }
+        // Check connection state before making request
+        const state = client.getState();
+        process.stderr.write(`[brv-mcp] [${timestamp}] Client state: ${state}, Client ID: ${client.getClientId()}\n`);
+        if (state !== 'connected') {
+            process.stderr.write(`[brv-mcp] [${timestamp}] ERROR: Socket not connected\n`);
+            return {
+                content: [
+                    {
+                        text: `Error: Socket not connected. Current state: ${state}. Ensure "brv" is running.`,
+                        type: 'text',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const taskId = randomUUID();
+            // Create task via transport (same pattern as brv query command)
+            await client.request('task:create', {
+                clientCwd: getWorkingDirectory(),
+                content: query,
+                taskId,
+                type: 'query',
+            });
+            // Wait for task completion and return result
+            const result = await waitForTaskResult(client, taskId);
+            return {
+                content: [{ text: result, type: 'text' }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ text: `Error: ${message}`, type: 'text' }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/infra/mcp/tools/index.d.ts

@@ -0,0 +1,3 @@
+export { registerBrvCurateTool } from './brv-curate-tool.js';
+export { registerBrvQueryTool } from './brv-query-tool.js';
+export { waitForTaskResult } from './task-result-waiter.js';

package/dist/infra/mcp/tools/index.js

@@ -0,0 +1,3 @@
+export { registerBrvCurateTool } from './brv-curate-tool.js';
+export { registerBrvQueryTool } from './brv-query-tool.js';
+export { waitForTaskResult } from './task-result-waiter.js';

package/dist/infra/mcp/tools/task-result-waiter.d.ts

@@ -0,0 +1,30 @@
+import type { ITransportClient } from '../../../core/interfaces/transport/index.js';
+export interface TaskCompletedPayload {
+    result: string;
+    taskId: string;
+}
+export interface TaskErrorPayload {
+    error: {
+        code?: string;
+        details?: Record<string, unknown>;
+        message: string;
+        name: string;
+    };
+    taskId: string;
+}
+export interface LlmResponsePayload {
+    content: string;
+    taskId: string;
+}
+/**
+ * Waits for a task to complete and returns the result.
+ *
+ * Unlike the fire-and-forget pattern used by `brv curate`, MCP tools need
+ * to wait for the task to finish and return the result to the coding agent.
+ *
+ * This function listens for:
+ * - llmservice:response: Captures the LLM's text response
+ * - task:completed: Task finished successfully
+ * - task:error: Task failed with an error
+ */
+export declare function waitForTaskResult(client: ITransportClient, taskId: string, timeoutMs?: number): Promise<string>;

package/dist/infra/mcp/tools/task-result-waiter.js

@@ -0,0 +1,56 @@
+/**
+ * Waits for a task to complete and returns the result.
+ *
+ * Unlike the fire-and-forget pattern used by `brv curate`, MCP tools need
+ * to wait for the task to finish and return the result to the coding agent.
+ *
+ * This function listens for:
+ * - llmservice:response: Captures the LLM's text response
+ * - task:completed: Task finished successfully
+ * - task:error: Task failed with an error
+ */
+export async function waitForTaskResult(client, taskId, timeoutMs = 120_000) {
+    return new Promise((resolve, reject) => {
+        let result = '';
+        let completed = false;
+        const unsubscribers = [];
+        const cleanup = () => {
+            clearTimeout(timeout);
+            for (const unsub of unsubscribers) {
+                unsub();
+            }
+        };
+        const timeout = setTimeout(() => {
+            if (!completed) {
+                completed = true;
+                cleanup();
+                reject(new Error(`Task timeout after ${timeoutMs}ms`));
+            }
+        }, timeoutMs);
+        // Set up all event listeners
+        unsubscribers.push(
+        // Listen for LLM response content
+        client.on('llmservice:response', (payload) => {
+            if (payload.taskId === taskId && payload.content) {
+                result = payload.content;
+            }
+        }), 
+        // Listen for task completion
+        client.on('task:completed', (payload) => {
+            if (payload.taskId === taskId && !completed) {
+                completed = true;
+                cleanup();
+                // Use the result from the event if available, otherwise use accumulated result
+                resolve(payload.result || result);
+            }
+        }), 
+        // Listen for task error
+        client.on('task:error', (payload) => {
+            if (payload.taskId === taskId && !completed) {
+                completed = true;
+                cleanup();
+                reject(new Error(payload.error.message));
+            }
+        }));
+    });
+}

package/dist/infra/process/agent-worker.js

@@ -808,6 +808,43 @@ async function startAgent() {
             await transportClient?.request('agent:restarted', { error: message, success: false });
         }
     });
+    // Handle agent:newSession from Transport (triggered by /new command)
+    transportClient.on('agent:newSession', async (data) => {
+        agentLog(`New session requested: ${data.reason ?? 'no reason'}`);
+        try {
+            if (!cipherAgent) {
+                agentLog('Cannot create new session - agent not initialized');
+                await transportClient?.request('agent:newSessionCreated', {
+                    error: 'Agent not initialized',
+                    success: false,
+                });
+                return;
+            }
+            // Generate new session ID
+            const newSessionId = `agent-session-${randomUUID()}`;
+            // Create new session
+            await cipherAgent.createSession(newSessionId);
+            // Switch the agent's default session to the new one
+            // This ensures execute()/generate()/stream() use the new session
+            cipherAgent.switchDefaultSession(newSessionId);
+            // Update the local session ID reference
+            chatSessionId = newSessionId;
+            agentLog(`New session created: ${newSessionId}`);
+            // Notify Transport that new session was created
+            await transportClient?.request('agent:newSessionCreated', {
+                sessionId: newSessionId,
+                success: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            agentLog(`New session creation error: ${message}`);
+            await transportClient?.request('agent:newSessionCreated', {
+                error: message,
+                success: false,
+            });
+        }
+    });
     agentLog('Ready to process tasks');
 }
 // ============================================================================

package/dist/infra/repl/commands/curate-command.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { isDevelopment } from '../../../config/environment.js';
 import { CommandKind } from '../../../tui/types.js';
-import { FileGlobalConfigStore } from "../../storage/file-global-config-store.js";
+import { FileGlobalConfigStore } from '../../storage/file-global-config-store.js';
 import { createTokenStore } from '../../storage/token-store.js';
 import { ReplTerminal } from '../../terminal/repl-terminal.js';
 import { MixpanelTrackingService } from '../../tracking/mixpanel-tracking-service.js';
@@ -73,7 +73,7 @@ export const curateCommand = {
         {
             char: '@',
             description: 'Include files (type @ to browse, max 5)',
-            name: 'files',
+            name: 'file',
             type: 'file',
         },
         ...(isDevelopment() ? toCommandFlags(devFlags) : []),

package/dist/infra/transport/socket-io-transport-client.d.ts

@@ -35,6 +35,13 @@ export declare class SocketIOTransportClient implements ITransportClient {
     disconnect(): Promise<void>;
     getClientId(): string | undefined;
     getState(): ConnectionState;
+    /**
+     * Checks if the socket is actually connected and responsive.
+     * Uses Socket.IO's built-in volatile emit with acknowledgement to verify bidirectional communication.
+     * @param timeoutMs - Timeout in milliseconds (default: 2000)
+     * @returns true if socket is connected and responsive, false otherwise
+     */
+    isConnected(timeoutMs?: number): Promise<boolean>;
     joinRoom(room: string): Promise<void>;
     leaveRoom(room: string): Promise<void>;
     on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
@@ -65,6 +72,15 @@ export declare class SocketIOTransportClient implements ITransportClient {
      * Used when initiating new connection attempt - counter preserved for backoff continuity.
      */
     private clearForceReconnectTimer;
+    /**
+     * Remove all registered event listeners from socket.
+     * Used before re-registering to prevent listener accumulation across reconnects.
+     *
+     * Why this is needed: Socket.IO preserves the Socket instance across internal reconnects.
+     * If we clear registeredSocketEvents without calling socket.off(), the old listeners
+     * remain attached, and registerPendingEventHandlers() adds new ones - causing duplicates.
+     */
+    private clearSocketEventListeners;
     /**
      * Handle system wake from sleep/hibernate.
      * Re-triggers reconnection if not connected and force reconnect has given up.

package/dist/infra/transport/socket-io-transport-client.js

@@ -145,8 +145,10 @@ export class SocketIOTransportClient {
                 clientLog(`Socket.IO built-in reconnect succeeded after ${attemptNumber} attempts`);
                 this.setState('connected');
                 // Re-register event handlers after reconnect
-                // Clear tracking first since socket listeners were reset during reconnect
-                this.registeredSocketEvents.clear();
+                // FIX: Remove existing socket listeners before re-registering to prevent
+                // listener accumulation. Socket.IO preserves the Socket instance across
+                // internal reconnects, so old listeners remain attached if not removed.
+                this.clearSocketEventListeners();
                 this.registerPendingEventHandlers();
                 // Auto-rejoin rooms after reconnect
                 // Use process.nextTick to ensure socket.connected is true
@@ -192,6 +194,31 @@ export class SocketIOTransportClient {
     getState() {
         return this.state;
     }
+    /**
+     * Checks if the socket is actually connected and responsive.
+     * Uses Socket.IO's built-in volatile emit with acknowledgement to verify bidirectional communication.
+     * @param timeoutMs - Timeout in milliseconds (default: 2000)
+     * @returns true if socket is connected and responsive, false otherwise
+     */
+    async isConnected(timeoutMs = 2000) {
+        const { socket } = this;
+        // Quick check: if socket doesn't exist or isn't marked as connected, return false immediately
+        if (!socket?.connected) {
+            return false;
+        }
+        // Verify actual bidirectional communication with a ping
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                resolve(false);
+            }, timeoutMs);
+            // Use Socket.IO's built-in ping mechanism via volatile emit
+            // Volatile means if the message can't be sent, it won't be buffered
+            socket.volatile.emit('ping', { timestamp: Date.now() }, () => {
+                clearTimeout(timeout);
+                resolve(true);
+            });
+        });
+    }
     async joinRoom(room) {
         const { socket } = this;
         if (!socket?.connected) {
@@ -383,6 +410,23 @@ export class SocketIOTransportClient {
             this.forceReconnectTimer = undefined;
         }
     }
+    /**
+     * Remove all registered event listeners from socket.
+     * Used before re-registering to prevent listener accumulation across reconnects.
+     *
+     * Why this is needed: Socket.IO preserves the Socket instance across internal reconnects.
+     * If we clear registeredSocketEvents without calling socket.off(), the old listeners
+     * remain attached, and registerPendingEventHandlers() adds new ones - causing duplicates.
+     */
+    clearSocketEventListeners() {
+        const { socket } = this;
+        if (!socket)
+            return;
+        for (const event of this.registeredSocketEvents) {
+            socket.off(event);
+        }
+        this.registeredSocketEvents.clear();
+    }
     /**
      * Handle system wake from sleep/hibernate.
      * Re-triggers reconnection if not connected and force reconnect has given up.

package/dist/infra/transport/socket-io-transport-server.js

@@ -145,6 +145,10 @@ export class SocketIOTransportServer {
                     socket.leave(room);
                     callback?.({ success: true });
                 });
+                // Handle ping requests for health checks
+                socket.on('ping', (_data, callback) => {
+                    callback?.({ pong: true, timestamp: Date.now() });
+                });
             });
             this.httpServer.on('error', (err) => {
                 if (err.code === 'EADDRINUSE') {

package/dist/infra/usecase/connectors-use-case.d.ts

@@ -20,6 +20,10 @@ export declare class ConnectorsUseCase implements IConnectorsUseCase {
     private readonly trackingService;
     constructor(options: ConnectorsUseCaseOptions);
     run(): Promise<void>;
+    /**
+     * Display manual setup instructions for MCP configuration.
+     */
+    private displayManualInstructions;
     /**
      * Gets a description for a connector type.
      */