byterover-cli 0.4.1 → 1.0.0

package/dist/infra/process/task-queue-manager.d.ts

@@ -0,0 +1,123 @@
+/**
+ * TaskQueueManager - Manages in-memory task queues with concurrency control.
+ *
+ * Features:
+ * - Separate queues for different task types (curate, query)
+ * - Configurable concurrency limits per queue
+ * - Task deduplication (same taskId can't be queued twice)
+ * - Cancel tasks from queue before processing
+ * - FIFO processing order
+ *
+ * This class is extracted from agent-worker.ts to enable unit testing.
+ */
+import type { TaskExecute } from '../../core/domain/transport/schemas.js';
+export type TaskType = 'curate' | 'query';
+export interface QueueConfig {
+    /** Maximum concurrent tasks for this queue */
+    maxConcurrent: number;
+}
+export interface TaskQueueStats {
+    /** Number of tasks currently being processed */
+    active: number;
+    /** Maximum concurrent tasks allowed */
+    maxConcurrent: number;
+    /** Number of tasks waiting in queue */
+    queued: number;
+}
+export interface TaskQueueManagerConfig {
+    curate: QueueConfig;
+    /** Optional callback for executor errors (for logging/debugging) */
+    onExecutorError?: (taskId: string, error: unknown) => void;
+    query: QueueConfig;
+}
+/**
+ * Result of attempting to enqueue a task.
+ */
+export type EnqueueResult = {
+    position: number;
+    success: true;
+} | {
+    reason: 'duplicate' | 'unknown_type';
+    success: false;
+};
+/**
+ * Result of attempting to cancel a task.
+ */
+export type CancelResult = {
+    reason: 'not_found';
+    success: false;
+} | {
+    success: true;
+    taskType: TaskType;
+    wasQueued: boolean;
+};
+/**
+ * Callback for when a task should be executed.
+ */
+export type TaskExecutor = (task: TaskExecute) => Promise<void>;
+export declare class TaskQueueManager {
+    private activeCurateTasks;
+    private activeQueryTasks;
+    private readonly config;
+    private readonly curateQueue;
+    /** Maps taskId → taskType for tracking (replaces Set for type awareness) */
+    private readonly knownTasks;
+    private readonly onExecutorError?;
+    private readonly queryQueue;
+    private taskExecutor;
+    constructor(config?: Partial<TaskQueueManagerConfig>);
+    /**
+     * Cancel a task by taskId.
+     * Removes from queue if waiting, or marks for cancellation if processing.
+     */
+    cancel(taskId: string): CancelResult;
+    /**
+     * Clear all queues and reset state.
+     * Useful for testing or shutdown.
+     */
+    clear(): void;
+    /**
+     * Enqueue a task for processing.
+     * Returns success with queue position, or failure reason.
+     */
+    enqueue(task: TaskExecute): EnqueueResult;
+    /**
+     * Get all queue statistics.
+     */
+    getAllStats(): Record<TaskType, TaskQueueStats>;
+    /**
+     * Get statistics for a specific queue.
+     */
+    getStats(type: TaskType): TaskQueueStats;
+    /**
+     * Check if a taskId is known (queued or processing).
+     */
+    isKnown(taskId: string): boolean;
+    /**
+     * Mark a task as completed (removes from known map).
+     * Should be called by executor when task finishes.
+     * Guards against underflow from duplicate/invalid calls.
+     */
+    markCompleted(taskId: string, type: TaskType): void;
+    /**
+     * Set the task executor callback.
+     * Called when a task is ready to be processed.
+     * Also triggers processing of any queued tasks (up to maxConcurrent).
+     */
+    setExecutor(executor: TaskExecutor): void;
+    /**
+     * Process all possible tasks from a queue (up to maxConcurrent).
+     * Handles Infinity maxConcurrent safely by using queue length as bound.
+     */
+    private drainQueue;
+    private executeTask;
+    /**
+     * Get queue state for a task type (DRY helper).
+     */
+    private getQueueState;
+    /**
+     * Try to process the next task from a specific queue.
+     * Unified method replacing tryProcessNextCurate/tryProcessNextQuery.
+     */
+    private tryProcessNext;
+}

