byterover-cli 0.4.0 → 1.0.0

package/dist/infra/repl/transport-client-helper.js

@@ -0,0 +1,96 @@
+/**
+ * Transport Client Helper for TUI (v0.5.0 architecture).
+ *
+ * TODO(v0.5.0): This is a temporary helper for TUI team to monitor events.
+ * Remove when TUI fully integrates with Transport via React context.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDevelopment } from '../../config/environment.js';
+import { BRV_DIR } from '../../constants.js';
+import { TransportAgentEventNames, TransportLlmEventList, TransportSessionEventNames, TransportTaskEventNames, } from '../../core/domain/transport/schemas.js';
+import { createTransportClientFactory } from '../transport/transport-client-factory.js';
+const TRANSPORT_LOG_FILE = path.join(BRV_DIR, 'transport-events.log');
+/**
+ * Transport events that TUI subscribes to via "broadcast-room".
+ *
+ * Event naming convention:
+ * - task:* events are Transport-generated (lifecycle)
+ * - llmservice:* events are forwarded from Agent with ORIGINAL names
+ *
+ * This means FE receives the SAME event names that Agent emits internally.
+ * No mapping needed - what you see is what Agent does.
+ */
+const TRANSPORT_EVENTS = [
+    // Task lifecycle (Transport-generated) - using constants from schemas
+    TransportTaskEventNames.ACK,
+    TransportTaskEventNames.CREATED,
+    TransportTaskEventNames.STARTED,
+    TransportTaskEventNames.COMPLETED,
+    TransportTaskEventNames.ERROR,
+    TransportTaskEventNames.CANCELLED,
+    // LLM events (using constants from schemas)
+    ...TransportLlmEventList,
+    // Connection events (internal)
+    TransportAgentEventNames.CONNECTED,
+    TransportAgentEventNames.DISCONNECTED,
+    TransportSessionEventNames.SWITCHED,
+    // Agent control events
+    TransportAgentEventNames.RESTARTING,
+    TransportAgentEventNames.RESTARTED,
+];
+function formatTimestamp() {
+    return new Date().toISOString();
+}
+function logEvent(eventName, data) {
+    if (!isDevelopment())
+        return;
+    const line = JSON.stringify({ data, event: eventName, timestamp: formatTimestamp() }, null, 2) + '\n';
+    try {
+        fs.appendFileSync(TRANSPORT_LOG_FILE, line);
+    }
+    catch {
+        // Ignore
+    }
+}
+/**
+ * Connect to Transport and join TUI room for event monitoring.
+ */
+export async function connectTransportClient() {
+    if (isDevelopment()) {
+        try {
+            fs.writeFileSync(TRANSPORT_LOG_FILE, `# Transport Events - ${formatTimestamp()}\n`);
+        }
+        catch {
+            // Ignore
+        }
+    }
+    try {
+        const factory = createTransportClientFactory();
+        const { client } = await factory.connect();
+        client.onStateChange((state) => {
+            logEvent('_connection', { clientId: client.getClientId(), state });
+        });
+        for (const event of TRANSPORT_EVENTS) {
+            client.on(event, (data) => logEvent(event, data));
+        }
+        logEvent('_connection', { clientId: client.getClientId(), state: 'initialized' });
+        await client.joinRoom('broadcast-room');
+        logEvent('_room', { room: 'broadcast-room', state: 'joined' });
+        return client;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        logEvent('_connection', { error: msg, state: 'failed' });
+        return null;
+    }
+}
+/**
+ * Disconnect transport client.
+ */
+export async function disconnectTransportClient(client) {
+    if (client) {
+        logEvent('_connection', { state: 'closing' });
+        await client.disconnect();
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from './port-utils.js';
+export * from './socket-io-transport-client.js';
+export * from './socket-io-transport-server.js';
+export * from './transport-factory.js';

package/dist/infra/transport/index.js

@@ -0,0 +1,4 @@
+export * from './port-utils.js';
+export * from './socket-io-transport-client.js';
+export * from './socket-io-transport-server.js';
+export * from './transport-factory.js';

package/dist/infra/transport/port-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Checks if a port is available for binding.
+ *
+ * @param port - The port number to check
+ * @returns Promise resolving to true if available, false otherwise
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Generates a random port within the safe range.
+ *
+ * @returns A random port number between PORT_RANGE_MIN and PORT_RANGE_MAX
+ */
+export declare function getRandomPort(): number;
+/**
+ * Finds an available port for the transport server.
+ *
+ * Uses a random selection strategy within the safe port range (49152-60000)
+ * to avoid conflicts with:
+ * - Well-known ports (0-1023): HTTP, HTTPS, SSH, etc.
+ * - Common dev ports: 3000, 5000, 8080, etc.
+ * - Database ports: 3306, 5432, 27017, 6379, etc.
+ *
+ * @returns Promise resolving to an available port number
+ * @throws Error if no available port found after MAX_PORT_ATTEMPTS
+ *
+ * @example
+ * const port = await findAvailablePort();
+ * await server.start(port);
+ */
+export declare function findAvailablePort(): Promise<number>;
+/**
+ * Finds an available port, starting from a preferred port.
+ * If the preferred port is not available, falls back to random selection.
+ *
+ * @param preferredPort - The preferred port to try first
+ * @returns Promise resolving to an available port number
+ *
+ * @example
+ * // Try 9847 first, fallback to random if unavailable
+ * const port = await findAvailablePortWithPreference(9847);
+ */
+export declare function findAvailablePortWithPreference(preferredPort: number): Promise<number>;

package/dist/infra/transport/port-utils.js

@@ -0,0 +1,84 @@
+import { createServer } from 'node:net';
+import { TRANSPORT_HOST } from '../../constants.js';
+/**
+ * Port range for transport server.
+ * Using high ports (49152-65535) which are "dynamic/private" per IANA.
+ * We use a subset to avoid potential conflicts.
+ */
+const PORT_RANGE_MIN = 49_152;
+const PORT_RANGE_MAX = 60_000;
+/**
+ * Maximum attempts to find an available port.
+ */
+const MAX_PORT_ATTEMPTS = 20;
+/**
+ * Checks if a port is available for binding.
+ *
+ * @param port - The port number to check
+ * @returns Promise resolving to true if available, false otherwise
+ */
+export function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => {
+            resolve(false);
+        });
+        server.once('listening', () => {
+            server.close(() => {
+                resolve(true);
+            });
+        });
+        server.listen(port, TRANSPORT_HOST);
+    });
+}
+/**
+ * Generates a random port within the safe range.
+ *
+ * @returns A random port number between PORT_RANGE_MIN and PORT_RANGE_MAX
+ */
+export function getRandomPort() {
+    return Math.floor(Math.random() * (PORT_RANGE_MAX - PORT_RANGE_MIN + 1)) + PORT_RANGE_MIN;
+}
+/**
+ * Finds an available port for the transport server.
+ *
+ * Uses a random selection strategy within the safe port range (49152-60000)
+ * to avoid conflicts with:
+ * - Well-known ports (0-1023): HTTP, HTTPS, SSH, etc.
+ * - Common dev ports: 3000, 5000, 8080, etc.
+ * - Database ports: 3306, 5432, 27017, 6379, etc.
+ *
+ * @returns Promise resolving to an available port number
+ * @throws Error if no available port found after MAX_PORT_ATTEMPTS
+ *
+ * @example
+ * const port = await findAvailablePort();
+ * await server.start(port);
+ */
+export async function findAvailablePort() {
+    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+        const port = getRandomPort();
+        // eslint-disable-next-line no-await-in-loop -- Sequential check is intentional: find first available port
+        if (await isPortAvailable(port)) {
+            return port;
+        }
+    }
+    throw new Error(`Failed to find available port after ${MAX_PORT_ATTEMPTS} attempts in range ${PORT_RANGE_MIN}-${PORT_RANGE_MAX}`);
+}
+/**
+ * Finds an available port, starting from a preferred port.
+ * If the preferred port is not available, falls back to random selection.
+ *
+ * @param preferredPort - The preferred port to try first
+ * @returns Promise resolving to an available port number
+ *
+ * @example
+ * // Try 9847 first, fallback to random if unavailable
+ * const port = await findAvailablePortWithPreference(9847);
+ */
+export async function findAvailablePortWithPreference(preferredPort) {
+    if (await isPortAvailable(preferredPort)) {
+        return preferredPort;
+    }
+    return findAvailablePort();
+}

