byterover-cli 0.2.1 → 0.3.0

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

@@ -0,0 +1,108 @@
+/**
+ * Manages the runtime state of the CipherAgent.
+ *
+ * Enhanced to track execution state, termination reasons, timing,
+ * and tool metrics following gemini-cli patterns. Maintains backward
+ * compatibility with legacy fields (executionHistory).
+ */
+export class CipherAgentStateManager {
+    currentIteration = 0;
+    durationMs;
+    endTime;
+    executionHistory = [];
+    executionState = 'idle';
+    startTime;
+    terminationReason;
+    toolCallsExecuted = 0;
+    /**
+     * Add an execution record to history (legacy method).
+     * @param record - Execution record to add
+     */
+    addExecutionRecord(record) {
+        this.executionHistory.push(record);
+    }
+    /**
+     * Mark execution as complete with reason.
+     * @param reason - Why execution terminated
+     */
+    complete(reason) {
+        this.executionState = 'complete';
+        this.terminationReason = reason;
+        this.endTime = new Date();
+        if (this.startTime) {
+            this.durationMs = this.endTime.getTime() - this.startTime.getTime();
+        }
+    }
+    /**
+     * Mark execution as errored.
+     * @param reason - Error termination reason
+     */
+    fail(reason) {
+        this.executionState = 'error';
+        this.terminationReason = reason;
+        this.endTime = new Date();
+        if (this.startTime) {
+            this.durationMs = this.endTime.getTime() - this.startTime.getTime();
+        }
+    }
+    /**
+     * Get the current state.
+     * @returns Current agent state with all enhanced fields
+     */
+    getState() {
+        return {
+            currentIteration: this.currentIteration,
+            durationMs: this.durationMs,
+            endTime: this.endTime,
+            executionHistory: [...this.executionHistory],
+            executionState: this.executionState,
+            startTime: this.startTime,
+            terminationReason: this.terminationReason,
+            toolCallsExecuted: this.toolCallsExecuted,
+        };
+    }
+    /**
+     * Increment the iteration counter.
+     * @returns The new iteration count
+     */
+    incrementIteration() {
+        this.currentIteration++;
+        return this.currentIteration;
+    }
+    /**
+     * Increment the tool calls counter.
+     * @returns The new tool calls count
+     */
+    incrementToolCalls() {
+        this.toolCallsExecuted++;
+        return this.toolCallsExecuted;
+    }
+    /**
+     * Reset the state to initial values.
+     */
+    reset() {
+        this.currentIteration = 0;
+        this.durationMs = undefined;
+        this.endTime = undefined;
+        this.executionHistory = [];
+        this.executionState = 'idle';
+        this.startTime = undefined;
+        this.terminationReason = undefined;
+        this.toolCallsExecuted = 0;
+    }
+    /**
+     * Set the current execution state.
+     * @param state - New execution state
+     */
+    setExecutionState(state) {
+        this.executionState = state;
+    }
+    /**
+     * Start execution tracking.
+     * Sets startTime and transitions to executing state.
+     */
+    startExecution() {
+        this.startTime = new Date();
+        this.executionState = 'executing';
+    }
+}

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