package/dist/infra/process/task-queue-manager.js

@@ -0,0 +1,226 @@
+/**
+ * TaskQueueManager - Manages in-memory task queues with concurrency control.
+ *
+ * Features:
+ * - Separate queues for different task types (curate, query)
+ * - Configurable concurrency limits per queue
+ * - Task deduplication (same taskId can't be queued twice)
+ * - Cancel tasks from queue before processing
+ * - FIFO processing order
+ *
+ * This class is extracted from agent-worker.ts to enable unit testing.
+ */
+export class TaskQueueManager {
+    activeCurateTasks = 0;
+    activeQueryTasks = 0;
+    config;
+    curateQueue = [];
+    /** Maps taskId → taskType for tracking (replaces Set for type awareness) */
+    knownTasks = new Map();
+    onExecutorError;
+    queryQueue = [];
+    taskExecutor;
+    constructor(config) {
+        this.config = {
+            curate: { maxConcurrent: config?.curate?.maxConcurrent ?? 2 },
+            // Query tasks are unlimited (Infinity) - lightweight and fast
+            query: { maxConcurrent: config?.query?.maxConcurrent ?? Infinity },
+        };
+        this.onExecutorError = config?.onExecutorError;
+    }
+    /**
+     * Cancel a task by taskId.
+     * Removes from queue if waiting, or marks for cancellation if processing.
+     */
+    cancel(taskId) {
+        // Try to remove from curate queue
+        const curateIndex = this.curateQueue.findIndex((t) => t.taskId === taskId);
+        if (curateIndex !== -1) {
+            this.curateQueue.splice(curateIndex, 1);
+            this.knownTasks.delete(taskId);
+            return { success: true, taskType: 'curate', wasQueued: true };
+        }
+        // Try to remove from query queue
+        const queryIndex = this.queryQueue.findIndex((t) => t.taskId === taskId);
+        if (queryIndex !== -1) {
+            this.queryQueue.splice(queryIndex, 1);
+            this.knownTasks.delete(taskId);
+            return { success: true, taskType: 'query', wasQueued: true };
+        }
+        // Check if task is currently processing - now we know the real taskType!
+        const taskType = this.knownTasks.get(taskId);
+        if (taskType) {
+            // Task is processing - caller should handle cancellation via taskProcessor
+            return { success: true, taskType, wasQueued: false };
+        }
+        return { reason: 'not_found', success: false };
+    }
+    /**
+     * Clear all queues and reset state.
+     * Useful for testing or shutdown.
+     */
+    clear() {
+        this.curateQueue.length = 0;
+        this.queryQueue.length = 0;
+        this.activeCurateTasks = 0;
+        this.activeQueryTasks = 0;
+        this.knownTasks.clear();
+    }
+    /**
+     * Enqueue a task for processing.
+     * Returns success with queue position, or failure reason.
+     */
+    enqueue(task) {
+        // Deduplication check
+        if (this.knownTasks.has(task.taskId)) {
+            return { reason: 'duplicate', success: false };
+        }
+        // Validate task type
+        if (task.type !== 'curate' && task.type !== 'query') {
+            return { reason: 'unknown_type', success: false };
+        }
+        // Register with type and enqueue
+        this.knownTasks.set(task.taskId, task.type);
+        if (task.type === 'curate') {
+            this.curateQueue.push(task);
+            this.tryProcessNext('curate');
+            return { position: this.curateQueue.length, success: true };
+        }
+        this.queryQueue.push(task);
+        this.tryProcessNext('query');
+        return { position: this.queryQueue.length, success: true };
+    }
+    /**
+     * Get all queue statistics.
+     */
+    getAllStats() {
+        return {
+            curate: this.getStats('curate'),
+            query: this.getStats('query'),
+        };
+    }
+    /**
+     * Get statistics for a specific queue.
+     */
+    getStats(type) {
+        if (type === 'curate') {
+            return {
+                active: this.activeCurateTasks,
+                maxConcurrent: this.config.curate.maxConcurrent,
+                queued: this.curateQueue.length,
+            };
+        }
+        return {
+            active: this.activeQueryTasks,
+            maxConcurrent: this.config.query.maxConcurrent,
+            queued: this.queryQueue.length,
+        };
+    }
+    /**
+     * Check if a taskId is known (queued or processing).
+     */
+    isKnown(taskId) {
+        return this.knownTasks.has(taskId);
+    }
+    /**
+     * Mark a task as completed (removes from known map).
+     * Should be called by executor when task finishes.
+     * Guards against underflow from duplicate/invalid calls.
+     */
+    markCompleted(taskId, type) {
+        // Guard: only decrement if task was actually known (prevents underflow)
+        if (!this.knownTasks.has(taskId)) {
+            return;
+        }
+        this.knownTasks.delete(taskId);
+        if (type === 'curate') {
+            if (this.activeCurateTasks > 0) {
+                this.activeCurateTasks--;
+            }
+            this.tryProcessNext('curate');
+        }
+        else {
+            if (this.activeQueryTasks > 0) {
+                this.activeQueryTasks--;
+            }
+            this.tryProcessNext('query');
+        }
+    }
+    /**
+     * Set the task executor callback.
+     * Called when a task is ready to be processed.
+     * Also triggers processing of any queued tasks (up to maxConcurrent).
+     */
+    setExecutor(executor) {
+        this.taskExecutor = executor;
+        // Process any tasks that were queued before executor was set
+        // Use queue length as upper bound to handle Infinity maxConcurrent safely
+        this.drainQueue('curate');
+        this.drainQueue('query');
+    }
+    /**
+     * Process all possible tasks from a queue (up to maxConcurrent).
+     * Handles Infinity maxConcurrent safely by using queue length as bound.
+     */
+    drainQueue(type) {
+        const state = this.getQueueState(type);
+        // Process up to queue length (safe for Infinity maxConcurrent)
+        const toProcess = Math.min(state.queue.length, state.config.maxConcurrent);
+        for (let i = 0; i < toProcess; i++) {
+            this.tryProcessNext(type);
+        }
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    executeTask(task, type) {
+        this.taskExecutor(task)
+            .catch((error) => {
+            // Notify caller of executor error (for logging/debugging)
+            // Primary error handling is executor's responsibility
+            this.onExecutorError?.(task.taskId, error);
+        })
+            .finally(() => {
+            this.markCompleted(task.taskId, type);
+        });
+    }
+    /**
+     * Get queue state for a task type (DRY helper).
+     */
+    getQueueState(type) {
+        if (type === 'curate') {
+            return {
+                active: this.activeCurateTasks,
+                config: this.config.curate,
+                incrementActive: () => this.activeCurateTasks++,
+                queue: this.curateQueue,
+            };
+        }
+        return {
+            active: this.activeQueryTasks,
+            config: this.config.query,
+            incrementActive: () => this.activeQueryTasks++,
+            queue: this.queryQueue,
+        };
+    }
+    /**
+     * Try to process the next task from a specific queue.
+     * Unified method replacing tryProcessNextCurate/tryProcessNextQuery.
+     */
+    tryProcessNext(type) {
+        // Don't process without executor - tasks stay in queue
+        if (!this.taskExecutor) {
+            return;
+        }
+        const state = this.getQueueState(type);
+        if (state.active >= state.config.maxConcurrent) {
+            return;
+        }
+        if (state.queue.length === 0) {
+            return;
+        }
+        const task = state.queue.shift();
+        state.incrementActive();
+        this.executeTask(task, type);
+    }
+}

package/dist/infra/process/transport-handlers.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Transport Handlers - Message routing in Transport Process.
+ *
+ * Architecture v0.5.0:
+ * - Routes messages between clients (TUI, external CLIs) and Agent
+ * - Agent is a special client that registers via 'agent:register'
+ * - Client UseCase generates taskId, Transport validates and routes
+ * - NO TaskProcessor, NO business logic (just routing)
+ *
+ * Event naming convention:
+ * - task:* events are Transport-generated (ack, created, started, completed, error)
+ * - llmservice:* events are forwarded from Agent with ORIGINAL names
+ *
+ * Message flows:
+ * 1. Client → Transport: task:create {taskId, type, content}
+ *    Transport → Agent: task:execute {taskId, type, content, clientId}
+ *    Transport → Client: task:ack {taskId}
+ *    Transport → broadcast-room: task:created {taskId, type, content, files?}
+ *
+ * 2. Agent → Transport: llmservice:response {taskId, content}
+ *    Transport → Client (direct): llmservice:response
+ *    Transport → broadcast-room: llmservice:response (for TUI monitoring)
+ *
+ * 3. Agent → Transport: task:completed {taskId}
+ *    Transport → Client (direct): task:completed
+ *    Transport → broadcast-room: task:completed (for TUI monitoring)
+ *
+ * Special events:
+ * - agent:register: Agent identifies itself
+ * - agent:connected / agent:disconnected: Broadcast to all clients
+ * - broadcast-room: TUI joins this room to monitor all events
+ */
+import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
+/**
+ * TransportHandlers - Routes messages between clients and Agent.
+ *
+ * This class is the "brain" of the Transport Process.
+ * It knows which client is the Agent and routes messages accordingly.
+ */
+export declare class TransportHandlers {
+    /** The Agent's client ID (set when Agent registers) */
+    private agentClientId;
+    /** Track active tasks */
+    private tasks;
+    /** Transport server reference */
+    private readonly transport;
+    constructor(transport: ITransportServer);
+    /**
+     * Cleanup handlers.
+     */
+    cleanup(): void;
+    /**
+     * Setup all message handlers.
+     */
+    setup(): void;
+    /**
+     * Handle Agent registration.
+     * Agent connects as Socket.IO client and sends 'agent:register'.
+     */
+    private handleAgentRegister;
+    /**
+     * Handle task:cancel request from client.
+     * Returns success:false if task not found or Agent not available.
+     * Emits task:cancelled terminal event when cancelled locally (no Agent).
+     */
+    private handleTaskCancel;
+    /**
+     * Handle task:cancelled from Agent.
+     * Terminal event: task was cancelled before completion.
+     * Route to task owner + broadcast-room, then cleanup.
+     */
+    private handleTaskCancelled;
+    /**
+     * Handle task:completed from Agent.
+     * Route directly to task owner + broadcast-room for monitoring.
+     */
+    private handleTaskCompleted;
+    /**
+     * Handle task:create request from client.
+     * Validate taskId from client, add to tracking, forward to Agent.
+     */
+    private handleTaskCreate;
+    /**
+     * Handle task:error from Agent.
+     * Route directly to task owner + broadcast-room for monitoring.
+     */
+    private handleTaskError;
+    /**
+     * Handle task:started from Agent.
+     * Route directly to task owner + broadcast-room for monitoring.
+     */
+    private handleTaskStarted;
+    private registerLlmEvent;
+    /**
+     * Generic handler for routing LLM events from Agent to clients.
+     * Routes directly to task owner + broadcast-room for monitoring.
+     *
+     * All llmservice:* events follow the same routing pattern:
+     * 1. Extract taskId from payload
+     * 2. Check if task is still active (not completed/cancelled/errored)
+     * 3. Send to task owner + broadcast-room if active
+     * 4. Drop silently if task already ended (prevents events-after-terminal)
+     */
+    private routeLlmEvent;
+    /**
+     * Setup agent control handlers.
+     * These handle commands to control the Agent process (restart, etc.)
+     */
+    private setupAgentControlHandlers;
+    /**
+     * Setup Agent-related handlers.
+     * These handle events FROM the Agent.
+     */
+    private setupAgentHandlers;
+    /**
+     * Setup client-related handlers.
+     * These handle events FROM clients (TUI, external CLIs).
+     */
+    private setupClientHandlers;
+    /**
+     * Setup connection event handlers.
+     */
+    private setupConnectionHandlers;
+}