byterover-cli 1.7.2 → 2.0.0

package/dist/agent/infra/sandbox/tools-sdk.d.ts

@@ -1,6 +1,8 @@
 import type { FileContent, GlobResult, ListDirectoryResult, SearchResult, WriteResult } from '../../core/domain/file-system/types.js';
 import type { CurateOperation, CurateOptions, CurateResult, DetectDomainsInput, DetectDomainsResult, ICurateService } from '../../core/interfaces/i-curate-service.js';
 import type { IFileSystem } from '../../core/interfaces/i-file-system.js';
+import type { ISandboxService } from '../../core/interfaces/i-sandbox-service.js';
+import type { SessionManager } from '../session/session-manager.js';
 /**
  * Options for glob operation in ToolsSDK.
  */
@@ -65,9 +67,17 @@ export interface SearchKnowledgeOptions {
 export interface SearchKnowledgeResult {
     message: string;
     results: Array<{
+        /** Number of other memories that reference this one */
+        backlinkCount?: number;
         excerpt: string;
         path: string;
+        /** Top backlink source paths (max 3) */
+        relatedPaths?: string[];
         score: number;
+        /** Symbol kind: 'domain' | 'topic' | 'subtopic' | 'context' */
+        symbolKind?: string;
+        /** Resolved hierarchical path in the symbol tree */
+        symbolPath?: string;
         title: string;
     }>;
     totalFound: number;
@@ -84,6 +94,19 @@ export interface ISearchKnowledgeService {
  * Provides async file system operations for programmatic access.
  */
 export interface ToolsSDK {
+    /**
+     * Spawn a sub-agent to process a prompt with full code_exec access.
+     * The sub-agent runs in an isolated context (does not pollute parent).
+     * Only the final response string flows back.
+     * @param prompt - Prompt for the sub-agent
+     * @param options - Optional limits
+     * @param options.maxIterations - Maximum agentic iterations (default: 5)
+     * @returns Promise resolving to the sub-agent's final response
+     */
+    agentQuery(prompt: string, options?: {
+        contextData?: Record<string, unknown>;
+        maxIterations?: number;
+    }): Promise<string>;
     /**
      * Execute curate operations on knowledge topics.
      * Operations: ADD, UPDATE, MERGE, DELETE
@@ -143,15 +166,30 @@ export interface ToolsSDK {
      */
     writeFile(filePath: string, content: string, options?: WriteFileOptions): Promise<WriteResult>;
 }
+/**
+ * Options for creating a Tools SDK instance.
+ */
+export interface CreateToolsSDKOptions {
+    /** Curate service for knowledge curation */
+    curateService?: ICurateService;
+    /** File system service for file operations */
+    fileSystem: IFileSystem;
+    /** Parent session ID for creating child sessions (required for agentQuery) */
+    parentSessionId?: string;
+    /** Sandbox service for variable injection into child sessions (optional, enables contextData in agentQuery) */
+    sandboxService?: ISandboxService;
+    /** Search knowledge service */
+    searchKnowledgeService?: ISearchKnowledgeService;
+    /** Session manager for sub-agent delegation (required for agentQuery) */
+    sessionManager?: SessionManager;
+}
 /**
  * Creates a Tools SDK instance for sandbox code execution.
  *
  * The SDK provides async wrapper functions around file system operations,
  * allowing code executed in the sandbox to access file system tools programmatically.
  *
- * @param fileSystem - File system service for file operations
- * @param searchKnowledgeService - Optional search knowledge service
- * @param curateService - Optional curate service for knowledge curation
+ * @param options - Configuration options for the Tools SDK
  * @returns ToolsSDK instance ready to be injected into sandbox context
  */
-export declare function createToolsSDK(fileSystem: IFileSystem, searchKnowledgeService?: ISearchKnowledgeService, curateService?: ICurateService): ToolsSDK;
+export declare function createToolsSDK(options: CreateToolsSDKOptions): ToolsSDK;

package/dist/agent/infra/sandbox/tools-sdk.js

@@ -4,13 +4,38 @@
  * The SDK provides async wrapper functions around file system operations,
  * allowing code executed in the sandbox to access file system tools programmatically.
  *
- * @param fileSystem - File system service for file operations
- * @param searchKnowledgeService - Optional search knowledge service
- * @param curateService - Optional curate service for knowledge curation
+ * @param options - Configuration options for the Tools SDK
  * @returns ToolsSDK instance ready to be injected into sandbox context
  */
-export function createToolsSDK(fileSystem, searchKnowledgeService, curateService) {
+export function createToolsSDK(options) {
+    const { curateService, fileSystem, parentSessionId, sandboxService, searchKnowledgeService, sessionManager } = options;
     return {
+        async agentQuery(prompt, options) {
+            if (!sessionManager || !parentSessionId) {
+                throw new Error('agentQuery not available — no session manager configured');
+            }
+            const childSession = await sessionManager.createChildSession(parentSessionId, 'sub-query');
+            try {
+                // Inject context data as sandbox variables in child session (RLM pattern).
+                // This avoids embedding large data directly in the prompt string.
+                if (options?.contextData && sandboxService) {
+                    for (const [key, value] of Object.entries(options.contextData)) {
+                        sandboxService.setSandboxVariable(childSession.id, key, value);
+                    }
+                }
+                const response = await childSession.run(prompt, {
+                    emitTaskId: false,
+                    executionContext: {
+                        commandType: 'query',
+                        maxIterations: options?.maxIterations ?? 5,
+                    },
+                });
+                return response;
+            }
+            finally {
+                await sessionManager.deleteSession(childSession.id);
+            }
+        },
         async curate(operations, options) {
             if (!curateService) {
                 return {

package/dist/agent/infra/session/chat-session.d.ts

@@ -77,7 +77,7 @@ export declare class ChatSession implements IChatSession {
     /**
      * Reset the conversation history.
      */
-    reset(): void;
+    reset(): Promise<void>;
     /**
      * Send a message and get a response.
      * Delegates to the LLM service which handles the agentic loop.

package/dist/agent/infra/session/chat-session.js

@@ -154,9 +154,9 @@ export class ChatSession {
     /**
      * Reset the conversation history.
      */
-    reset() {
+    async reset() {
         const contextManager = this.llmService.getContextManager();
-        contextManager.clearHistory();
+        await contextManager.clearHistory();
         // Emit conversation reset event
         this.sharedServices.agentEventBus.emit('cipher:conversationReset', {
             sessionId: this.id,

package/dist/agent/infra/session/session-event-forwarder.js

@@ -34,9 +34,12 @@
  * @param sessionId - Unique session identifier to add to forwarded events
  */
 export function setupEventForwarding(sessionEventBus, agentEventBus, sessionId) {
-    // Forward llmservice:thinking (void payload)
-    sessionEventBus.on('llmservice:thinking', () => {
-        agentEventBus.emit('llmservice:thinking', { sessionId });
+    // Forward llmservice:thinking (may carry taskId from AgentLLMService)
+    sessionEventBus.on('llmservice:thinking', (payload) => {
+        agentEventBus.emit('llmservice:thinking', {
+            ...(typeof payload === 'object' && payload !== null ? payload : {}),
+            sessionId,
+        });
     });
     // Forward llmservice:chunk
     sessionEventBus.on('llmservice:chunk', (payload) => {

package/dist/agent/infra/session/session-manager.d.ts

@@ -62,13 +62,18 @@ export declare class SessionManager {
      * @param sharedServices - Shared services from CipherAgent (ToolManager, SystemPromptManager, etc.)
      * @param httpConfig - HTTP client configuration
      * @param llmConfig - LLM service configuration
-     * @param llmConfig.openRouterApiKey - Optional OpenRouter API key for direct service
      * @param llmConfig.httpReferer - Optional HTTP Referer for OpenRouter rankings
-     * @param llmConfig.siteName - Optional site name for OpenRouter rankings
      * @param llmConfig.maxIterations - Maximum iterations for agentic loop
      * @param llmConfig.maxTokens - Maximum output tokens
      * @param llmConfig.model - LLM model identifier
+     * @param llmConfig.openRouterApiKey - Optional OpenRouter API key for direct service
+     * @param llmConfig.provider - Optional direct provider ID (anthropic, openai, google, xai, groq, mistral)
+     * @param llmConfig.providerApiKey - Optional API key for direct provider
+     * @param llmConfig.providerBaseUrl - Optional base URL for OpenAI-compatible provider
+     * @param llmConfig.providerHeaders - Optional custom headers for provider
+     * @param llmConfig.siteName - Optional site name for OpenRouter rankings
      * @param llmConfig.temperature - Temperature for generation
+     * @param llmConfig.verbose - Optional verbose debug output
      * @param options - Optional session manager options
      * @param options.config - Session manager configuration
      */
@@ -78,8 +83,13 @@ export declare class SessionManager {
         maxTokens?: number;
         model: string;
         openRouterApiKey?: string;
+        provider?: string;
+        providerApiKey?: string;
+        providerBaseUrl?: string;
+        providerHeaders?: Record<string, string>;
         siteName?: string;
         temperature?: number;
+        verbose?: boolean;
     }, options?: SessionManagerOptions);
     /**
      * Create a child session for a subagent.

package/dist/agent/infra/session/session-manager.js

@@ -35,13 +35,18 @@ export class SessionManager {
      * @param sharedServices - Shared services from CipherAgent (ToolManager, SystemPromptManager, etc.)
      * @param httpConfig - HTTP client configuration
      * @param llmConfig - LLM service configuration
-     * @param llmConfig.openRouterApiKey - Optional OpenRouter API key for direct service
      * @param llmConfig.httpReferer - Optional HTTP Referer for OpenRouter rankings
-     * @param llmConfig.siteName - Optional site name for OpenRouter rankings
      * @param llmConfig.maxIterations - Maximum iterations for agentic loop
      * @param llmConfig.maxTokens - Maximum output tokens
      * @param llmConfig.model - LLM model identifier
+     * @param llmConfig.openRouterApiKey - Optional OpenRouter API key for direct service
+     * @param llmConfig.provider - Optional direct provider ID (anthropic, openai, google, xai, groq, mistral)
+     * @param llmConfig.providerApiKey - Optional API key for direct provider
+     * @param llmConfig.providerBaseUrl - Optional base URL for OpenAI-compatible provider
+     * @param llmConfig.providerHeaders - Optional custom headers for provider
+     * @param llmConfig.siteName - Optional site name for OpenRouter rankings
      * @param llmConfig.temperature - Temperature for generation
+     * @param llmConfig.verbose - Optional verbose debug output
      * @param options - Optional session manager options
      * @param options.config - Session manager configuration
      */
@@ -184,7 +189,15 @@ export class SessionManager {
             return false;
         }
         // Clear session history
-        session.reset();
+        await session.reset();
+        // Dispose session to remove event listeners (prevents memory leak on repeated task sessions)
+        session.dispose();
+        // Clean up metadata maps
+        this.sessionCreatedAt.delete(id);
+        this.sessionLastActivity.delete(id);
+        this.sessionTitles.delete(id);
+        this.sessionAgentNames.delete(id);
+        this.sessionParentIds.delete(id);
         // Remove from memory
         return this.sessions.delete(id);
     }
@@ -203,8 +216,6 @@ export class SessionManager {
         }
         // Dispose all sessions (prevents event forwarder leaks)
         for (const session of this.sessions.values()) {
-            // ChatSession.dispose() removes event forwarders
-            ;
             session.dispose();
         }
         this.sessions.clear();
@@ -232,8 +243,14 @@ export class SessionManager {
         // Ensure history is persisted before removing from memory
         const contextManager = session.getLLMService().getContextManager();
         await contextManager.flush();
-        // Cleanup session resources (cancels in-flight ops, preserves history)
-        session.cleanup();
+        // Dispose session to remove event listeners (dispose calls cleanup internally)
+        session.dispose();
+        // Clean up metadata maps
+        this.sessionCreatedAt.delete(id);
+        this.sessionLastActivity.delete(id);
+        this.sessionTitles.delete(id);
+        this.sessionAgentNames.delete(id);
+        this.sessionParentIds.delete(id);
         // Remove from memory only - history remains in storage
         return this.sessions.delete(id);
     }
@@ -350,7 +367,7 @@ export class SessionManager {
         // Create session with both shared and session services
         const session = new ChatSession(id, this.sharedServices, sessionServices);
         // Initialize LLM service to load persisted history from blob storage
-        // Only call initialize() if the service has the method (ByteRoverLLMService has it, GeminiLLMService doesn't)
+        // Only call initialize() if the service has the method (AgentLLMService has it)
         if ('initialize' in sessionServices.llmService && typeof sessionServices.llmService.initialize === 'function') {
             await sessionServices.llmService.initialize();
             // Debug logging removed for cleaner user experience

package/dist/agent/infra/session/session-metadata-store.d.ts

@@ -1,7 +1,7 @@
 /**
  * SessionMetadataStore - Manages session metadata persistence.
  *
- * Stores session metadata in .brv/sessions/ directory:
+ * Stores session metadata in the XDG sessions directory:
  * - active.json: Current active session pointer
  * - session-*.json: Individual session metadata files
  *
@@ -9,10 +9,20 @@
  */
 import type { ISessionPersistence, SessionCleanupResult, SessionRetentionConfig } from '../../core/interfaces/i-session-persistence.js';
 import { type ActiveSessionPointer, type SessionInfo, type SessionMetadata } from '../../core/domain/session/session-metadata.js';
+/**
+ * Configuration for SessionMetadataStore.
+ */
+type SessionMetadataStoreOptions = {
+    /** Sessions directory path (XDG storage path). */
+    sessionsDir: string;
+    /** Project working directory. */
+    workingDirectory: string;
+};
 /**
  * SessionMetadataStore implementation.
  *
- * Manages session metadata stored in .brv/sessions/ directory.
+ * Manages session metadata stored in the XDG sessions directory.
+ * Callers must provide the explicit sessionsDir path.
  */
 export declare class SessionMetadataStore implements ISessionPersistence {
     private readonly activeSessionPath;
@@ -21,32 +31,29 @@ export declare class SessionMetadataStore implements ISessionPersistence {
     /**
      * Create a new SessionMetadataStore.
      *
-     * @param workingDirectory - Project working directory (defaults to process.cwd())
+     * @param options - Configuration options (sessionsDir and workingDirectory required)
      */
-    constructor(workingDirectory?: string);
+    constructor(options: SessionMetadataStoreOptions);
     cleanupSessions(config: SessionRetentionConfig): Promise<SessionCleanupResult>;
-    clearActiveSession(): Promise<void>;
     /**
      * Create a new session metadata object.
      *
      * @param sessionId - Session ID
+     * @param providerId - Optional provider ID for cross-provider resume detection
      * @returns New session metadata with defaults
      */
-    createSessionMetadata(sessionId: string): SessionMetadata;
-    deleteSession(sessionId: string): Promise<boolean>;
+    createSessionMetadata(sessionId: string, providerId?: string): SessionMetadata;
     getActiveSession(): Promise<ActiveSessionPointer | null>;
     getSession(sessionId: string): Promise<null | SessionMetadata>;
     isActiveSessionStale(): Promise<boolean>;
     isSessionForCurrentProject(sessionId: string): Promise<boolean>;
     listSessions(): Promise<SessionInfo[]>;
-    markSessionEnded(sessionId: string): Promise<void>;
     markSessionInterrupted(sessionId: string): Promise<void>;
     saveSession(metadata: SessionMetadata): Promise<void>;
     setActiveSession(sessionId: string): Promise<void>;
-    setSessionTitle(sessionId: string, title: string): Promise<void>;
-    updateSessionActivity(sessionId: string, messageCount: number): Promise<void>;
     /**
      * Ensure the sessions directory exists.
      */
     private ensureSessionsDir;
 }
+export {};

package/dist/agent/infra/session/session-metadata-store.js

@@ -1,7 +1,7 @@
 /**
  * SessionMetadataStore - Manages session metadata persistence.
  *
- * Stores session metadata in .brv/sessions/ directory:
+ * Stores session metadata in the XDG sessions directory:
  * - active.json: Current active session pointer
  * - session-*.json: Individual session metadata files
  *
@@ -10,7 +10,7 @@
 import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import { join } from 'node:path';
-import { ACTIVE_SESSION_FILE, ActiveSessionPointerSchema, cleanMessageForTitle, generateSessionFilename, parseSessionFilename, SESSION_FILE_PREFIX, SessionMetadataSchema, SESSIONS_DIR, } from '../../core/domain/session/session-metadata.js';
+import { ACTIVE_SESSION_FILE, ActiveSessionPointerSchema, generateSessionFilename, parseSessionFilename, SESSION_FILE_PREFIX, SessionMetadataSchema, } from '../../core/domain/session/session-metadata.js';
 /**
  * Check if a process with given PID is running.
  *
@@ -47,14 +47,13 @@ const PROCESS_TOKEN = randomUUID();
  * @returns The UUID portion without the prefix
  */
 function extractUuidFromSessionId(sessionId) {
-    return sessionId.startsWith(SESSION_ID_PREFIX)
-        ? sessionId.slice(SESSION_ID_PREFIX.length)
-        : sessionId;
+    return sessionId.startsWith(SESSION_ID_PREFIX) ? sessionId.slice(SESSION_ID_PREFIX.length) : sessionId;
 }
 /**
  * SessionMetadataStore implementation.
  *
- * Manages session metadata stored in .brv/sessions/ directory.
+ * Manages session metadata stored in the XDG sessions directory.
+ * Callers must provide the explicit sessionsDir path.
  */
 export class SessionMetadataStore {
     activeSessionPath;
@@ -63,11 +62,11 @@ export class SessionMetadataStore {
     /**
      * Create a new SessionMetadataStore.
      *
-     * @param workingDirectory - Project working directory (defaults to process.cwd())
+     * @param options - Configuration options (sessionsDir and workingDirectory required)
      */
-    constructor(workingDirectory) {
-        this.workingDirectory = workingDirectory ?? process.cwd();
-        this.sessionsDir = join(this.workingDirectory, '.brv', SESSIONS_DIR);
+    constructor(options) {
+        this.workingDirectory = options.workingDirectory;
+        this.sessionsDir = options.sessionsDir;
         this.activeSessionPath = join(this.sessionsDir, ACTIVE_SESSION_FILE);
     }
     // ============================================================================
@@ -163,75 +162,25 @@ export class SessionMetadataStore {
             throw error;
         }
     }
-    async clearActiveSession() {
-        try {
-            await fs.unlink(this.activeSessionPath);
-        }
-        catch (error) {
-            // Ignore if file doesn't exist
-            if (error.code !== 'ENOENT') {
-                throw error;
-            }
-        }
-    }
     /**
      * Create a new session metadata object.
      *
      * @param sessionId - Session ID
+     * @param providerId - Optional provider ID for cross-provider resume detection
      * @returns New session metadata with defaults
      */
-    createSessionMetadata(sessionId) {
+    createSessionMetadata(sessionId, providerId) {
         const now = new Date().toISOString();
         return {
             createdAt: now,
             lastUpdated: now,
             messageCount: 0,
+            ...(providerId && { providerId }),
             sessionId,
             status: 'active',
             workingDirectory: this.workingDirectory,
         };
     }
-    async deleteSession(sessionId) {
-        try {
-            const files = await fs.readdir(this.sessionsDir);
-            for (const file of files) {
-                if (!file.startsWith(SESSION_FILE_PREFIX) || !file.endsWith('.json')) {
-                    continue;
-                }
-                const parsed = parseSessionFilename(file);
-                // Extract UUID from sessionId (removes "agent-session-" prefix if present)
-                // then compare with the filename's uuid prefix
-                const uuid = extractUuidFromSessionId(sessionId);
-                if (parsed && uuid.startsWith(parsed.uuidPrefix)) {
-                    // eslint-disable-next-line no-await-in-loop
-                    await fs.unlink(join(this.sessionsDir, file));
-                    return true;
-                }
-                // Also check by reading the file to match full sessionId
-                try {
-                    const filePath = join(this.sessionsDir, file);
-                    // eslint-disable-next-line no-await-in-loop
-                    const content = await fs.readFile(filePath, 'utf8');
-                    const data = JSON.parse(content);
-                    if (data.sessionId === sessionId) {
-                        // eslint-disable-next-line no-await-in-loop
-                        await fs.unlink(filePath);
-                        return true;
-                    }
-                }
-                catch {
-                    // Continue to next file
-                }
-            }
-            return false;
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return false;
-            }
-            throw error;
-        }
-    }
     async getActiveSession() {
         try {
             const content = await fs.readFile(this.activeSessionPath, 'utf8');
@@ -332,14 +281,6 @@ export class SessionMetadataStore {
     // ============================================================================
     // Session Lifecycle
     // ============================================================================
-    async markSessionEnded(sessionId) {
-        const session = await this.getSession(sessionId);
-        if (session) {
-            session.status = 'ended';
-            session.lastUpdated = new Date().toISOString();
-            await this.saveSession(session);
-        }
-    }
     async markSessionInterrupted(sessionId) {
         const session = await this.getSession(sessionId);
         if (session) {
@@ -381,22 +322,6 @@ export class SessionMetadataStore {
         };
         await fs.writeFile(this.activeSessionPath, JSON.stringify(pointer, null, 2), 'utf8');
     }
-    async setSessionTitle(sessionId, title) {
-        const session = await this.getSession(sessionId);
-        if (session && !session.title) {
-            session.title = cleanMessageForTitle(title);
-            session.lastUpdated = new Date().toISOString();
-            await this.saveSession(session);
-        }
-    }
-    async updateSessionActivity(sessionId, messageCount) {
-        const session = await this.getSession(sessionId);
-        if (session) {
-            session.lastUpdated = new Date().toISOString();
-            session.messageCount = messageCount;
-            await this.saveSession(session);
-        }
-    }
     /**
      * Ensure the sessions directory exists.
      */

package/dist/agent/infra/storage/blob-history-storage.d.ts

@@ -19,6 +19,11 @@ export declare class BlobHistoryStorage implements IHistoryStorage {
      * @param blobStorage - The blob storage backend to use
      */
     constructor(blobStorage: IBlobStorage);
+    /**
+     * Append a single message to the session history.
+     * For blob storage, this loads existing history, appends, and re-saves.
+     */
+    appendMessage(sessionId: string, message: InternalMessage): Promise<void>;
     /**
      * Delete all history for a specific session.
      *

package/dist/agent/infra/storage/blob-history-storage.js

@@ -17,6 +17,21 @@ export class BlobHistoryStorage {
     constructor(blobStorage) {
         this.blobStorage = blobStorage;
     }
+    /**
+     * Append a single message to the session history.
+     * For blob storage, this loads existing history, appends, and re-saves.
+     */
+    async appendMessage(sessionId, message) {
+        try {
+            const existing = await this.loadHistory(sessionId);
+            const messages = existing ?? [];
+            messages.push(message);
+            await this.saveHistory(sessionId, messages);
+        }
+        catch (error) {
+            console.error(`[BlobHistoryStorage] Failed to append message for session ${sessionId}:`, error);
+        }
+    }
     /**
      * Delete all history for a specific session.
      *

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

@@ -21,6 +21,12 @@ export declare class DualFormatHistoryStorage implements IHistoryStorage {
     private readonly blobStorage;
     private readonly granularStorage;
     constructor(blobStorage: BlobHistoryStorage, granularStorage: GranularHistoryStorage);
+    /**
+     * Append a single message to the session history.
+     * Routes to appropriate storage based on session format.
+     * New sessions use granular format.
+     */
+    appendMessage(sessionId: string, message: InternalMessage): Promise<void>;
     /**
      * Delete all history for a session.
      * Deletes from both storages to ensure complete cleanup.

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

@@ -19,6 +19,22 @@ export class DualFormatHistoryStorage {
         this.blobStorage = blobStorage;
         this.granularStorage = granularStorage;
     }
+    /**
+     * Append a single message to the session history.
+     * Routes to appropriate storage based on session format.
+     * New sessions use granular format.
+     */
+    async appendMessage(sessionId, message) {
+        const format = await this.detectFormat(sessionId);
+        if (format === 'granular') {
+            return this.granularStorage.appendMessage(sessionId, message);
+        }
+        if (format === 'blob') {
+            return this.blobStorage.appendMessage(sessionId, message);
+        }
+        // New session - use granular format
+        return this.granularStorage.appendMessage(sessionId, message);
+    }
     /**
      * Delete all history for a session.
      * Deletes from both storages to ensure complete cleanup.