byterover-cli 0.2.0 → 0.3.0

package/dist/infra/cipher/interactive-commands.js

@@ -0,0 +1,198 @@
+import chalk from 'chalk';
+/**
+ * Format a timestamp as a human-readable "time ago" string.
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns Human-readable time ago string (e.g., "2 hours ago", "3 days ago")
+ */
+function formatTimeAgo(timestamp) {
+    const now = Date.now();
+    const diffMs = now - timestamp;
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    const diffHours = Math.floor(diffMinutes / 60);
+    const diffDays = Math.floor(diffHours / 24);
+    if (diffSeconds < 60) {
+        return 'just now';
+    }
+    if (diffMinutes < 60) {
+        return `${diffMinutes} minute${diffMinutes === 1 ? '' : 's'} ago`;
+    }
+    if (diffHours < 24) {
+        return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`;
+    }
+    if (diffDays < 30) {
+        return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
+    }
+    const diffMonths = Math.floor(diffDays / 30);
+    return `${diffMonths} month${diffMonths === 1 ? '' : 's'} ago`;
+}
+/**
+ * Available interactive commands
+ */
+const INTERACTIVE_COMMANDS = [
+    {
+        aliases: ['?'],
+        description: 'Show available commands',
+        async handler() {
+            console.log('\n' + chalk.bold.cyan('📋 Available Commands:'));
+            console.log(chalk.cyan('─'.repeat(60)));
+            for (const cmd of INTERACTIVE_COMMANDS) {
+                const aliases = cmd.aliases ? chalk.gray(` (${cmd.aliases.join(', ')})`) : '';
+                console.log(chalk.green(`  /${cmd.name}`) + aliases);
+                console.log(chalk.white(`    ${cmd.description}`));
+                if (cmd.usage) {
+                    console.log(chalk.gray(`    Usage: ${cmd.usage}`));
+                }
+                console.log();
+            }
+            return true; // Continue loop
+        },
+        name: 'help',
+    },
+    {
+        description: 'Clear conversation history',
+        async handler(_args, agent) {
+            agent.reset();
+            console.log('\n' + chalk.green('✓ Conversation history cleared'));
+            return true; // Continue loop
+        },
+        name: 'reset',
+    },
+    {
+        description: 'Show agent state',
+        async handler(_args, agent) {
+            const state = agent.getState();
+            console.log('\n' + chalk.bold.cyan('📊 Agent State:'));
+            console.log(chalk.cyan('─'.repeat(60)));
+            console.log(chalk.white(`  Iterations: ${chalk.bold(state.currentIteration.toString())}`));
+            console.log(chalk.white(`  Execution history entries: ${chalk.bold(state.executionHistory.length.toString())}`));
+            if (state.executionHistory.length > 0) {
+                console.log(chalk.white('\n  Recent executions:'));
+                const recent = state.executionHistory.slice(-3);
+                for (const entry of recent) {
+                    console.log(chalk.gray(`    • ${entry}`));
+                }
+            }
+            console.log();
+            return true; // Continue loop
+        },
+        name: 'status',
+    },
+    {
+        description: 'List all persisted sessions',
+        async handler(_args, agent) {
+            console.log('\n' + chalk.bold.cyan('📋 Available Sessions:'));
+            console.log(chalk.cyan('─'.repeat(60)));
+            const sessionIds = await agent.listPersistedSessions();
+            if (sessionIds.length === 0) {
+                console.log(chalk.gray('  No sessions found'));
+                console.log();
+                return true;
+            }
+            // Load metadata for each session and sort by last activity
+            const sessions = [];
+            for (const sessionId of sessionIds) {
+                // eslint-disable-next-line no-await-in-loop -- Sequential metadata loading required
+                const metadata = await agent.getSessionMetadata(sessionId);
+                if (metadata) {
+                    sessions.push(metadata);
+                }
+            }
+            // Sort by last activity (most recent first)
+            sessions.sort((a, b) => b.lastActivity - a.lastActivity);
+            // Display sessions
+            for (const session of sessions) {
+                const timeAgo = formatTimeAgo(session.lastActivity);
+                console.log(chalk.green(`  • ${session.sessionId}`));
+                console.log(chalk.white(`    ${session.messageCount} messages, ${timeAgo}`));
+            }
+            console.log();
+            return true; // Continue loop
+        },
+        name: 'sessions',
+    },
+    {
+        description: 'Delete a session',
+        async handler(args, agent) {
+            if (args.length === 0) {
+                console.log('\n' + chalk.red('❌ Session ID is required'));
+                console.log(chalk.yellow('Usage: /delete <sessionId>'));
+                console.log();
+                return true;
+            }
+            const sessionId = args[0];
+            // Check if session exists
+            const metadata = await agent.getSessionMetadata(sessionId);
+            if (!metadata) {
+                console.log('\n' + chalk.red(`❌ Session '${sessionId}' not found`));
+                console.log();
+                return true;
+            }
+            // Delete the session
+            const deleted = await agent.deleteSession(sessionId);
+            if (deleted) {
+                console.log('\n' + chalk.green(`✓ Deleted session: ${sessionId}`));
+            }
+            else {
+                console.log('\n' + chalk.yellow(`⚠️  Session '${sessionId}' was not in memory`));
+            }
+            console.log();
+            return true; // Continue loop
+        },
+        name: 'delete',
+        usage: '/delete <sessionId>',
+    },
+    {
+        aliases: ['quit', 'q'],
+        description: 'Exit interactive mode',
+        async handler() {
+            console.log('\n' + chalk.yellow('👋 Goodbye!'));
+            return false; // Exit loop
+        },
+        name: 'exit',
+    },
+];
+/**
+ * Get all available command names (including aliases) for autocomplete
+ *
+ * @returns Array of command names with '/' prefix
+ */
+export function getCommandNames() {
+    const names = [];
+    for (const cmd of INTERACTIVE_COMMANDS) {
+        names.push(`/${cmd.name}`);
+        if (cmd.aliases) {
+            for (const alias of cmd.aliases) {
+                names.push(`/${alias}`);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * 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 async function executeCommand(command, args, agent) {
+    // Find the command (including aliases)
+    const cmd = INTERACTIVE_COMMANDS.find((c) => c.name === command || (c.aliases && c.aliases.includes(command)));
+    if (!cmd) {
+        console.log('\n' + chalk.red(`❌ Unknown command: /${command}`));
+        console.log(chalk.yellow('Type /help to see available commands\n'));
+        return true; // Continue loop
+    }
+    try {
+        return await cmd.handler(args, agent); // Execute command handler
+    }
+    catch (error) {
+        console.error('\n' + chalk.red(`❌ Error executing command /${command}:`));
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        console.log();
+        return true; // Continue loop on error
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { ICipherAgent } from '../../core/interfaces/cipher/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/infra/cipher/interactive-loop.js

@@ -0,0 +1,352 @@
+/* eslint-disable unicorn/no-process-exit */
+/* eslint-disable n/no-process-exit */
+import chalk from 'chalk';
+import readline from 'node:readline';
+import { parseInput } from './command-parser.js';
+import { executeCommand } from './interactive-commands.js';
+/**
+ * Prompt user for input using readline
+ *
+ * @param rl - Readline interface
+ * @returns Promise resolving to user input
+ */
+function promptUser(rl) {
+    return new Promise((resolve, reject) => {
+        // Set the prompt and display it immediately
+        const prompt = chalk.cyan('💬 You: ');
+        rl.setPrompt(prompt);
+        rl.prompt();
+        // Listen for line event instead of using question()
+        // This ensures the prompt appears immediately
+        const lineHandler = (answer) => {
+            rl.removeListener('line', lineHandler);
+            rl.removeListener('close', closeHandler);
+            resolve(answer);
+        };
+        const closeHandler = () => {
+            rl.removeListener('line', lineHandler);
+            rl.removeListener('close', closeHandler);
+            reject(new Error('Readline closed unexpectedly'));
+        };
+        rl.on('line', lineHandler);
+        rl.on('close', closeHandler);
+    });
+}
+/**
+ * Display welcome message for interactive mode
+ *
+ * @param sessionId - Session identifier
+ * @param model - LLM model name
+ * @param eventBus - Event bus to emit UI events
+ */
+function displayWelcome(sessionId, model, eventBus) {
+    if (eventBus) {
+        eventBus.emit('cipher:ui', {
+            context: { model, sessionId },
+            type: 'banner',
+        });
+    }
+}
+/**
+ * Format and display AI response
+ *
+ * @param response - AI response text
+ * @param eventBus - Event bus to emit UI events
+ */
+function displayResponse(response, eventBus) {
+    if (eventBus) {
+        eventBus.emit('cipher:ui', {
+            message: response,
+            type: 'response',
+        });
+    }
+}
+/**
+ * Safely clear the current terminal line
+ * Uses carriage return and spaces instead of ANSI codes to avoid rendering issues
+ */
+function clearTerminalLine() {
+    // Clear line by overwriting with spaces, then return to start
+    // Use terminal width or 200 chars (enough for long error messages)
+    const width = process.stdout.columns || 200;
+    process.stdout.write('\r' + ' '.repeat(width) + '\r');
+}
+/**
+ * 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 function displayInfo(message, clear = false) {
+    if (clear) {
+        // Clear the current line completely
+        clearTerminalLine();
+    }
+    else {
+        // Clear current line (spinner), write message, then newline to persist it
+        clearTerminalLine();
+        // Don't use gray - use default color for better visibility
+        process.stdout.write(message + '\n');
+    }
+}
+/**
+ * Setup event listeners for spinner and error handling
+ */
+function setupEventListeners(eventBus, spinnerState) {
+    const { frames: spinnerFrames, indexRef: spinnerIndexRef, isExecutingRef, ref: spinnerRef } = spinnerState;
+    // Thinking event - start spinner
+    eventBus.on('llmservice:thinking', () => {
+        // Only start spinner if currently executing and not already running
+        if (isExecutingRef.value && !spinnerRef.current) {
+            // Start animated spinner
+            spinnerRef.current = setInterval(() => {
+                clearTerminalLine();
+                process.stdout.write(chalk.gray(`💭 Agent thinking ${spinnerFrames[spinnerIndexRef.value]}`));
+                spinnerIndexRef.value = (spinnerIndexRef.value + 1) % spinnerFrames.length;
+            }, 80);
+        }
+    });
+    // Response event - clear spinner
+    eventBus.on('llmservice:response', () => {
+        if (spinnerRef.current) {
+            clearInterval(spinnerRef.current);
+            spinnerRef.current = null;
+            clearTerminalLine();
+        }
+    });
+    // Tool call event - clear spinner before tool execution
+    eventBus.on('llmservice:toolCall', () => {
+        if (spinnerRef.current) {
+            clearInterval(spinnerRef.current);
+            spinnerRef.current = null;
+            clearTerminalLine();
+        }
+    });
+    // Error event - SINGLE POINT where ALL errors are displayed
+    // Clear spinner and display formatted error message
+    eventBus.on('llmservice:error', (payload) => {
+        // Stop spinner first
+        if (spinnerRef.current) {
+            clearInterval(spinnerRef.current);
+            spinnerRef.current = null;
+            clearTerminalLine();
+        }
+        // Display error message (already formatted with ❌ from gRPC layer)
+        process.stdout.write('\n' + chalk.red(payload.error) + '\n\n');
+    });
+    // cipher:ui event - handle UI events (welcome banner, responses, etc.)
+    eventBus.on('cipher:ui', (payload) => {
+        switch (payload.type) {
+            case 'banner': {
+                // Welcome banner
+                const { model, sessionId } = payload.context;
+                console.log('\n' + chalk.cyan('═'.repeat(60)));
+                console.log(chalk.bold.cyan('🤖 CipherAgent Interactive Mode'));
+                console.log(chalk.cyan('═'.repeat(60)));
+                console.log(chalk.gray(`Model: ${model}`));
+                console.log(chalk.gray(`Session: ${sessionId}`));
+                console.log(chalk.yellow('\nType /help for available commands'));
+                console.log(chalk.cyan('─'.repeat(60)) + '\n');
+                break;
+            }
+            case 'help': {
+                // Help message
+                if (payload.message) {
+                    console.log(chalk.yellow(`ℹ ${payload.message}`));
+                }
+                break;
+            }
+            case 'response': {
+                // AI response
+                if (payload.message) {
+                    console.log('\n' + chalk.rgb(255, 165, 0)('─'.repeat(60)));
+                    console.log(chalk.bold.rgb(255, 165, 0)('🤖 AI Response:'));
+                    console.log(chalk.rgb(255, 165, 0)('─'.repeat(60)));
+                    console.log(chalk.white(payload.message));
+                    console.log(chalk.rgb(255, 165, 0)('─'.repeat(60)) + '\n');
+                }
+                break;
+            }
+            case 'shutdown': {
+                // Shutdown message
+                if (payload.message) {
+                    console.log(chalk.gray(`✓ ${payload.message}`));
+                }
+                break;
+            }
+            // No default case needed - other UI types can be ignored
+        }
+    });
+    // cipher:log event - handle structured logging
+    // NOTE: Skip 'error' level - those are handled by llmservice:error to avoid duplicates
+    eventBus.on('cipher:log', (payload) => {
+        const prefix = payload.source ? `[${payload.source}] ` : '';
+        const message = `${prefix}${payload.message}`;
+        switch (payload.level) {
+            case 'debug': {
+                console.log(chalk.gray(`🔍 ${message}`));
+                break;
+            }
+            case 'error': {
+                // Skip - llmservice:error handler displays errors to avoid duplicates
+                break;
+            }
+            case 'info': {
+                console.log(chalk.blue(`ℹ ${message}`));
+                break;
+            }
+            case 'warn': {
+                console.warn(chalk.yellow(`⚠ ${message}`));
+                break;
+            }
+        }
+    });
+}
+/**
+ * Stop and clear spinner if running
+ */
+function stopSpinner(spinnerRef) {
+    if (spinnerRef.current) {
+        clearInterval(spinnerRef.current);
+        spinnerRef.current = null;
+        clearTerminalLine();
+    }
+}
+/**
+ * Handle command execution
+ * @returns true to continue loop, false to exit
+ */
+async function handleCommand(command, args, agent, eventBus) {
+    if (!command) {
+        if (eventBus) {
+            eventBus.emit('cipher:ui', {
+                message: 'Type /help to see available commands',
+                type: 'help',
+            });
+        }
+        return true;
+    }
+    const shouldContinue = await executeCommand(command, args, agent);
+    return shouldContinue;
+}
+/**
+ * Execute user prompt with AI agent
+ */
+async function executePrompt(prompt, agent, state, eventBus) {
+    const { isExecutingRef, spinnerRef } = state;
+    try {
+        // Mark execution started - prevents late thinking events from starting spinner
+        isExecutingRef.value = true;
+        // Execute AI prompt
+        const response = await agent.execute(prompt);
+        // Mark execution finished - no more spinners allowed
+        isExecutingRef.value = false;
+        // Stop spinner immediately after execution completes (redundant safety check)
+        stopSpinner(spinnerRef);
+        // Display response
+        displayResponse(response, eventBus);
+        // Final safety cleanup - ensure no spinner is running after response displayed
+        stopSpinner(spinnerRef);
+    }
+    catch {
+        // Mark execution finished on error
+        isExecutingRef.value = false;
+        // Error is already handled by llmservice:error event listener
+        // No need to display here - just clean up state
+    }
+}
+/**
+ * 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 async function startInteractiveLoop(agent, options) {
+    // Display welcome message
+    displayWelcome(options?.sessionId ?? 'cipher-agent-session', options?.model ?? 'gemini-2.5-pro', options?.eventBus);
+    // Create readline interface
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    // Create custom spinner using carriage return for clean output
+    const spinnerRef = { current: null };
+    const spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    const spinnerIndexRef = { value: 0 };
+    const isExecutingRef = { value: false };
+    // Setup event listeners
+    if (options?.eventBus) {
+        setupEventListeners(options.eventBus, {
+            frames: spinnerFrames,
+            indexRef: spinnerIndexRef,
+            isExecutingRef,
+            ref: spinnerRef,
+        });
+    }
+    const isExitingRef = { value: false };
+    const exitEventHandler = async () => {
+        stopSpinner(spinnerRef);
+        await cleanup(agent, rl, isExitingRef, options?.eventBus);
+        process.exit(0);
+    };
+    rl.on('SIGINT', exitEventHandler);
+    process.on('SIGTERM', exitEventHandler);
+    try {
+        // Main interactive loop
+        while (true) {
+            // Get user input
+            // eslint-disable-next-line no-await-in-loop -- Sequential user input required for interactive loop
+            const userInput = await promptUser(rl);
+            // Parse input
+            const parsed = parseInput(userInput);
+            if (parsed.type === 'command') {
+                // Handle slash command
+                // eslint-disable-next-line no-await-in-loop -- Sequential command execution required for interactive loop
+                const shouldContinue = await handleCommand(parsed.command, parsed.args || [], agent, options?.eventBus);
+                if (!shouldContinue) {
+                    // Exit command was called
+                    break;
+                }
+                continue;
+            }
+            // Handle regular prompt - pass to AI
+            if (!parsed.rawInput.trim()) {
+                // Empty input, skip
+                continue;
+            }
+            // Execute AI prompt
+            // eslint-disable-next-line no-await-in-loop -- Sequential agent execution required for interactive loop
+            await executePrompt(parsed.rawInput, agent, { isExecutingRef, spinnerRef }, options?.eventBus);
+        }
+    }
+    finally {
+        stopSpinner(spinnerRef);
+        await cleanup(agent, rl, isExitingRef, options?.eventBus);
+        rl.off('SIGINT', exitEventHandler);
+        process.off('SIGTERM', exitEventHandler);
+    }
+}
+/**
+ * Cleans up resources when interactive loop is exiting.
+ * @param agent CipherAgent instance to stop
+ * @param rl Readline interface to close
+ * @param isExitingRef Reference object to track if exiting
+ * @param isExitingRef.value Boolean flag indicating if cleanup is in progress
+ */
+const cleanup = async (agent, rl, isExitingRef, eventBus) => {
+    if (isExitingRef.value)
+        return;
+    isExitingRef.value = true;
+    if (eventBus) {
+        eventBus.emit('cipher:ui', {
+            message: 'Shutting down...',
+            type: 'shutdown',
+        });
+    }
+    rl.close();
+    console.log(chalk.gray('✓ Cleanup complete'));
+};

package/dist/infra/cipher/llm/context/async-mutex.d.ts

@@ -0,0 +1,59 @@
+/**
+ * AsyncMutex - Simple asynchronous mutex for thread safety in parallel execution.
+ *
+ * Provides mutual exclusion for async operations, ensuring that only one
+ * operation can execute the critical section at a time. Uses a FIFO queue
+ * to ensure fairness among waiting operations.
+ *
+ * @example
+ * ```typescript
+ * const mutex = new AsyncMutex()
+ *
+ * // Option 1: Manual acquire/release
+ * await mutex.acquire()
+ * try {
+ *   // Critical section
+ * } finally {
+ *   mutex.release()
+ * }
+ *
+ * // Option 2: Using withLock (recommended)
+ * await mutex.withLock(async () => {
+ *   // Critical section - automatically released
+ * })
+ * ```
+ */
+export declare class AsyncMutex {
+    private locked;
+    private readonly queue;
+    /**
+     * Acquire the mutex lock.
+     * If the mutex is already locked, the caller will wait in a FIFO queue.
+     *
+     * @returns Promise that resolves when the lock is acquired
+     */
+    acquire(): Promise<void>;
+    /**
+     * Get the number of operations waiting for the lock.
+     */
+    getQueueLength(): number;
+    /**
+     * Check if the mutex is currently locked.
+     */
+    isLocked(): boolean;
+    /**
+     * Release the mutex lock.
+     * If there are waiting operations, the next one in the queue will be granted the lock.
+     *
+     * @throws Error if the mutex is not currently locked
+     */
+    release(): void;
+    /**
+     * Execute a function with the mutex lock held.
+     * The lock is automatically released when the function completes or throws.
+     *
+     * @param fn - Async function to execute with the lock held
+     * @returns The result of the function
+     */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+}