byterover-cli 1.5.0 → 1.7.0

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

@@ -0,0 +1,564 @@
+import { setMaxListeners } from 'node:events';
+import { STREAMING_EVENT_NAMES } from '../../core/domain/streaming/types.js';
+import { AgentEventBus } from '../events/event-emitter.js';
+import { SessionManager } from '../session/session-manager.js';
+import { AgentError } from './agent-error.js';
+import { BaseAgent } from './base-agent.js';
+import { createCipherAgentServices } from './service-initializer.js';
+/**
+ * CipherAgent - Main agent implementation extending BaseAgent.
+ *
+ * Inherits from BaseAgent:
+ * - Two-phase initialization (constructor + start)
+ * - Lifecycle management (start, stop, restart)
+ * - State management with session overrides
+ * - Typed error handling
+ * - Configuration validation (Zod)
+ *
+ * Architecture (DextoAgent pattern):
+ * - Agent creates AgentEventBus in constructor (available before start)
+ * - Agent creates and owns shared services (ToolManager, SystemPromptManager, etc.)
+ * - SessionManager creates session-specific services (LLM, SessionEventBus)
+ * - Agent delegates execution to sessions via session.run()
+ *
+ * Usage:
+ * - execute(input) uses default session automatically
+ * - execute(input, sessionId) for multi-session support
+ */
+export class CipherAgent extends BaseAgent {
+    // Private state (must come before methods)
+    _agentEventBus;
+    _brvConfig;
+    /**
+     * Session ID - created once during start().
+     * Each agent has exactly 1 session (Single-Session pattern).
+     */
+    _sessionId;
+    activeStreamControllers = new Map();
+    sessionManager;
+    /**
+     * Creates a new CipherAgent instance.
+     * Does NOT initialize services - call start() for async initialization.
+     *
+     * @param config - Agent configuration (Zod-validated AgentConfig)
+     * @param brvConfig - Optional ByteRover config for spaceId/teamId
+     */
+    constructor(config, brvConfig) {
+        // Call parent constructor (validates with Zod)
+        super(config);
+        // Create event bus early (DextoAgent pattern - available before start)
+        this._agentEventBus = new AgentEventBus();
+        this._brvConfig = brvConfig;
+    }
+    // === Public Getters (expose services for backward compatibility) ===
+    get agentEventBus() {
+        return this.services?.agentEventBus;
+    }
+    get fileSystemService() {
+        return this.services?.fileSystemService;
+    }
+    get historyStorage() {
+        return this.services?.historyStorage;
+    }
+    get memoryManager() {
+        return this.services?.memoryManager;
+    }
+    get processService() {
+        return this.services?.processService;
+    }
+    /**
+     * Get the session ID (created during start()).
+     * Each agent has exactly 1 session (Single-Session pattern).
+     */
+    get sessionId() {
+        return this._sessionId;
+    }
+    get systemPromptManager() {
+        return this.services?.systemPromptManager;
+    }
+    get toolManager() {
+        return this.services?.toolManager;
+    }
+    get toolProvider() {
+        return this.services?.toolProvider;
+    }
+    // === Public Methods (alphabetical order) ===
+    /**
+     * Cancels the currently running turn for the agent's default session.
+     * Safe to call even if no run is in progress.
+     *
+     * @returns true if a run was in progress and was signaled to abort; false otherwise
+     */
+    async cancel() {
+        this.ensureStarted();
+        const sessionId = this.getSessionIdInternal();
+        // Abort the stream iterator first (so consumer's for-await loop exits cleanly)
+        const streamController = this.activeStreamControllers.get(sessionId);
+        if (streamController) {
+            streamController.abort();
+            this.activeStreamControllers.delete(sessionId);
+        }
+        // Then cancel the session's LLM/tool execution
+        const session = this.getSessionManagerInternal().getSession(sessionId);
+        if (session) {
+            session.cancel();
+            return true;
+        }
+        // If no session found but stream was aborted, still return true
+        return Boolean(streamController);
+    }
+    async cleanupServices() {
+        // Abort all active streams and clear controllers
+        for (const controller of this.activeStreamControllers.values()) {
+            controller.abort();
+        }
+        this.activeStreamControllers.clear();
+        // Dispose session manager
+        if (this.sessionManager) {
+            this.sessionManager.dispose();
+            this.sessionManager = undefined;
+        }
+        // Reset execution state (only if state manager exists - may not during early cleanup)
+        if (this.stateManager) {
+            this.stateManager.reset();
+        }
+        // Clean up sandbox service (release VM contexts and pending operations)
+        if (this.services?.sandboxService) {
+            await this.services.sandboxService.cleanup();
+        }
+        // Close SQLite databases to release file handles and ensure clean shutdown
+        if (this.services?.blobStorage) {
+            this.services.blobStorage.close();
+        }
+    }
+    /**
+     * Create a new session.
+     */
+    async createSession(sessionId) {
+        this.ensureStarted();
+        return this.getSessionManagerInternal().createSession(sessionId);
+    }
+    /**
+     * Delete a session completely (memory + history).
+     */
+    async deleteSession(sessionId) {
+        this.ensureStarted();
+        // Clear session config overrides
+        if (this.stateManager) {
+            this.stateManager.clearSessionOverride(sessionId);
+        }
+        return this.getSessionManagerInternal().deleteSession(sessionId);
+    }
+    /**
+     * Execute the agent with user input.
+     * Uses the agent's default session (created during start()).
+     * Internally uses generate() for single code path maintainability.
+     *
+     * @param input - User message
+     * @param options - Optional execution options
+     * @param options.executionContext - Optional execution context
+     * @param options.taskId - Optional task ID for concurrent task isolation
+     */
+    async execute(input, options) {
+        this.ensureStarted();
+        // Use generate() internally for single code path
+        const response = await this.generate(input, {
+            executionContext: options?.executionContext,
+            taskId: options?.taskId,
+        });
+        return response.content;
+    }
+    /**
+     * Generate a complete response (waits for full completion).
+     * Wrapper around stream() that collects all events and returns final result.
+     * Uses the agent's default session (created during start()).
+     *
+     * @param input - User message
+     * @param options - Optional configuration (signal for cancellation, taskId for billing)
+     * @returns Complete response with content, usage, and tool calls
+     */
+    async generate(input, options) {
+        const sessionId = this.getSessionIdInternal();
+        // Collect all events from stream
+        const events = [];
+        for await (const event of await this.stream(input, options)) {
+            events.push(event);
+        }
+        // Check for non-recoverable error events
+        const fatalErrorEvent = events.find((e) => e.name === 'llmservice:error' && e.recoverable !== true);
+        if (fatalErrorEvent) {
+            throw new Error(fatalErrorEvent.error);
+        }
+        // Find the final response event
+        const responseEvent = events.find((e) => e.name === 'llmservice:response');
+        if (!responseEvent || responseEvent.name !== 'llmservice:response') {
+            throw new Error('Stream did not complete successfully - no response received');
+        }
+        // Collect tool calls
+        const toolCallEvents = events.filter((e) => e.name === 'llmservice:toolCall');
+        const toolResultEvents = events.filter((e) => e.name === 'llmservice:toolResult');
+        const toolCalls = toolCallEvents.map((tc) => {
+            const toolResult = toolResultEvents.find((tr) => tr.callId === tc.callId);
+            return {
+                args: tc.args,
+                callId: tc.callId ?? `tool_${Date.now()}`,
+                result: toolResult ? { data: toolResult.result, success: toolResult.success } : undefined,
+                toolName: tc.toolName,
+            };
+        });
+        const defaultUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        return {
+            content: responseEvent.content,
+            reasoning: responseEvent.reasoning,
+            sessionId,
+            toolCalls,
+            usage: responseEvent.tokenUsage ?? defaultUsage,
+        };
+    }
+    /**
+     * Get an existing session or create a new one.
+     */
+    async getOrCreateSession(sessionId) {
+        this.ensureStarted();
+        const sessionMgr = this.getSessionManagerInternal();
+        const existingSession = sessionMgr.getSession(sessionId);
+        return existingSession ?? sessionMgr.createSession(sessionId);
+    }
+    /**
+     * Get a session by ID.
+     */
+    getSession(sessionId) {
+        this.ensureStarted();
+        return this.getSessionManagerInternal().getSession(sessionId);
+    }
+    /**
+     * Get session metadata without loading full history.
+     */
+    async getSessionMetadata(sessionId) {
+        this.ensureStarted();
+        return this.getHistoryStorageInternal().getSessionMetadata(sessionId);
+    }
+    /**
+     * Get current agent state.
+     * Returns default state if agent is not yet started.
+     */
+    getState() {
+        // Return default state if not started yet (for backward compatibility)
+        if (!this.stateManager) {
+            return {
+                currentIteration: 0,
+                executionHistory: [],
+                executionState: 'idle',
+                toolCallsExecuted: 0,
+            };
+        }
+        return this.stateManager.getExecutionState();
+    }
+    /**
+     * Get the current system prompt.
+     */
+    async getSystemPrompt() {
+        this.ensureStarted();
+        return this.getSystemPromptManagerInternal().build({});
+    }
+    async initializeServices() {
+        // Pass pre-created event bus to service initializer (DextoAgent pattern)
+        return createCipherAgentServices(this.config, this._agentEventBus);
+    }
+    /**
+     * List all persisted session IDs from history storage.
+     */
+    async listPersistedSessions() {
+        this.ensureStarted();
+        return this.getHistoryStorageInternal().listSessions();
+    }
+    /**
+     * List all session IDs (in-memory only).
+     */
+    listSessions() {
+        this.ensureStarted();
+        return this.getSessionManagerInternal().listSessions();
+    }
+    // === Protected Methods (implement abstract from BaseAgent) ===
+    /**
+     * Reset the agent to initial state.
+     * Resets execution state only. To reset sessions, use resetSession(sessionId).
+     */
+    reset() {
+        // Reset execution state (only if state manager exists - may not if not started)
+        if (this.stateManager) {
+            this.stateManager.reset();
+        }
+    }
+    /**
+     * Reset a specific session's conversation history.
+     * @param sessionId - The session ID to reset
+     */
+    resetSession(sessionId) {
+        const session = this.getSessionManagerInternal().getSession(sessionId);
+        if (session) {
+            session.reset();
+        }
+        // Emit conversation reset event (only if agent is started)
+        if (this._isStarted && this.services?.agentEventBus) {
+            this.services.agentEventBus.emit('cipher:conversationReset', { sessionId });
+        }
+    }
+    /**
+     * Start the agent - initializes all services asynchronously.
+     * Must be called before execute().
+     */
+    async start() {
+        // Call parent start (creates services)
+        await super.start();
+        // Create SessionManager with shared services
+        const services = this.getServices();
+        // Extract HTTP config
+        const httpConfig = {
+            accessToken: this.config.accessToken,
+            apiBaseUrl: this.config.apiBaseUrl,
+            projectId: this.config.projectId,
+            region: this.config.region,
+            sessionKey: this.config.sessionKey,
+            spaceId: this.config.spaceId ?? this._brvConfig?.spaceId ?? '',
+            teamId: this.config.teamId ?? this._brvConfig?.teamId ?? '',
+        };
+        // Extract LLM config for sessions
+        const sessionLLMConfig = {
+            httpReferer: this.config.httpReferer,
+            maxIterations: this.config.llm.maxIterations,
+            maxTokens: this.config.llm.maxTokens,
+            model: this.config.model,
+            openRouterApiKey: this.config.openRouterApiKey,
+            siteName: this.config.siteName,
+            temperature: this.config.llm.temperature,
+            verbose: this.config.llm.verbose,
+        };
+        // Create SessionManager
+        this.sessionManager = new SessionManager(services, httpConfig, sessionLLMConfig, {
+            config: {
+                maxSessions: this.config.sessions.maxSessions,
+                sessionTTL: this.config.sessions.sessionTTL,
+            },
+        });
+        // Create default session (Single-Session pattern)
+        // Each agent has exactly 1 session created at start time
+        const defaultSession = await this.sessionManager.createSession();
+        this._sessionId = defaultSession.id;
+    }
+    /**
+     * Stream a response with real-time event emission.
+     * Uses the agent's default session (created during start()).
+     *
+     * @param input - User message
+     * @param options - Optional configuration (signal for cancellation, taskId for billing)
+     * @returns AsyncIterator that yields StreamingEvent objects
+     */
+    async stream(input, options) {
+        this.ensureStarted();
+        const sessionId = this.getSessionIdInternal();
+        const signal = options?.signal;
+        // Event queue for aggregation
+        const eventQueue = [];
+        let completed = false;
+        // Create AbortController for cleanup
+        const controller = new AbortController();
+        const cleanupSignal = controller.signal;
+        // Store controller so cancel() can abort this stream (keyed by sessionId)
+        this.activeStreamControllers.set(sessionId, controller);
+        // Increase listener limit - stream() registers many event listeners
+        setMaxListeners(30, cleanupSignal);
+        // Track listener references for manual cleanup
+        const listeners = [];
+        // Get the agent event bus
+        const agentEventBus = this.services?.agentEventBus;
+        if (!agentEventBus) {
+            throw AgentError.serviceNotInitialized('AgentEventBus');
+        }
+        // Cleanup function to remove all listeners and stream controller
+        const cleanupListeners = () => {
+            if (listeners.length === 0) {
+                return; // Already cleaned up
+            }
+            for (const { event, listener } of listeners) {
+                agentEventBus.off(event, listener);
+            }
+            listeners.length = 0;
+            // Remove from active controllers map
+            this.activeStreamControllers.delete(sessionId);
+        };
+        // Wire external signal to trigger cleanup
+        if (signal) {
+            const abortHandler = () => {
+                cleanupListeners();
+                controller.abort();
+            };
+            signal.addEventListener('abort', abortHandler, { once: true });
+        }
+        // Subscribe to streaming events (filter by sessionId - ChatSession.id)
+        for (const eventName of STREAMING_EVENT_NAMES) {
+            const listener = (payload) => {
+                const data = payload;
+                if (data.sessionId !== sessionId)
+                    return;
+                // Add event to queue with name discriminant
+                eventQueue.push({ name: eventName, ...data });
+                // Close iterator on run:complete
+                if (eventName === 'run:complete') {
+                    completed = true;
+                }
+            };
+            agentEventBus.on(eventName, listener, { signal: cleanupSignal });
+            listeners.push({ event: eventName, listener });
+        }
+        // Start streaming in background (fire-and-forget)
+        ;
+        (async () => {
+            try {
+                // Get or create session using the provided sessionId
+                // ChatSession maintains conversation history
+                const sessionMgr = this.getSessionManagerInternal();
+                const existingSession = sessionMgr.getSession(sessionId);
+                const session = existingSession ?? (await sessionMgr.createSession(sessionId));
+                // Increment iteration counter
+                this.getStateManager().incrementIteration();
+                // Call session.streamRun() which emits events and run:complete
+                // Pass taskId for concurrent task isolation (included in all emitted events)
+                await session.streamRun(input, {
+                    executionContext: options?.executionContext,
+                    signal,
+                    taskId: options?.taskId,
+                });
+            }
+            catch (error_) {
+                // Emit error event if something goes wrong
+                completed = true;
+                const error = error_ instanceof Error ? error_ : new Error(String(error_));
+                eventQueue.push({
+                    code: undefined,
+                    error: error.message,
+                    name: 'llmservice:error',
+                    recoverable: false,
+                    sessionId,
+                });
+            }
+        })();
+        // Resolve function for waiting - will be called when new events arrive
+        let notifyNewEvent = null;
+        // Wrap the original listener to also notify waiters
+        const originalListeners = [...listeners];
+        listeners.length = 0;
+        for (const { event, listener: originalListener } of originalListeners) {
+            const wrappedListener = (payload) => {
+                originalListener(payload);
+                // Notify any waiting next() call
+                if (notifyNewEvent) {
+                    notifyNewEvent();
+                    notifyNewEvent = null;
+                }
+            };
+            agentEventBus.off(event, originalListener);
+            agentEventBus.on(event, wrappedListener, { signal: cleanupSignal });
+            listeners.push({ event, listener: wrappedListener });
+        }
+        // Return async iterable iterator
+        const iterator = {
+            async next() {
+                // If we already have events, return immediately
+                if (eventQueue.length > 0) {
+                    return { done: false, value: eventQueue.shift() };
+                }
+                // If already completed, cleanup and return
+                if (completed) {
+                    cleanupListeners();
+                    return { done: true, value: undefined };
+                }
+                // Check for abort
+                if (signal?.aborted || cleanupSignal.aborted) {
+                    cleanupListeners();
+                    return { done: true, value: undefined };
+                }
+                // Wait for new events
+                await new Promise((resolve) => {
+                    notifyNewEvent = resolve;
+                    // Also resolve on abort
+                    const abortHandler = () => {
+                        notifyNewEvent = null;
+                        resolve();
+                    };
+                    cleanupSignal.addEventListener('abort', abortHandler, { once: true });
+                    if (signal) {
+                        signal.addEventListener('abort', abortHandler, { once: true });
+                    }
+                });
+                // After waiting, check state again
+                if (signal?.aborted || cleanupSignal.aborted) {
+                    cleanupListeners();
+                    return { done: true, value: undefined };
+                }
+                if (eventQueue.length > 0) {
+                    return { done: false, value: eventQueue.shift() };
+                }
+                if (completed) {
+                    cleanupListeners();
+                    return { done: true, value: undefined };
+                }
+                // Recursive call to handle edge cases
+                return iterator.next();
+            },
+            async return() {
+                // Called when consumer breaks out early or explicitly calls return()
+                cleanupListeners();
+                controller.abort();
+                return { done: true, value: undefined };
+            },
+            [Symbol.asyncIterator]() {
+                return iterator;
+            },
+        };
+        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;
+        if (!storage) {
+            throw AgentError.serviceNotInitialized('HistoryStorage');
+        }
+        return storage;
+    }
+    getSessionIdInternal() {
+        if (!this._sessionId) {
+            throw AgentError.serviceNotInitialized('Session (call start() first)');
+        }
+        return this._sessionId;
+    }
+    getSessionManagerInternal() {
+        if (!this.sessionManager) {
+            throw AgentError.serviceNotInitialized('SessionManager');
+        }
+        return this.sessionManager;
+    }
+    getSystemPromptManagerInternal() {
+        const manager = this.services?.systemPromptManager;
+        if (!manager) {
+            throw AgentError.serviceNotInitialized('SystemPromptManager');
+        }
+        return manager;
+    }
+}