@@ -0,0 +1,182 @@
+import type { BrvConfig } from '../../core/domain/entities/brv-config.js';
+import type { IChatSession } from '../../core/interfaces/cipher/i-chat-session.js';
+import type { AgentState, ExecutionContext, ICipherAgent } from '../../core/interfaces/cipher/i-cipher-agent.js';
+import type { IHistoryStorage } from '../../core/interfaces/cipher/i-history-storage.js';
+import type { CipherLLMConfig } from './agent-service-factory.js';
+import type { AgentEventBus } from './events/event-emitter.js';
+import type { FileSystemService } from './file-system/file-system-service.js';
+import type { MemoryManager } from './memory/memory-manager.js';
+import type { ProcessService } from './process/process-service.js';
+import type { SimplePromptFactory } from './system-prompt/simple-prompt-factory.js';
+import type { ToolManager } from './tools/tool-manager.js';
+import type { ToolProvider } from './tools/tool-provider.js';
+/**
+ * CipherAgent - Main agent implementation
+ *
+ * Following Dexto's pattern: CipherAgent orchestrates sessions and delegates
+ * execution to ChatSession instances. Each session maintains isolated conversation
+ * context while sharing global services (tools, prompts, file system, etc.).
+ *
+ * Architecture:
+ * - Agent creates and owns shared services (ToolManager, SystemPromptManager, etc.)
+ * - SessionManager creates session-specific services (LLM, EventBus)
+ * - Agent delegates execution to sessions via session.run()
+ *
+ * Follows two-phase initialization:
+ * 1. Constructor: validates and stores config
+ * 2. start(): asynchronously creates all services and SessionManager
+ *
+ * Backward compatible:
+ * - execute(input) uses default session automatically
+ * - New: execute(input, sessionId) for multi-session support
+ */
+export declare class CipherAgent implements ICipherAgent {
+    readonly agentEventBus?: AgentEventBus;
+    readonly fileSystemService?: FileSystemService;
+    readonly historyStorage?: IHistoryStorage;
+    readonly memoryManager?: MemoryManager;
+    readonly processService?: ProcessService;
+    readonly promptFactory?: SimplePromptFactory;
+    readonly toolManager?: ToolManager;
+    readonly toolProvider?: ToolProvider;
+    private readonly _brvConfig?;
+    private _isStarted;
+    private readonly currentDefaultSessionId;
+    private defaultSession;
+    private readonly llmConfig;
+    private sessionManager?;
+    private readonly stateManager;
+    /**
+     * Creates a new CipherAgent instance
+     * Does NOT initialize services - call start() for async initialization
+     *
+     * @param llmConfig - LLM configuration (API key, model settings)
+     * @param brvConfig - Optional ByteRover config (for custom system prompt)
+     */
+    constructor(llmConfig: CipherLLMConfig, brvConfig?: BrvConfig);
+    /**
+     * Create a new session.
+     *
+     * @param sessionId - Optional session ID (generates UUID if not provided)
+     * @returns New or existing chat session
+     */
+    createSession(sessionId?: string): Promise<IChatSession>;
+    /**
+     * Delete a session completely (memory + history).
+     *
+     * @param sessionId - Session ID to delete
+     * @returns True if session existed and was deleted
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+    /**
+     * Execute the agent with user input.
+     *
+     * Following Dexto's pattern: determine target session, get or create it,
+     * then delegate to session.run().
+     *
+     * @param input - User input string
+     * @param sessionId - Optional session ID (uses 'default' if not provided)
+     * @param options - Optional execution options
+     * @param options.mode - Optional mode for system prompt ('autonomous' enables autonomous mode)
+     * @param options.executionContext - Optional execution context
+     * @returns Agent response from LLM
+     * @throws Error if agent is not started
+     */
+    execute(input: string, sessionId?: string, options?: {
+        executionContext?: ExecutionContext;
+        mode?: 'autonomous' | 'default' | 'query';
+    }): Promise<string>;
+    /**
+     * Get an existing session or create a new one.
+     * Useful for ensuring a session exists before pre-loading history.
+     *
+     * @param sessionId - Session ID to get or create
+     * @returns Existing or newly created chat session
+     */
+    getOrCreateSession(sessionId: string): Promise<IChatSession>;
+    /**
+     * Get a session by ID.
+     *
+     * @param sessionId - Session ID
+     * @returns Session instance or undefined if not found
+     */
+    getSession(sessionId: string): IChatSession | undefined;
+    /**
+     * Get session metadata without loading full history.
+     *
+     * @param sessionId - Session ID
+     * @returns Session metadata or undefined if not found
+     */
+    getSessionMetadata(sessionId: string): Promise<import('../../core/domain/cipher/storage/history-types.js').SessionMetadata | undefined>;
+    /**
+     * Get current agent state
+     *
+     * @returns Current state information
+     */
+    getState(): AgentState;
+    /**
+     * Get the current system prompt from SimplePromptFactory
+     * Useful for debugging and inspection
+     *
+     * @returns Current system prompt (built dynamically)
+     */
+    getSystemPrompt(): Promise<string>;
+    /**
+     * List all persisted session IDs from history storage.
+     *
+     * @returns Array of session IDs
+     */
+    listPersistedSessions(): Promise<string[]>;
+    /**
+     * List all session IDs (in-memory only).
+     *
+     * @returns Array of session IDs
+     */
+    listSessions(): string[];
+    /**
+     * Reset the agent to initial state.
+     * Clears execution history, resets iteration counter, and resets default session.
+     */
+    reset(): void;
+    /**
+     * Start the agent - initializes all services asynchronously
+     * Must be called before execute()
+     *
+     * @throws Error if agent is already started
+     */
+    start(): Promise<void>;
+    /**
+     * Ensure the agent has been started and all services are initialized
+     *
+     * @throws Error if agent is not started or services are not initialized
+     */
+    private ensureStarted;
+    /**
+     * Get initialized agent event bus (guaranteed to be defined after start())
+     *
+     * @returns AgentEventBus instance
+     * @throws Error if not initialized
+     */
+    private getAgentEventBus;
+    /**
+     * Get initialized history storage (guaranteed to be defined after start())
+     *
+     * @returns IHistoryStorage instance
+     * @throws Error if not initialized
+     */
+    private getHistoryStorage;
+    /**
+     * Get initialized prompt factory (guaranteed to be defined after start())
+     *
+     * @returns SimplePromptFactory instance
+     * @throws Error if not initialized
+     */
+    private getPromptFactory;
+    /**
+     * Get initialized session manager (guaranteed to be defined after start())
+     *
+     * @returns SessionManager instance
+     * @throws Error if not initialized
+     */
+    private getSessionManager;
+}

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

