byterover-cli 0.4.0 → 1.0.0

package/dist/infra/core/task-processor.js

@@ -0,0 +1,115 @@
+import { NoOpLogger } from '../../core/interfaces/cipher/i-logger.js';
+/**
+ * TaskProcessor - Coordinates task execution with injected executors.
+ *
+ * Architecture:
+ * - TaskProcessor receives single agent reference via setAgent()
+ * - TaskProcessor passes agent to Executor.executeWithAgent()
+ * - Executor handles execution (validation, prompt building)
+ * - Event streaming handled by agent-worker (subscribes to agentEventBus)
+ *
+ * Flow: agent-worker → TaskProcessor.process() → Executor.executeWithAgent()
+ */
+export class TaskProcessor {
+    /**
+     * Single CipherAgent reference from agent-worker.
+     */
+    agent;
+    curateExecutor;
+    logger;
+    queryExecutor;
+    /** Track running tasks for cancellation */
+    runningTasks = new Map();
+    constructor(config) {
+        this.logger = config.logger ?? new NoOpLogger();
+        this.curateExecutor = config.curateExecutor;
+        this.queryExecutor = config.queryExecutor;
+    }
+    /**
+     * Cancel a running task.
+     */
+    cancel(taskId) {
+        const task = this.runningTasks.get(taskId);
+        if (task) {
+            task.abort();
+            this.runningTasks.delete(taskId);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if a task is running.
+     */
+    isRunning(taskId) {
+        return this.runningTasks.has(taskId);
+    }
+    /**
+     * Process a task and return the result.
+     *
+     * Architecture:
+     * - Calls Executor.executeWithAgent() with long-lived agent
+     * - Returns result string
+     * - Event streaming handled by agent-worker (agentEventBus)
+     */
+    async process(input) {
+        const { taskId, type } = input;
+        this.logger.info('Processing task', { taskId, type });
+        if (!this.agent) {
+            throw new Error('Agent not configured. Call setAgent() first.');
+        }
+        // Track task for cancellation
+        let aborted = false;
+        const abort = () => {
+            aborted = true;
+        };
+        this.runningTasks.set(taskId, { abort });
+        try {
+            const result = await this.executeWithAgent(input);
+            if (aborted) {
+                throw new Error('Task cancelled');
+            }
+            this.logger.info('Task completed', { taskId });
+            return result;
+        }
+        finally {
+            this.runningTasks.delete(taskId);
+        }
+    }
+    /**
+     * Set agent reference from agent-worker.
+     */
+    setAgent(agent) {
+        this.agent = agent;
+        this.logger.debug('Agent reference set');
+    }
+    /**
+     * Execute task with the injected agent.
+     */
+    async executeWithAgent(input) {
+        const { content, taskId, type } = input;
+        if (!this.agent) {
+            throw new Error('Agent not configured');
+        }
+        this.logger.debug('Executing with agent', { taskId, type });
+        switch (type) {
+            case 'curate': {
+                // Agent uses its default session (Single-Session pattern)
+                return this.curateExecutor.executeWithAgent(this.agent, {
+                    content,
+                    files: input.files,
+                    taskId,
+                });
+            }
+            case 'query': {
+                // Agent uses its default session (Single-Session pattern)
+                return this.queryExecutor.executeWithAgent(this.agent, { query: content, taskId });
+            }
+        }
+    }
+}
+/**
+ * Create a new TaskProcessor instance.
+ */
+export function createTaskProcessor(config) {
+    return new TaskProcessor(config);
+}

package/dist/infra/instance/file-instance-discovery.d.ts

@@ -0,0 +1,31 @@
+import type { DiscoveryResult, IInstanceDiscovery } from '../../core/interfaces/instance/i-instance-discovery.js';
+import type { IInstanceManager } from '../../core/interfaces/instance/i-instance-manager.js';
+/**
+ * File-based implementation of IInstanceDiscovery.
+ *
+ * Implements walk-up directory tree algorithm to find running instances.
+ */
+export declare class FileInstanceDiscovery implements IInstanceDiscovery {
+    private readonly instanceManager;
+    constructor(instanceManager?: IInstanceManager);
+    /**
+     * Discovers a running instance starting from the given directory.
+     *
+     * Walk-up algorithm:
+     * 1. Start from `fromDir`
+     * 2. Check if .brv/instance.json exists
+     * 3. If yes, verify pid is alive
+     * 4. If no, walk up to parent directory
+     * 5. Repeat until root or found
+     */
+    discover(fromDir: string): Promise<DiscoveryResult>;
+    /**
+     * Finds the project root by walking up from a directory.
+     * Returns the directory containing .brv/ or undefined if not found.
+     */
+    findProjectRoot(fromDir: string): Promise<string | undefined>;
+    /**
+     * Checks if a directory exists.
+     */
+    private directoryExists;
+}

package/dist/infra/instance/file-instance-discovery.js

@@ -0,0 +1,84 @@
+import { access } from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import { BRV_DIR } from '../../constants.js';
+import { FileInstanceManager } from './file-instance-manager.js';
+import { isProcessAlive } from './process-utils.js';
+/**
+ * File-based implementation of IInstanceDiscovery.
+ *
+ * Implements walk-up directory tree algorithm to find running instances.
+ */
+export class FileInstanceDiscovery {
+    instanceManager;
+    constructor(instanceManager) {
+        this.instanceManager = instanceManager ?? new FileInstanceManager();
+    }
+    /**
+     * Discovers a running instance starting from the given directory.
+     *
+     * Walk-up algorithm:
+     * 1. Start from `fromDir`
+     * 2. Check if .brv/instance.json exists
+     * 3. If yes, verify pid is alive
+     * 4. If no, walk up to parent directory
+     * 5. Repeat until root or found
+     */
+    async discover(fromDir) {
+        const projectRoot = await this.findProjectRoot(fromDir);
+        if (!projectRoot) {
+            return { found: false, reason: 'no_instance' };
+        }
+        const instance = await this.instanceManager.load(projectRoot);
+        if (!instance) {
+            return { found: false, reason: 'no_instance' };
+        }
+        // Verify PID is alive (this is the only check we need)
+        if (!isProcessAlive(instance.pid)) {
+            return { found: false, reason: 'instance_crashed' };
+        }
+        return {
+            found: true,
+            instance,
+            projectRoot,
+        };
+    }
+    /**
+     * Finds the project root by walking up from a directory.
+     * Returns the directory containing .brv/ or undefined if not found.
+     */
+    async findProjectRoot(fromDir) {
+        let currentDir = fromDir;
+        // Walk up requires sequential checks - can't parallelize tree traversal
+        while (true) {
+            const brvPath = join(currentDir, BRV_DIR);
+            // eslint-disable-next-line no-await-in-loop
+            if (await this.directoryExists(brvPath)) {
+                return currentDir;
+            }
+            // Get parent directory
+            const parentDir = dirname(currentDir);
+            // Check if we've reached the root
+            if (parentDir === currentDir) {
+                return undefined;
+            }
+            // Check if we've reached filesystem root (e.g., "/" or "C:\")
+            const parsed = parse(currentDir);
+            if (parsed.root === currentDir) {
+                return undefined;
+            }
+            currentDir = parentDir;
+        }
+    }
+    /**
+     * Checks if a directory exists.
+     */
+    async directoryExists(path) {
+        try {
+            await access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/infra/instance/file-instance-manager.d.ts

@@ -0,0 +1,46 @@
+import type { AcquireResult, IInstanceManager } from '../../core/interfaces/instance/i-instance-manager.js';
+import { InstanceInfo } from '../../core/domain/instance/types.js';
+/**
+ * File-based implementation of IInstanceManager.
+ *
+ * Stores instance information in .brv/instance.json.
+ *
+ * NOTE: We don't store "status" - we check pid alive at runtime.
+ * This handles crashes gracefully without stale status.
+ */
+export declare class FileInstanceManager implements IInstanceManager {
+    /**
+     * Attempts to acquire an instance lock.
+     *
+     * Logic:
+     * - No file → create new instance
+     * - File exists + pid alive → already running, fail
+     * - File exists + pid dead → stale (crashed), overwrite
+     *
+     * @param projectRoot - Root directory containing .brv/
+     * @param port - Port the transport server will use
+     */
+    acquire(projectRoot: string, port: number): Promise<AcquireResult>;
+    /**
+     * Loads instance info from the project root.
+     */
+    load(projectRoot: string): Promise<InstanceInfo | undefined>;
+    /**
+     * Releases the instance lock by deleting instance.json.
+     *
+     * Called during graceful shutdown.
+     */
+    release(projectRoot: string): Promise<void>;
+    /**
+     * Updates the current session ID.
+     */
+    updateSessionId(projectRoot: string, sessionId: string): Promise<void>;
+    /**
+     * Gets the path to the instance.json file.
+     */
+    private getInstanceFilePath;
+    /**
+     * Saves instance info to the project root.
+     */
+    private save;
+}

package/dist/infra/instance/file-instance-manager.js

@@ -0,0 +1,123 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BRV_DIR, INSTANCE_FILE } from '../../constants.js';
+import { InstanceInfo } from '../../core/domain/instance/types.js';
+import { getCurrentPid, isProcessAlive } from './process-utils.js';
+/**
+ * Type guard to validate instance.json structure.
+ * Ensures all required fields exist with correct types.
+ */
+function isValidInstanceInfoJson(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.pid === 'number' &&
+        typeof obj.port === 'number' &&
+        typeof obj.startedAt === 'number' &&
+        (obj.currentSessionId === null || typeof obj.currentSessionId === 'string'));
+}
+/**
+ * File-based implementation of IInstanceManager.
+ *
+ * Stores instance information in .brv/instance.json.
+ *
+ * NOTE: We don't store "status" - we check pid alive at runtime.
+ * This handles crashes gracefully without stale status.
+ */
+export class FileInstanceManager {
+    /**
+     * Attempts to acquire an instance lock.
+     *
+     * Logic:
+     * - No file → create new instance
+     * - File exists + pid alive → already running, fail
+     * - File exists + pid dead → stale (crashed), overwrite
+     *
+     * @param projectRoot - Root directory containing .brv/
+     * @param port - Port the transport server will use
+     */
+    async acquire(projectRoot, port) {
+        const existing = await this.load(projectRoot);
+        // Check if there's an existing running instance (pid alive)
+        if (existing && isProcessAlive(existing.pid)) {
+            return {
+                acquired: false,
+                existingInstance: existing,
+                reason: 'already_running',
+            };
+        }
+        // Create new instance (either no existing or stale/crashed)
+        const instance = InstanceInfo.create({
+            pid: getCurrentPid(),
+            port,
+        });
+        await this.save(projectRoot, instance);
+        return {
+            acquired: true,
+            instance,
+        };
+    }
+    /**
+     * Loads instance info from the project root.
+     */
+    async load(projectRoot) {
+        const filePath = this.getInstanceFilePath(projectRoot);
+        try {
+            const content = await readFile(filePath, 'utf8');
+            const json = JSON.parse(content);
+            if (!isValidInstanceInfoJson(json)) {
+                // Corrupted file = no valid instance
+                return undefined;
+            }
+            return InstanceInfo.fromJson(json);
+        }
+        catch {
+            // File doesn't exist, is corrupted, or unreadable = no valid instance
+            return undefined;
+        }
+    }
+    /**
+     * Releases the instance lock by deleting instance.json.
+     *
+     * Called during graceful shutdown.
+     */
+    async release(projectRoot) {
+        const filePath = this.getInstanceFilePath(projectRoot);
+        try {
+            await rm(filePath);
+        }
+        catch {
+            // File might not exist, ignore
+        }
+    }
+    /**
+     * Updates the current session ID.
+     */
+    async updateSessionId(projectRoot, sessionId) {
+        const instance = await this.load(projectRoot);
+        if (!instance) {
+            throw new Error('No instance found to update');
+        }
+        const updated = instance.withSessionId(sessionId);
+        await this.save(projectRoot, updated);
+    }
+    /**
+     * Gets the path to the instance.json file.
+     */
+    getInstanceFilePath(projectRoot) {
+        return join(projectRoot, BRV_DIR, INSTANCE_FILE);
+    }
+    /**
+     * Saves instance info to the project root.
+     */
+    async save(projectRoot, instance) {
+        const brvDir = join(projectRoot, BRV_DIR);
+        const filePath = this.getInstanceFilePath(projectRoot);
+        // Ensure .brv directory exists
+        await mkdir(brvDir, { recursive: true });
+        // Write instance.json with pretty formatting
+        const json = JSON.stringify(instance.toJson(), null, 2);
+        await writeFile(filePath, json, 'utf8');
+    }
+}

package/dist/infra/instance/index.d.ts

@@ -0,0 +1,3 @@
+export * from './file-instance-discovery.js';
+export * from './file-instance-manager.js';
+export * from './process-utils.js';

package/dist/infra/instance/index.js

@@ -0,0 +1,3 @@
+export * from './file-instance-discovery.js';
+export * from './file-instance-manager.js';
+export * from './process-utils.js';

package/dist/infra/instance/process-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Checks if a process with the given PID is alive.
+ *
+ * Uses process.kill(pid, 0) which doesn't actually send a signal,
+ * but throws an error if the process doesn't exist.
+ *
+ * @param pid - Process ID to check
+ * @returns true if process exists, false otherwise
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Gets the current process ID.
+ */
+export declare function getCurrentPid(): number;

package/dist/infra/instance/process-utils.js

@@ -0,0 +1,39 @@
+/**
+ * Checks if a process with the given PID is alive.
+ *
+ * Uses process.kill(pid, 0) which doesn't actually send a signal,
+ * but throws an error if the process doesn't exist.
+ *
+ * @param pid - Process ID to check
+ * @returns true if process exists, false otherwise
+ */
+export function isProcessAlive(pid) {
+    try {
+        // Signal 0 doesn't kill the process, just checks if it exists
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH means "No such process"
+        // EPERM means "Permission denied" (process exists but we can't signal it)
+        if (error instanceof Error && 'code' in error) {
+            const { code } = error;
+            if (code === 'ESRCH') {
+                return false;
+            }
+            if (code === 'EPERM') {
+                // Process exists but we don't have permission to signal it
+                // This shouldn't happen for our own child processes, but handle it
+                return true;
+            }
+        }
+        // Unknown error, assume process doesn't exist
+        return false;
+    }
+}
+/**
+ * Gets the current process ID.
+ */
+export function getCurrentPid() {
+    return process.pid;
+}

package/dist/infra/process/agent-worker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent Worker - Entry point for Agent Process.
+ *
+ * Architecture v0.5.0:
+ * - Connects to Transport as Socket.IO CLIENT
+ * - Contains TaskProcessor + UseCases + CipherAgent
+ * - Receives tasks via Socket.IO (task:execute)
+ * - Sends results back via Socket.IO (task:chunk, task:completed, etc.)
+ * - NO Socket.IO server (Transport is the only server)
+ *
+ * IPC messages:
+ * - Receives: 'ping', 'shutdown'
+ * - Sends: 'ready', 'pong', 'stopped', 'error'
+ *
+ * Socket.IO events (as client):
+ * - Sends: 'agent:register' (identify as Agent)
+ * - Receives: 'task:execute', 'task:cancel', 'shutdown'
+ * - Sends: 'task:started', 'task:chunk', 'task:completed', 'task:error', 'task:toolCall', 'task:toolResult'
+ */
+export {};