package/dist/agent/infra/agent/interactive-commands.d.ts

@@ -0,0 +1,16 @@
+import type { ICipherAgent } from '../../core/interfaces/i-cipher-agent.js';
+/**
+ * Get all available command names (including aliases) for autocomplete
+ *
+ * @returns Array of command names with '/' prefix
+ */
+export declare function getCommandNames(): string[];
+/**
+ * Execute an interactive command
+ *
+ * @param command - Command name
+ * @param args - Command arguments
+ * @param agent - CipherAgent instance
+ * @returns Promise<boolean> - true to continue loop, false to exit
+ */
+export declare function executeCommand(command: string, args: string[], agent: ICipherAgent): Promise<boolean>;

package/dist/agent/infra/agent/interactive-loop.d.ts

@@ -0,0 +1,24 @@
+import type { ICipherAgent } from '../../core/interfaces/i-cipher-agent.js';
+import type { AgentEventBus } from '../events/event-emitter.js';
+/**
+ * Display system information message on the same line using carriage return
+ * This allows messages to overwrite each other for cleaner output
+ *
+ * @param message - Info message to display
+ * @param clear - If true, clear the line after displaying (for completed actions)
+ */
+export declare function displayInfo(message: string, clear?: boolean): void;
+/**
+ * Start interactive loop for CipherAgent
+ *
+ * @param agent - CipherAgent instance
+ * @param options - Optional configuration
+ * @param options.model - LLM model name
+ * @param options.sessionId - Session identifier
+ * @param options.eventBus - Optional event bus for listening to agent events
+ */
+export declare function startInteractiveLoop(agent: ICipherAgent, options?: {
+    eventBus?: AgentEventBus;
+    model?: string;
+    sessionId?: string;
+}): Promise<void>;