package/dist/infra/transport/socket-io-transport-client.d.ts

@@ -0,0 +1,45 @@
+import type { TransportClientConfig } from '../../core/domain/transport/types.js';
+import type { ConnectionState, ConnectionStateHandler, EventHandler, ITransportClient, RequestOptions } from '../../core/interfaces/transport/index.js';
+/**
+ * Socket.IO implementation of ITransportClient.
+ *
+ * Architecture notes:
+ * - Auto-reconnects with exponential backoff
+ * - Request/response uses Socket.IO acknowledgements (callbacks)
+ * - Connection state is tracked and exposed via onStateChange
+ */
+export declare class SocketIOTransportClient implements ITransportClient {
+    private readonly config;
+    private eventHandlers;
+    /** Track which events have socket listeners registered (prevents duplicates on reconnect) */
+    private registeredSocketEvents;
+    private socket;
+    private state;
+    private stateHandlers;
+    constructor(config?: TransportClientConfig);
+    connect(url: string): Promise<void>;
+    disconnect(): Promise<void>;
+    getClientId(): string | undefined;
+    getState(): ConnectionState;
+    joinRoom(room: string): Promise<void>;
+    leaveRoom(room: string): Promise<void>;
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    once<T = unknown>(event: string, handler: EventHandler<T>): void;
+    onStateChange(handler: ConnectionStateHandler): () => void;
+    request<TResponse = unknown, TRequest = unknown>(event: string, data?: TRequest, options?: RequestOptions): Promise<TResponse>;
+    /**
+     * Register all pending event handlers on the socket.
+     * Called after successful connection to handle handlers added before connect().
+     */
+    private registerPendingEventHandlers;
+    /**
+     * Register a socket listener for an event if not already registered.
+     * Uses registeredSocketEvents set to prevent duplicates.
+     */
+    private registerSocketEventIfNeeded;
+    /**
+     * Remove socket listener for an event and clear tracking.
+     */
+    private removeSocketEventListener;
+    private setState;
+}