@@ -0,0 +1,317 @@
+import { createCipherAgentServices } from './agent-service-factory.js';
+import { CipherAgentStateManager } from './cipher-agent-state-manager.js';
+import { SessionManager } from './session/session-manager.js';
+/**
+ * CipherAgent - Main agent implementation
+ *
+ * Following Dexto's pattern: CipherAgent orchestrates sessions and delegates
+ * execution to ChatSession instances. Each session maintains isolated conversation
+ * context while sharing global services (tools, prompts, file system, etc.).
+ *
+ * Architecture:
+ * - Agent creates and owns shared services (ToolManager, SystemPromptManager, etc.)
+ * - SessionManager creates session-specific services (LLM, EventBus)
+ * - Agent delegates execution to sessions via session.run()
+ *
+ * Follows two-phase initialization:
+ * 1. Constructor: validates and stores config
+ * 2. start(): asynchronously creates all services and SessionManager
+ *
+ * Backward compatible:
+ * - execute(input) uses default session automatically
+ * - New: execute(input, sessionId) for multi-session support
+ */
+export class CipherAgent {
+    // Shared services (exposed publicly for external access)
+    // Made optional to avoid definite assignment assertions
+    agentEventBus;
+    fileSystemService;
+    historyStorage;
+    memoryManager;
+    processService;
+    promptFactory;
+    toolManager;
+    toolProvider;
+    _brvConfig;
+    _isStarted = false;
+    currentDefaultSessionId = 'default';
+    defaultSession = null;
+    llmConfig;
+    sessionManager;
+    stateManager;
+    /**
+     * Creates a new CipherAgent instance
+     * Does NOT initialize services - call start() for async initialization
+     *
+     * @param llmConfig - LLM configuration (API key, model settings)
+     * @param brvConfig - Optional ByteRover config (for custom system prompt)
+     */
+    constructor(llmConfig, brvConfig) {
+        this.llmConfig = llmConfig;
+        this._brvConfig = brvConfig;
+        this.stateManager = new CipherAgentStateManager();
+    }
+    /**
+     * Create a new session.
+     *
+     * @param sessionId - Optional session ID (generates UUID if not provided)
+     * @returns New or existing chat session
+     */
+    async createSession(sessionId) {
+        this.ensureStarted();
+        return this.getSessionManager().createSession(sessionId);
+    }
+    /**
+     * Delete a session completely (memory + history).
+     *
+     * @param sessionId - Session ID to delete
+     * @returns True if session existed and was deleted
+     */
+    async deleteSession(sessionId) {
+        this.ensureStarted();
+        return this.getSessionManager().deleteSession(sessionId);
+    }
+    /**
+     * Execute the agent with user input.
+     *
+     * Following Dexto's pattern: determine target session, get or create it,
+     * then delegate to session.run().
+     *
+     * @param input - User input string
+     * @param sessionId - Optional session ID (uses 'default' if not provided)
+     * @param options - Optional execution options
+     * @param options.mode - Optional mode for system prompt ('autonomous' enables autonomous mode)
+     * @param options.executionContext - Optional execution context
+     * @returns Agent response from LLM
+     * @throws Error if agent is not started
+     */
+    async execute(input, sessionId, options) {
+        // Ensure agent is started
+        this.ensureStarted();
+        // Determine target session (backward compatible: defaults to 'default')
+        const targetSessionId = sessionId ?? this.currentDefaultSessionId;
+        // Get or create session (lazy loading pattern from Dexto)
+        const sessionMgr = this.getSessionManager();
+        const existingSession = sessionMgr.getSession(targetSessionId);
+        const session = existingSession ?? (await sessionMgr.createSession(targetSessionId));
+        // Cache default session for faster access
+        if (targetSessionId === this.currentDefaultSessionId && !this.defaultSession) {
+            this.defaultSession = session;
+        }
+        // Increment iteration counter (agent-level state) - kept for internal tracking only
+        this.stateManager.incrementIteration();
+        // Note: Execution records removed to reduce log noise
+        // DELEGATE TO SESSION
+        // The ChatSession will:
+        // 1. Call llmService.completeTask()
+        // 2. LLM service handles agentic loop (tools, prompts, iterations)
+        // 3. Events forwarded from session bus to agent bus
+        const response = await session.run(input, options);
+        return response;
+    }
+    /**
+     * Get an existing session or create a new one.
+     * Useful for ensuring a session exists before pre-loading history.
+     *
+     * @param sessionId - Session ID to get or create
+     * @returns Existing or newly created chat session
+     */
+    async getOrCreateSession(sessionId) {
+        this.ensureStarted();
+        const sessionMgr = this.getSessionManager();
+        const existingSession = sessionMgr.getSession(sessionId);
+        return existingSession ?? sessionMgr.createSession(sessionId);
+    }
+    /**
+     * Get a session by ID.
+     *
+     * @param sessionId - Session ID
+     * @returns Session instance or undefined if not found
+     */
+    getSession(sessionId) {
+        this.ensureStarted();
+        return this.getSessionManager().getSession(sessionId);
+    }
+    /**
+     * Get session metadata without loading full history.
+     *
+     * @param sessionId - Session ID
+     * @returns Session metadata or undefined if not found
+     */
+    async getSessionMetadata(sessionId) {
+        this.ensureStarted();
+        return this.getHistoryStorage().getSessionMetadata(sessionId);
+    }
+    /**
+     * Get current agent state
+     *
+     * @returns Current state information
+     */
+    getState() {
+        return this.stateManager.getState();
+    }
+    /**
+     * Get the current system prompt from SimplePromptFactory
+     * Useful for debugging and inspection
+     *
+     * @returns Current system prompt (built dynamically)
+     */
+    async getSystemPrompt() {
+        this.ensureStarted();
+        return this.getPromptFactory().buildSystemPrompt({});
+    }
+    /**
+     * List all persisted session IDs from history storage.
+     *
+     * @returns Array of session IDs
+     */
+    async listPersistedSessions() {
+        this.ensureStarted();
+        return this.getHistoryStorage().listSessions();
+    }
+    /**
+     * List all session IDs (in-memory only).
+     *
+     * @returns Array of session IDs
+     */
+    listSessions() {
+        this.ensureStarted();
+        return this.getSessionManager().listSessions();
+    }
+    /**
+     * Reset the agent to initial state.
+     * Clears execution history, resets iteration counter, and resets default session.
+     */
+    reset() {
+        this.stateManager.reset();
+        // Reset default session if it exists
+        if (this.defaultSession) {
+            this.defaultSession.reset();
+        }
+        // Emit conversation reset event (only if agent is started)
+        if (this._isStarted) {
+            this.getAgentEventBus().emit('cipher:conversationReset', {
+                sessionId: this.currentDefaultSessionId,
+            });
+        }
+    }
+    /**
+     * Start the agent - initializes all services asynchronously
+     * Must be called before execute()
+     *
+     * @throws Error if agent is already started
+     */
+    async start() {
+        if (this._isStarted) {
+            throw new Error('CipherAgent is already started');
+        }
+        // Services will create necessary directories during their initialization
+        // No need for upfront validation - let services handle their own setup
+        // Create SHARED services only (following Dexto's pattern)
+        const sharedServices = await createCipherAgentServices(this.llmConfig);
+        // Extract gRPC config from llmConfig
+        const grpcConfig = {
+            accessToken: this.llmConfig.accessToken,
+            grpcEndpoint: this.llmConfig.grpcEndpoint,
+            projectId: this.llmConfig.projectId,
+            region: this.llmConfig.region,
+            sessionKey: this.llmConfig.sessionKey,
+            spaceId: this._brvConfig?.spaceId ?? '',
+            teamId: this._brvConfig?.teamId ?? '',
+        };
+        // Extract LLM config for sessions
+        const sessionLLMConfig = {
+            httpReferer: this.llmConfig.httpReferer,
+            maxIterations: this.llmConfig.maxIterations,
+            maxTokens: this.llmConfig.maxTokens,
+            model: this.llmConfig.model,
+            openRouterApiKey: this.llmConfig.openRouterApiKey,
+            siteName: this.llmConfig.siteName,
+            temperature: this.llmConfig.temperature,
+            verbose: this.llmConfig.verbose,
+        };
+        // Create SessionManager with shared services
+        const sessionManager = new SessionManager(sharedServices, grpcConfig, sessionLLMConfig, {
+            config: {
+                maxSessions: 100,
+                sessionTTL: 3_600_000, // 1 hour
+            },
+        });
+        // Assign services using Object.assign for readonly properties
+        Object.assign(this, {
+            ...sharedServices,
+            sessionManager,
+        });
+        this._isStarted = true;
+    }
+    /**
+     * Ensure the agent has been started and all services are initialized
+     *
+     * @throws Error if agent is not started or services are not initialized
+     */
+    ensureStarted() {
+        if (!this._isStarted) {
+            throw new Error('CipherAgent must be started before use. Call start() first.');
+        }
+        // Runtime validation to ensure services were properly initialized
+        if (!this.agentEventBus ||
+            !this.fileSystemService ||
+            !this.historyStorage ||
+            !this.memoryManager ||
+            !this.processService ||
+            !this.promptFactory ||
+            !this.toolManager ||
+            !this.toolProvider ||
+            !this.sessionManager) {
+            throw new Error('CipherAgent services not properly initialized. This is a bug.');
+        }
+    }
+    /**
+     * Get initialized agent event bus (guaranteed to be defined after start())
+     *
+     * @returns AgentEventBus instance
+     * @throws Error if not initialized
+     */
+    getAgentEventBus() {
+        if (!this.agentEventBus) {
+            throw new Error('AgentEventBus not initialized. This is a bug.');
+        }
+        return this.agentEventBus;
+    }
+    /**
+     * Get initialized history storage (guaranteed to be defined after start())
+     *
+     * @returns IHistoryStorage instance
+     * @throws Error if not initialized
+     */
+    getHistoryStorage() {
+        if (!this.historyStorage) {
+            throw new Error('HistoryStorage not initialized. This is a bug.');
+        }
+        return this.historyStorage;
+    }
+    /**
+     * Get initialized prompt factory (guaranteed to be defined after start())
+     *
+     * @returns SimplePromptFactory instance
+     * @throws Error if not initialized
+     */
+    getPromptFactory() {
+        if (!this.promptFactory) {
+            throw new Error('SimplePromptFactory not initialized. This is a bug.');
+        }
+        return this.promptFactory;
+    }
+    /**
+     * Get initialized session manager (guaranteed to be defined after start())
+     *
+     * @returns SessionManager instance
+     * @throws Error if not initialized
+     */
+    getSessionManager() {
+        if (!this.sessionManager) {
+            throw new Error('SessionManager not initialized. This is a bug.');
+        }
+        return this.sessionManager;
+    }
+}

package/dist/infra/cipher/command-parser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Command parser for interactive CLI
+ * Parses user input to distinguish between slash commands and regular prompts
+ */
+/**
+ * Result type for parsed commands
+ */
+export type CommandResult = {
+    args?: string[];
+    command?: string;
+    rawInput: string;
+    type: 'command';
+} | {
+    rawInput: string;
+    type: 'prompt';
+};
+/**
+ * Parse user input into command or prompt
+ *
+ * @param input - Raw user input string
+ * @returns Parsed command result (discriminated union)
+ */
+export declare function parseInput(input: string): CommandResult;