package/dist/agent/infra/agent/service-initializer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Service Initializer: Centralized Wiring for Cipher Agent Services
+ *
+ * This module is responsible for initializing and wiring together all core agent services.
+ * It provides a single entry point for constructing the service graph.
+ *
+ * Following DextoAgent pattern:
+ * - Config file is source of truth (ValidatedAgentConfig)
+ * - Centralized function (not factory class) for service creation
+ * - Explicit dependency order with numbered steps
+ * - Event bus passed in as parameter (created in agent constructor)
+ */
+import type { CipherAgentServices, SessionServices } from '../../core/interfaces/cipher-services.js';
+import type { ValidatedAgentConfig } from './agent-schemas.js';
+import { AgentEventBus } from '../events/event-emitter.js';
+/**
+ * HTTP configuration for ByteRover LLM service.
+ */
+export interface ByteRoverHttpConfig {
+    accessToken: string;
+    apiBaseUrl: string;
+    projectId: string;
+    region?: string;
+    sessionKey: string;
+    spaceId: string;
+    teamId: string;
+    timeout?: number;
+}
+/**
+ * LLM configuration for per-session services.
+ */
+export interface SessionLLMConfig {
+    httpReferer?: string;
+    maxIterations?: number;
+    maxTokens?: number;
+    model: string;
+    openRouterApiKey?: string;
+    siteName?: string;
+    temperature?: number;
+    verbose?: boolean;
+}
+export type { CipherAgentServices, SessionManagerConfig, SessionServices } from '../../core/interfaces/cipher-services.js';
+/**
+ * Creates shared services for CipherAgent.
+ * These services are singletons shared across all sessions.
+ *
+ * Initialization order follows DextoAgent pattern (explicit numbered steps):
+ * 1. Logger (uses provided event bus)
+ * 2. File system service (no dependencies)
+ * 3. Process service (no dependencies)
+ * 4. Blob storage (no dependencies)
+ * 5. Memory system (depends on BlobStorage, Logger)
+ * 6. System prompt manager (no dependencies)
+ * 7. Tool provider (depends on FileSystemService, ProcessService, MemoryManager)
+ * 8. Policy engine (no dependencies)
+ * 9. Tool scheduler (depends on ToolProvider, PolicyEngine)
+ * 10. Tool manager (depends on ToolProvider, ToolScheduler)
+ * 11. History storage (depends on BlobStorage)
+ * 12. Return all services
+ *
+ * @param config - Validated agent configuration (Zod-validated)
+ * @param agentEventBus - Pre-created event bus from agent constructor (DextoAgent pattern)
+ * @returns Initialized shared services
+ */
+export declare function createCipherAgentServices(config: ValidatedAgentConfig, agentEventBus: AgentEventBus): Promise<CipherAgentServices>;
+/**
+ * Creates session-specific services for a ChatSession.
+ * Generator composition order (innermost to outermost):
+ * 1. Base generator (ByteRoverContentGenerator or OpenRouterContentGenerator)
+ * 2. RetryableContentGenerator - handles transient errors with backoff
+ * 3. LoggingContentGenerator - debug logging (if verbose enabled)
+ *
+ * @param sessionId - Unique session identifier
+ * @param sharedServices - Shared services from agent
+ * @param httpConfig - HTTP configuration
+ * @param llmConfig - LLM service configuration
+ * @returns Initialized session services
+ */
+export declare function createSessionServices(sessionId: string, sharedServices: CipherAgentServices, httpConfig: ByteRoverHttpConfig, llmConfig: SessionLLMConfig): SessionServices;