package/dist/infra/transport/socket-io-transport-client.js

@@ -0,0 +1,270 @@
+import { io } from 'socket.io-client';
+import { TRANSPORT_CONNECT_TIMEOUT_MS, TRANSPORT_DEFAULT_TRANSPORTS, TRANSPORT_RECONNECTION_ATTEMPTS, TRANSPORT_RECONNECTION_DELAY_MAX_MS, TRANSPORT_RECONNECTION_DELAY_MS, TRANSPORT_REQUEST_TIMEOUT_MS, TRANSPORT_ROOM_TIMEOUT_MS, } from '../../constants.js';
+import { TransportConnectionError, TransportNotConnectedError, TransportRequestError, TransportRequestTimeoutError, TransportRoomError, TransportRoomTimeoutError, } from '../../core/domain/errors/transport-error.js';
+/**
+ * Socket.IO implementation of ITransportClient.
+ *
+ * Architecture notes:
+ * - Auto-reconnects with exponential backoff
+ * - Request/response uses Socket.IO acknowledgements (callbacks)
+ * - Connection state is tracked and exposed via onStateChange
+ */
+export class SocketIOTransportClient {
+    config;
+    eventHandlers = new Map();
+    /** Track which events have socket listeners registered (prevents duplicates on reconnect) */
+    registeredSocketEvents = new Set();
+    socket;
+    state = 'disconnected';
+    stateHandlers = new Set();
+    constructor(config) {
+        this.config = {
+            connectTimeoutMs: config?.connectTimeoutMs ?? TRANSPORT_CONNECT_TIMEOUT_MS,
+            reconnectionAttempts: config?.reconnectionAttempts ?? TRANSPORT_RECONNECTION_ATTEMPTS,
+            reconnectionDelayMaxMs: config?.reconnectionDelayMaxMs ?? TRANSPORT_RECONNECTION_DELAY_MAX_MS,
+            reconnectionDelayMs: config?.reconnectionDelayMs ?? TRANSPORT_RECONNECTION_DELAY_MS,
+            requestTimeoutMs: config?.requestTimeoutMs ?? TRANSPORT_REQUEST_TIMEOUT_MS,
+            roomTimeoutMs: config?.roomTimeoutMs ?? TRANSPORT_ROOM_TIMEOUT_MS,
+            transports: config?.transports ?? TRANSPORT_DEFAULT_TRANSPORTS,
+        };
+    }
+    async connect(url) {
+        if (this.socket?.connected) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            this.setState('connecting');
+            this.socket = io(url, {
+                randomizationFactor: 0,
+                reconnection: true,
+                reconnectionAttempts: this.config.reconnectionAttempts,
+                reconnectionDelay: this.config.reconnectionDelayMs,
+                reconnectionDelayMax: this.config.reconnectionDelayMaxMs,
+                timeout: this.config.connectTimeoutMs,
+                // Use WebSocket-only by default to avoid HTTP polling issues in sandboxed environments
+                transports: this.config.transports,
+            });
+            const onConnect = () => {
+                this.setState('connected');
+                cleanup();
+                // Register any handlers that were added before connect() was called.
+                // This fixes the issue where on() called before connect() would not
+                // actually register handlers on the socket.
+                this.registerPendingEventHandlers();
+                resolve();
+            };
+            const onConnectError = (error) => {
+                this.setState('disconnected');
+                cleanup();
+                // Properly disconnect and cleanup socket to prevent leaks.
+                // Without this, the socket continues attempting reconnection
+                // even after we reject the promise.
+                if (this.socket) {
+                    this.socket.removeAllListeners();
+                    this.socket.io.removeAllListeners();
+                    this.socket.disconnect();
+                    this.socket = undefined;
+                }
+                reject(new TransportConnectionError(url, error));
+            };
+            const cleanup = () => {
+                this.socket?.off('connect', onConnect);
+                this.socket?.off('connect_error', onConnectError);
+            };
+            this.socket.on('connect', onConnect);
+            this.socket.once('connect_error', onConnectError);
+            // Set up persistent event handlers
+            this.socket.on('disconnect', () => {
+                if (this.socket?.active) {
+                    // Socket.IO is attempting to reconnect
+                    this.setState('reconnecting');
+                }
+                else {
+                    this.setState('disconnected');
+                }
+            });
+            this.socket.io.on('reconnect', () => {
+                this.setState('connected');
+                // Re-register event handlers after reconnect
+                // Clear tracking first since socket listeners were reset during reconnect
+                this.registeredSocketEvents.clear();
+                this.registerPendingEventHandlers();
+            });
+            this.socket.io.on('reconnect_failed', () => {
+                this.setState('disconnected');
+            });
+        });
+    }
+    async disconnect() {
+        const { socket } = this;
+        if (!socket) {
+            return;
+        }
+        return new Promise((resolve) => {
+            // Remove all listeners to prevent memory leaks
+            socket.removeAllListeners();
+            socket.io.removeAllListeners();
+            socket.disconnect();
+            this.socket = undefined;
+            this.setState('disconnected');
+            // Clear all tracking state to prevent leaks
+            this.eventHandlers.clear();
+            this.registeredSocketEvents.clear();
+            this.stateHandlers.clear();
+            resolve();
+        });
+    }
+    getClientId() {
+        return this.socket?.id;
+    }
+    getState() {
+        return this.state;
+    }
+    async joinRoom(room) {
+        const { socket } = this;
+        if (!socket?.connected) {
+            throw new TransportNotConnectedError('joinRoom');
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new TransportRoomTimeoutError(room, 'join', this.config.roomTimeoutMs));
+            }, this.config.roomTimeoutMs);
+            socket.emit('room:join', room, (response) => {
+                clearTimeout(timer);
+                if (response.success) {
+                    resolve();
+                }
+                else {
+                    reject(new TransportRoomError(room, 'join'));
+                }
+            });
+        });
+    }
+    async leaveRoom(room) {
+        const { socket } = this;
+        if (!socket?.connected) {
+            throw new TransportNotConnectedError('leaveRoom');
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new TransportRoomTimeoutError(room, 'leave', this.config.roomTimeoutMs));
+            }, this.config.roomTimeoutMs);
+            socket.emit('room:leave', room, (response) => {
+                clearTimeout(timer);
+                if (response.success) {
+                    resolve();
+                }
+                else {
+                    reject(new TransportRoomError(room, 'leave'));
+                }
+            });
+        });
+    }
+    on(event, handler) {
+        if (!this.eventHandlers.has(event)) {
+            this.eventHandlers.set(event, new Set());
+        }
+        // Register socket listener if connected and not already registered
+        // Use registeredSocketEvents to prevent duplicates across reconnects
+        this.registerSocketEventIfNeeded(event);
+        // Wrap handler to store without type assertion
+        const wrappedHandler = (data) => handler(data);
+        const handlers = this.eventHandlers.get(event);
+        handlers?.add(wrappedHandler);
+        // Return unsubscribe function that also cleans up socket listener if no handlers remain
+        return () => {
+            handlers?.delete(wrappedHandler);
+            // Clean up socket listener and map entry if no handlers remain
+            if (handlers && handlers.size === 0) {
+                this.eventHandlers.delete(event);
+                this.removeSocketEventListener(event);
+            }
+        };
+    }
+    once(event, handler) {
+        const { socket } = this;
+        if (!socket) {
+            throw new TransportNotConnectedError('once');
+        }
+        socket.once(event, handler);
+    }
+    onStateChange(handler) {
+        this.stateHandlers.add(handler);
+        return () => {
+            this.stateHandlers.delete(handler);
+        };
+    }
+    async request(event, data, options) {
+        const { socket } = this;
+        if (!socket?.connected) {
+            throw new TransportNotConnectedError('request');
+        }
+        const timeout = options?.timeout ?? this.config.requestTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new TransportRequestTimeoutError(event, timeout));
+            }, timeout);
+            socket.emit(event, data, (response) => {
+                clearTimeout(timer);
+                if (response.success && response.data !== undefined) {
+                    resolve(response.data);
+                }
+                else if (response.success) {
+                    // Response success but data is undefined - resolve with undefined cast
+                    // This is a boundary case where server returns void
+                    resolve(undefined);
+                }
+                else {
+                    reject(new TransportRequestError(event, response.error));
+                }
+            });
+        });
+    }
+    /**
+     * Register all pending event handlers on the socket.
+     * Called after successful connection to handle handlers added before connect().
+     */
+    registerPendingEventHandlers() {
+        for (const event of this.eventHandlers.keys()) {
+            this.registerSocketEventIfNeeded(event);
+        }
+    }
+    /**
+     * Register a socket listener for an event if not already registered.
+     * Uses registeredSocketEvents set to prevent duplicates.
+     */
+    registerSocketEventIfNeeded(event) {
+        const { socket } = this;
+        if (!socket || this.registeredSocketEvents.has(event)) {
+            return;
+        }
+        // Register the dispatch listener on socket
+        socket.on(event, (data) => {
+            const handlers = this.eventHandlers.get(event);
+            if (handlers) {
+                for (const h of handlers) {
+                    h(data);
+                }
+            }
+        });
+        this.registeredSocketEvents.add(event);
+    }
+    /**
+     * Remove socket listener for an event and clear tracking.
+     */
+    removeSocketEventListener(event) {
+        const { socket } = this;
+        if (socket && this.registeredSocketEvents.has(event)) {
+            socket.off(event);
+            this.registeredSocketEvents.delete(event);
+        }
+    }
+    setState(state) {
+        if (this.state !== state) {
+            this.state = state;
+            for (const handler of this.stateHandlers) {
+                handler(state);
+            }
+        }
+    }
+}

