byterover-cli 0.2.0 → 0.3.0

package/dist/infra/cipher/process/process-service.js

@@ -0,0 +1,439 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { ProcessError } from '../../../core/domain/cipher/errors/process-error.js';
+import { CommandValidator } from './command-validator.js';
+/**
+ * Default timeout for foreground commands (milliseconds).
+ */
+const DEFAULT_TIMEOUT = 120_000; // 2 minutes
+/**
+ * Default maximum timeout (milliseconds).
+ */
+const DEFAULT_MAX_TIMEOUT = 600_000; // 10 minutes
+/**
+ * Default maximum concurrent background processes.
+ */
+const DEFAULT_MAX_CONCURRENT_PROCESSES = 5;
+/**
+ * Default maximum output buffer size (bytes).
+ */
+const DEFAULT_MAX_OUTPUT_BUFFER = 1024 * 1024; // 1MB
+/**
+ * Process service implementation.
+ *
+ * Provides secure command execution with:
+ * - Multi-layer security validation
+ * - Foreground and background execution
+ * - Output buffering with size limits
+ * - Timeout management with signal escalation
+ * - Working directory confinement
+ * - Approval system integration
+ */
+export class ProcessService {
+    backgroundProcesses = new Map();
+    commandValidator;
+    config;
+    initialized = false;
+    /**
+     * Creates a new process service.
+     *
+     * @param config - Process configuration (partial, will be merged with defaults)
+     */
+    constructor(config = {}) {
+        // Merge with defaults
+        this.config = {
+            allowedCommands: config.allowedCommands || [],
+            blockedCommands: config.blockedCommands || [],
+            environment: config.environment || {},
+            maxConcurrentProcesses: config.maxConcurrentProcesses || DEFAULT_MAX_CONCURRENT_PROCESSES,
+            maxOutputBuffer: config.maxOutputBuffer || DEFAULT_MAX_OUTPUT_BUFFER,
+            maxTimeout: config.maxTimeout || DEFAULT_MAX_TIMEOUT,
+            securityLevel: config.securityLevel || 'moderate',
+            workingDirectory: config.workingDirectory,
+        };
+        this.commandValidator = new CommandValidator({
+            allowedCommands: this.config.allowedCommands,
+            blockedCommands: this.config.blockedCommands,
+            securityLevel: this.config.securityLevel,
+        });
+    }
+    /**
+     * Clean up completed background processes older than 1 hour.
+     */
+    async cleanup() {
+        const now = Date.now();
+        const CLEANUP_AGE = 3_600_000; // 1 hour in milliseconds
+        for (const [processId, bgProcess] of this.backgroundProcesses.entries()) {
+            if (bgProcess.status !== 'running' && bgProcess.completedAt) {
+                const age = now - bgProcess.completedAt.getTime();
+                if (age > CLEANUP_AGE) {
+                    this.backgroundProcesses.delete(processId);
+                }
+            }
+        }
+    }
+    /**
+     * Execute a shell command.
+     *
+     * @param command - Shell command to execute
+     * @param options - Execution options
+     * @returns Process result or handle
+     */
+    async executeCommand(command, options = {}) {
+        if (!this.initialized) {
+            throw ProcessError.notInitialized();
+        }
+        // Validate command
+        const validation = this.commandValidator.validateCommand(command);
+        if (!validation.isValid) {
+            throw ProcessError.invalidCommand(command, validation.error);
+        }
+        const { normalizedCommand } = validation;
+        // Validate timeout
+        const timeout = options.timeout || DEFAULT_TIMEOUT;
+        if (timeout > this.config.maxTimeout) {
+            throw ProcessError.invalidCommand(command, `Timeout ${timeout}ms exceeds maximum ${this.config.maxTimeout}ms`);
+        }
+        // Resolve working directory
+        const cwd = this.resolveSafeCwd(options.cwd);
+        // Merge environment variables
+        const env = {};
+        for (const [key, value] of Object.entries({
+            ...process.env,
+            ...this.config.environment,
+            ...options.env,
+        })) {
+            if (value !== undefined) {
+                env[key] = value;
+            }
+        }
+        // Execute based on mode
+        if (options.runInBackground) {
+            return this.executeInBackground(normalizedCommand, {
+                cwd,
+                description: options.description,
+                env,
+                timeout,
+            });
+        }
+        return this.executeForeground(normalizedCommand, { cwd, env, timeout });
+    }
+    /**
+     * Get the current process configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get output from a background process.
+     *
+     * @param processId - Unique process identifier
+     * @returns Process output
+     */
+    async getProcessOutput(processId) {
+        const bgProcess = this.backgroundProcesses.get(processId);
+        if (!bgProcess) {
+            throw ProcessError.processNotFound(processId);
+        }
+        // Join output chunks
+        const stdout = bgProcess.outputBuffer.stdout.join('');
+        const stderr = bgProcess.outputBuffer.stderr.join('');
+        // Clear buffer (destructive read)
+        bgProcess.outputBuffer.stdout = [];
+        bgProcess.outputBuffer.stderr = [];
+        bgProcess.outputBuffer.lastRead = Date.now();
+        bgProcess.outputBuffer.bytesUsed = 0;
+        // Calculate duration if completed
+        let duration;
+        if (bgProcess.completedAt) {
+            duration = bgProcess.completedAt.getTime() - bgProcess.startedAt.getTime();
+        }
+        return {
+            duration,
+            exitCode: bgProcess.exitCode,
+            status: bgProcess.status,
+            stderr,
+            stdout,
+        };
+    }
+    /**
+     * Initialize the process service.
+     */
+    async initialize() {
+        // Clear any stale processes
+        this.backgroundProcesses.clear();
+        this.initialized = true;
+    }
+    /**
+     * Terminate a background process.
+     *
+     * @param processId - Unique process identifier
+     */
+    async killProcess(processId) {
+        const bgProcess = this.backgroundProcesses.get(processId);
+        if (!bgProcess) {
+            throw ProcessError.processNotFound(processId);
+        }
+        if (bgProcess.status !== 'running') {
+            // Process already terminated
+            return;
+        }
+        try {
+            // Send SIGTERM
+            bgProcess.child.kill('SIGTERM');
+            // Wait 5 seconds, then escalate to SIGKILL
+            setTimeout(() => {
+                if (bgProcess.child.exitCode === null) {
+                    bgProcess.child.kill('SIGKILL');
+                }
+            }, 5000);
+        }
+        catch (error) {
+            throw ProcessError.killFailed(processId, error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * List all background processes.
+     */
+    async listProcesses() {
+        const processes = [];
+        for (const bgProcess of this.backgroundProcesses.values()) {
+            processes.push({
+                command: bgProcess.command,
+                completedAt: bgProcess.completedAt,
+                description: bgProcess.description,
+                exitCode: bgProcess.exitCode,
+                pid: bgProcess.child.pid,
+                processId: bgProcess.processId,
+                startedAt: bgProcess.startedAt,
+                status: bgProcess.status,
+            });
+        }
+        return processes;
+    }
+    /**
+     * Execute command in foreground (wait for completion).
+     *
+     * @param command - Normalized command to execute
+     * @param options - Execution options
+     * @param options.cwd - Working directory
+     * @param options.env - Environment variables
+     * @param options.timeout - Timeout in milliseconds
+     * @returns Process result with stdout, stderr, exit code, duration
+     */
+    async executeForeground(command, options) {
+        return new Promise((resolve, reject) => {
+            const startTime = Date.now();
+            let stdout = '';
+            let stderr = '';
+            let killed = false;
+            let closed = false;
+            // Spawn process
+            const child = spawn(command, {
+                cwd: options.cwd,
+                env: options.env,
+                shell: true,
+            });
+            // Collect stdout
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            // Collect stderr
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            // Handle timeout
+            const timeoutHandle = setTimeout(() => {
+                if (!closed) {
+                    killed = true;
+                    child.kill('SIGTERM');
+                    // Escalate to SIGKILL after 5 seconds
+                    setTimeout(() => {
+                        if (!closed && child.exitCode === null) {
+                            child.kill('SIGKILL');
+                        }
+                    }, 5000);
+                }
+            }, options.timeout);
+            // Handle process exit
+            child.on('close', (code, signal) => {
+                closed = true;
+                clearTimeout(timeoutHandle);
+                const duration = Date.now() - startTime;
+                if (killed) {
+                    reject(ProcessError.timeout(command, options.timeout));
+                    return;
+                }
+                if (signal) {
+                    reject(ProcessError.executionFailed(command, `Process terminated by signal: ${signal}`));
+                    return;
+                }
+                resolve({
+                    duration,
+                    exitCode: code ?? 1,
+                    stderr,
+                    stdout,
+                });
+            });
+            // Handle spawn errors
+            child.on('error', (error) => {
+                clearTimeout(timeoutHandle);
+                if (error.code === 'ENOENT') {
+                    reject(ProcessError.commandNotFound(command));
+                }
+                else if (error.code === 'EACCES') {
+                    reject(ProcessError.permissionDenied(command));
+                }
+                else {
+                    reject(ProcessError.executionFailed(command, error.message));
+                }
+            });
+        });
+    }
+    /**
+     * Execute command in background (return immediately).
+     *
+     * @param command - Normalized command to execute
+     * @param options - Execution options
+     * @param options.cwd - Working directory
+     * @param options.description - Optional description
+     * @param options.env - Environment variables
+     * @param options.timeout - Timeout in milliseconds
+     * @returns Process handle with processId
+     */
+    async executeInBackground(command, options) {
+        // Check concurrent process limit
+        const runningCount = [...this.backgroundProcesses.values()].filter(p => p.status === 'running').length;
+        if (runningCount >= this.config.maxConcurrentProcesses) {
+            throw ProcessError.tooManyProcesses(runningCount, this.config.maxConcurrentProcesses);
+        }
+        // Generate unique process ID
+        const processId = randomBytes(4).toString('hex');
+        // Initialize output buffer
+        const outputBuffer = {
+            bytesUsed: 0,
+            complete: false,
+            lastRead: Date.now(),
+            stderr: [],
+            stdout: [],
+            truncated: false,
+        };
+        // Spawn process
+        const child = spawn(command, {
+            cwd: options.cwd,
+            detached: false, // Process dies with parent
+            env: options.env,
+            shell: true,
+        });
+        const startedAt = new Date();
+        // Create background process entry
+        const bgProcess = {
+            child,
+            command,
+            description: options.description,
+            outputBuffer,
+            processId,
+            startedAt,
+            status: 'running',
+        };
+        this.backgroundProcesses.set(processId, bgProcess);
+        // Collect stdout with buffer limit
+        child.stdout?.on('data', (data) => {
+            const chunk = data.toString();
+            const chunkBytes = Buffer.byteLength(chunk, 'utf8');
+            if (outputBuffer.bytesUsed + chunkBytes <= this.config.maxOutputBuffer) {
+                outputBuffer.stdout.push(chunk);
+                outputBuffer.bytesUsed += chunkBytes;
+            }
+            else if (!outputBuffer.truncated) {
+                outputBuffer.truncated = true;
+                // Note: In production, you might want to log this
+            }
+        });
+        // Collect stderr with buffer limit
+        child.stderr?.on('data', (data) => {
+            const chunk = data.toString();
+            const chunkBytes = Buffer.byteLength(chunk, 'utf8');
+            if (outputBuffer.bytesUsed + chunkBytes <= this.config.maxOutputBuffer) {
+                outputBuffer.stderr.push(chunk);
+                outputBuffer.bytesUsed += chunkBytes;
+            }
+            else if (!outputBuffer.truncated) {
+                outputBuffer.truncated = true;
+                // Note: In production, you might want to log this
+            }
+        });
+        // Handle process completion
+        child.on('close', (code, signal) => {
+            outputBuffer.complete = true;
+            bgProcess.completedAt = new Date();
+            bgProcess.exitCode = code ?? 1;
+            if (signal) {
+                bgProcess.status = 'failed';
+            }
+            else if (code === 0) {
+                bgProcess.status = 'completed';
+            }
+            else {
+                bgProcess.status = 'failed';
+            }
+        });
+        // Handle spawn errors
+        child.on('error', () => {
+            bgProcess.status = 'failed';
+            bgProcess.completedAt = new Date();
+            bgProcess.exitCode = 1;
+            outputBuffer.complete = true;
+        });
+        // Set timeout handler
+        const killTimer = setTimeout(() => {
+            if (bgProcess.status === 'running') {
+                child.kill('SIGTERM');
+                // Escalate to SIGKILL after 5 seconds
+                setTimeout(() => {
+                    if (bgProcess.status === 'running') {
+                        child.kill('SIGKILL');
+                    }
+                }, 5000);
+            }
+        }, options.timeout);
+        // Clear timeout when process completes
+        child.on('close', () => {
+            clearTimeout(killTimer);
+        });
+        // Return handle immediately
+        return {
+            command,
+            description: options.description,
+            pid: child.pid,
+            processId,
+            startedAt,
+        };
+    }
+    /**
+     * Resolve and validate working directory.
+     *
+     * Ensures the directory is within the configured base directory
+     * and prevents directory traversal attacks.
+     *
+     * @param cwd - Optional working directory (relative or absolute)
+     * @returns Safe absolute working directory
+     */
+    resolveSafeCwd(cwd) {
+        const baseDir = this.config.workingDirectory || process.cwd();
+        // If no cwd specified, use base directory
+        if (!cwd) {
+            return baseDir;
+        }
+        // Resolve to absolute path
+        const candidatePath = isAbsolute(cwd) ? resolve(cwd) : resolve(baseDir, cwd);
+        // Check if path is within base directory
+        const relativePath = relative(baseDir, candidatePath);
+        const isOutsideBase = relativePath.startsWith('..') || isAbsolute(relativePath);
+        if (isOutsideBase) {
+            throw ProcessError.invalidWorkingDirectory(cwd, `Working directory must be within ${baseDir}`);
+        }
+        return candidatePath;
+    }
+}

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

@@ -0,0 +1,80 @@
+import type { Message } from '../../../core/domain/cipher/session/types.js';
+import type { CipherAgentServices, SessionServices } from '../../../core/interfaces/cipher/cipher-services.js';
+import type { IChatSession } from '../../../core/interfaces/cipher/i-chat-session.js';
+import type { ExecutionContext } from '../../../core/interfaces/cipher/i-cipher-agent.js';
+import type { ILLMService } from '../../../core/interfaces/cipher/i-llm-service.js';
+import { SessionEventBus } from '../events/event-emitter.js';
+/**
+ * Chat session implementation.
+ *
+ * Following Dexto's pattern: ChatSession owns session-specific services
+ * (LLM, EventBus) and receives shared services (ToolManager, SystemPromptManager).
+ *
+ * The LLM service handles:
+ * - Message history (via ContextManager)
+ * - Agentic loop
+ * - Tool execution
+ *
+ * This session provides:
+ * - Session isolation
+ * - Cancellation support
+ * - Event forwarding to agent bus
+ * - Proper cleanup/disposal
+ */
+export declare class ChatSession implements IChatSession {
+    readonly eventBus: SessionEventBus;
+    readonly id: string;
+    private currentController?;
+    private readonly forwarders;
+    private readonly llmService;
+    private readonly sharedServices;
+    /**
+     * Creates a new chat session
+     *
+     * @param id - Unique session identifier
+     * @param sharedServices - Shared services from CipherAgent
+     * @param sessionServices - Session-specific services (LLM, EventBus)
+     */
+    constructor(id: string, sharedServices: CipherAgentServices, sessionServices: SessionServices);
+    /**
+     * Cancel the current operation.
+     */
+    cancel(): void;
+    /**
+     * Dispose of the session and clean up resources.
+     * Removes event listeners to prevent memory leaks.
+     */
+    dispose(): void;
+    /**
+     * Get the conversation history.
+     */
+    getHistory(): Message[];
+    /**
+     * Get the LLM service for direct access to context manager.
+     * Useful for pre-loading conversation history in JSON input mode.
+     */
+    getLLMService(): ILLMService;
+    /**
+     * Get the number of messages in the conversation.
+     */
+    getMessageCount(): number;
+    /**
+     * Reset the conversation history.
+     */
+    reset(): void;
+    /**
+     * Send a message and get a response.
+     * Delegates to the LLM service which handles the agentic loop.
+     */
+    run(input: string, options?: {
+        executionContext?: ExecutionContext;
+        mode?: 'autonomous' | 'default' | 'query';
+    }): Promise<string>;
+    /**
+     * Setup automatic event forwarding from SessionEventBus to AgentEventBus.
+     * All session events are forwarded with sessionId added to the payload.
+     *
+     * Following Dexto's pattern: event forwarding is built into the session.
+     */
+    private setupEventForwarding;
+}

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

@@ -0,0 +1,165 @@
+import { LLMError, SessionCancelledError } from '../../../core/domain/cipher/errors/session-error.js';
+// List of all session events that should be forwarded to agent bus
+const SESSION_EVENT_NAMES = [
+    'llmservice:thinking',
+    'llmservice:chunk',
+    'llmservice:response',
+    'llmservice:toolCall',
+    'llmservice:toolResult',
+    'llmservice:error',
+    'llmservice:unsupportedInput',
+];
+/**
+ * Chat session implementation.
+ *
+ * Following Dexto's pattern: ChatSession owns session-specific services
+ * (LLM, EventBus) and receives shared services (ToolManager, SystemPromptManager).
+ *
+ * The LLM service handles:
+ * - Message history (via ContextManager)
+ * - Agentic loop
+ * - Tool execution
+ *
+ * This session provides:
+ * - Session isolation
+ * - Cancellation support
+ * - Event forwarding to agent bus
+ * - Proper cleanup/disposal
+ */
+export class ChatSession {
+    eventBus;
+    id;
+    currentController;
+    forwarders = new Map();
+    llmService;
+    sharedServices;
+    /**
+     * Creates a new chat session
+     *
+     * @param id - Unique session identifier
+     * @param sharedServices - Shared services from CipherAgent
+     * @param sessionServices - Session-specific services (LLM, EventBus)
+     */
+    constructor(id, sharedServices, sessionServices) {
+        this.id = id;
+        this.sharedServices = sharedServices;
+        this.eventBus = sessionServices.sessionEventBus;
+        this.llmService = sessionServices.llmService;
+        // Setup event forwarding from session bus to agent bus
+        this.setupEventForwarding();
+    }
+    /**
+     * Cancel the current operation.
+     */
+    cancel() {
+        if (this.currentController) {
+            this.currentController.abort();
+        }
+    }
+    /**
+     * Dispose of the session and clean up resources.
+     * Removes event listeners to prevent memory leaks.
+     */
+    dispose() {
+        // Remove all event forwarders
+        for (const [eventName, forwarder] of this.forwarders.entries()) {
+            this.eventBus.off(eventName, forwarder);
+        }
+        this.forwarders.clear();
+    }
+    /**
+     * Get the conversation history.
+     */
+    getHistory() {
+        // Get history from service's context manager
+        const contextManager = this.llmService.getContextManager();
+        const internalMessages = contextManager.getMessages();
+        // Convert to session Message format
+        return internalMessages.map((msg) => ({
+            content: typeof msg.content === 'string' ? msg.content : '',
+            role: msg.role,
+            timestamp: Date.now(), // Internal messages don't have timestamps
+            toolCallId: msg.toolCallId,
+            toolCalls: msg.toolCalls?.map((tc) => ({
+                arguments: JSON.parse(tc.function.arguments),
+                id: tc.id,
+                name: tc.function.name,
+            })),
+            toolName: msg.name,
+        }));
+    }
+    /**
+     * Get the LLM service for direct access to context manager.
+     * Useful for pre-loading conversation history in JSON input mode.
+     */
+    getLLMService() {
+        return this.llmService;
+    }
+    /**
+     * Get the number of messages in the conversation.
+     */
+    getMessageCount() {
+        const contextManager = this.llmService.getContextManager();
+        return contextManager.getMessages().length;
+    }
+    /**
+     * Reset the conversation history.
+     */
+    reset() {
+        const contextManager = this.llmService.getContextManager();
+        contextManager.clearHistory();
+        // Emit conversation reset event
+        this.sharedServices.agentEventBus.emit('cipher:conversationReset', {
+            sessionId: this.id,
+        });
+    }
+    /**
+     * Send a message and get a response.
+     * Delegates to the LLM service which handles the agentic loop.
+     */
+    async run(input, options) {
+        // Create abort controller for cancellation
+        this.currentController = new AbortController();
+        try {
+            // Delegate to service - it handles everything
+            const response = await this.llmService.completeTask(input, this.id, {
+                executionContext: options?.executionContext,
+                mode: options?.mode,
+                signal: this.currentController.signal,
+            });
+            return response;
+        }
+        catch (error) {
+            // Check if cancelled
+            if (this.currentController.signal.aborted) {
+                throw new SessionCancelledError(this.id);
+            }
+            // Wrap other errors - pass message as-is since it's already formatted
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new LLMError(errorMessage, this.id);
+        }
+        finally {
+            this.currentController = undefined;
+        }
+    }
+    /**
+     * Setup automatic event forwarding from SessionEventBus to AgentEventBus.
+     * All session events are forwarded with sessionId added to the payload.
+     *
+     * Following Dexto's pattern: event forwarding is built into the session.
+     */
+    setupEventForwarding() {
+        for (const eventName of SESSION_EVENT_NAMES) {
+            const forwarder = (payload) => {
+                // Add sessionId to payload
+                const payloadWithSession = payload && typeof payload === 'object' ? { ...payload, sessionId: this.id } : { sessionId: this.id };
+                // Forward to agent bus - eventName is properly typed from SESSION_EVENT_NAMES
+                this.sharedServices.agentEventBus.emit(eventName, payloadWithSession);
+            };
+            // Track forwarder for cleanup
+            this.forwarders.set(eventName, forwarder);
+            // Register listener on session bus - eventName is properly typed from SESSION_EVENT_NAMES
+            this.eventBus.on(eventName, forwarder);
+        }
+    }
+}

package/dist/infra/cipher/session/index.d.ts

@@ -0,0 +1,6 @@
+export { LLMError, MaxIterationsExceededError, SessionCancelledError, SessionError, SessionNotInitializedError, } from '../../../core/domain/cipher/errors/session-error.js';
+export type { LLMResponse, Message, MessageRole, SessionConfig, ToolCall } from '../../../core/domain/cipher/session/types.js';
+export type { IChatSession } from '../../../core/interfaces/cipher/i-chat-session.js';
+export type { ILLMService } from '../../../core/interfaces/cipher/i-llm-service.js';
+export { ChatSession } from './chat-session.js';
+export { SessionManager } from './session-manager.js';

package/dist/infra/cipher/session/index.js

@@ -0,0 +1,5 @@
+// Session errors
+export { LLMError, MaxIterationsExceededError, SessionCancelledError, SessionError, SessionNotInitializedError, } from '../../../core/domain/cipher/errors/session-error.js';
+export { ChatSession } from './chat-session.js';
+// Session manager
+export { SessionManager } from './session-manager.js';