package/dist/infra/transport/socket-io-transport-server.d.ts

@@ -0,0 +1,35 @@
+import type { TransportServerConfig } from '../../core/domain/transport/types.js';
+import type { ConnectionHandler, ITransportServer, RequestHandler } from '../../core/interfaces/transport/index.js';
+/**
+ * Socket.IO implementation of ITransportServer.
+ *
+ * Architecture notes:
+ * - Uses an HTTP server internally for Socket.IO
+ * - Request/response pattern: client emits "event", server emits "event:response" or "event:error"
+ * - Rooms are used for targeted broadcasts (e.g., per-task events)
+ */
+export declare class SocketIOTransportServer implements ITransportServer {
+    private readonly config;
+    private connectionHandlers;
+    private disconnectionHandlers;
+    private httpServer;
+    private io;
+    private port;
+    private requestHandlers;
+    private running;
+    private sockets;
+    constructor(config?: TransportServerConfig);
+    addToRoom(clientId: string, room: string): void;
+    broadcast<T = unknown>(event: string, data: T): void;
+    broadcastTo<T = unknown>(room: string, event: string, data: T): void;
+    getPort(): number | undefined;
+    isRunning(): boolean;
+    onConnection(handler: ConnectionHandler): void;
+    onDisconnection(handler: ConnectionHandler): void;
+    onRequest<TRequest = unknown, TResponse = unknown>(event: string, handler: RequestHandler<TRequest, TResponse>): void;
+    removeFromRoom(clientId: string, room: string): void;
+    sendTo<T = unknown>(clientId: string, event: string, data: T): void;
+    start(port: number): Promise<void>;
+    stop(): Promise<void>;
+    private registerEventHandler;
+}