@stdiobus/workers-registry 1.3.7

package/out/tsc/workers/acp-worker/src/registry-launcher/router/message-router.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Message Router for the Registry Launcher.
+ *
+ * Routes incoming JSON-RPC messages to the appropriate agent based on agentId.
+ * Handles agentId extraction, message transformation, and error response generation.
+ *
+ * @module router/message-router
+ */
+import type { IRegistryIndex } from '../registry/index.js';
+import type { AgentRuntimeManager } from '../runtime/manager.js';
+/**
+ * JSON-RPC error codes for routing errors.
+ */
+export declare const RoutingErrorCodes: {
+    /** Missing agentId in request */
+    readonly MISSING_AGENT_ID: -32600;
+    /** Agent not found in registry */
+    readonly AGENT_NOT_FOUND: -32001;
+    /** Platform not supported for binary distribution */
+    readonly PLATFORM_NOT_SUPPORTED: -32002;
+    /** Agent spawn failed */
+    readonly SPAWN_FAILED: -32003;
+};
+/**
+ * JSON-RPC error response structure.
+ */
+export interface ErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Callback type for writing responses to stdout.
+ */
+export type WriteCallback = (message: object) => boolean;
+/**
+ * Create a JSON-RPC error response.
+ *
+ * @param id - Request ID (null for notifications or unknown)
+ * @param code - Error code
+ * @param message - Error message
+ * @param data - Optional additional error data
+ * @returns Error response object
+ */
+export declare function createErrorResponse(id: string | number | null, code: number, message: string, data?: unknown): ErrorResponse;
+/**
+ * Extract the agentId field from a message.
+ *
+ * @param message - The message object to extract from
+ * @returns The agentId string or undefined if not present
+ */
+export declare function extractAgentId(message: object): string | undefined;
+/**
+ * Extract the JSON-RPC id field from a message.
+ *
+ * @param message - The message object to extract from
+ * @returns The id (string, number, or null)
+ */
+export declare function extractId(message: object): string | number | null;
+/**
+ * Transform a message for forwarding to an agent.
+ *
+ * Removes the agentId field while preserving all other fields.
+ *
+ * @param message - The original message
+ * @returns A new message object without the agentId field
+ */
+export declare function transformMessage(message: object): object;
+/**
+ * Message Router implementation.
+ *
+ * Routes incoming JSON-RPC messages to the appropriate agent based on agentId.
+ * Handles message transformation, error generation, and request correlation.
+ */
+export declare class MessageRouter {
+    /** Registry index for agent lookup and resolution */
+    private readonly registry;
+    /** Runtime manager for agent process lifecycle */
+    private readonly runtimeManager;
+    /** Callback for writing responses to stdout */
+    private readonly writeCallback;
+    /** API keys for agent authentication */
+    private readonly apiKeys;
+    /** Map of request ID to pending request info for correlation */
+    private readonly pendingRequests;
+    /** Map of agent ID to authentication state */
+    private readonly authState;
+    /** Map of agent sessionId to client sessionId for notification routing */
+    private readonly sessionIdMap;
+    /**
+     * Create a new MessageRouter.
+     *
+     * @param registry - Registry index for agent lookup
+     * @param runtimeManager - Runtime manager for agent processes
+     * @param writeCallback - Callback for writing responses to stdout
+     * @param apiKeys - API keys for agent authentication (optional)
+     */
+    constructor(registry: IRegistryIndex, runtimeManager: AgentRuntimeManager, writeCallback: WriteCallback, apiKeys?: Record<string, any>);
+    /**
+     * Route an incoming message to the appropriate agent.
+     *
+     * Extracts agentId, resolves spawn command, and forwards message.
+     *
+     * @param message - The incoming JSON-RPC message
+     * @returns Error response if routing fails, undefined on success
+     */
+    route(message: object): Promise<ErrorResponse | undefined>;
+    /**
+     * Handle a response from an agent process.
+     *
+     * Intercepts initialize responses to trigger automatic authentication.
+     * Tracks sessionId mapping for proper notification routing.
+     * Forwards all responses to stdout.
+     *
+     * @param agentId - The agent that sent the response
+     * @param response - The response object from the agent
+     */
+    handleAgentResponse(agentId: string, response: object): void;
+    /**
+     * Attempt automatic authentication for an agent.
+     *
+     * Selects the best authentication method and sends authenticate request.
+     *
+     * @param agentId - The agent to authenticate
+     * @param authMethods - Available authentication methods from initialize response
+     */
+    private attemptAuthentication;
+    /**
+     * Get the number of pending requests.
+     *
+     * @returns The count of pending requests
+     */
+    get pendingCount(): number;
+    /**
+     * Check if a request ID is pending.
+     *
+     * @param id - The request ID to check
+     * @returns true if the request is pending, false otherwise
+     */
+    isPending(id: string | number): boolean;
+    /**
+     * Clear all pending requests.
+     * Useful for cleanup during shutdown.
+     */
+    clearPending(): void;
+}

package/out/tsc/workers/acp-worker/src/registry-launcher/runtime/agent-runtime.d.ts

@@ -0,0 +1,58 @@
+import { ChildProcess } from 'child_process';
+import type { AgentRuntime, RuntimeState } from './types.js';
+import type { SpawnCommand } from '../registry/types.js';
+/**
+ * Implementation of AgentRuntime that manages a spawned agent process.
+ *
+ * Handles process spawning with non-blocking file descriptors,
+ * message writing to stdin, and graceful termination with SIGTERM/SIGKILL.
+ */
+export declare class AgentRuntimeImpl implements AgentRuntime {
+    readonly agentId: string;
+    state: RuntimeState;
+    readonly process: ChildProcess;
+    private readonly onExitCallback?;
+    /**
+     * Create a new AgentRuntime by spawning a process.
+     *
+     * @param agentId - The agent identifier
+     * @param spawnCommand - The resolved spawn command
+     * @param onExit - Optional callback when process exits
+     */
+    private constructor();
+    /**
+     * Spawn a new agent process and create an AgentRuntime instance.
+     *
+     * @param agentId - The agent identifier
+     * @param spawnCommand - The resolved spawn command with command, args, and optional env
+     * @param onExit - Optional callback when process exits
+     * @returns A new AgentRuntime instance
+     */
+    static spawn(agentId: string, spawnCommand: SpawnCommand, onExit?: (code: number | null, signal: string | null) => void): AgentRuntimeImpl;
+    /**
+     * Set up event handlers for the child process.
+     */
+    private setupProcessHandlers;
+    /**
+     * Write a message to the agent's stdin as NDJSON.
+     *
+     * @param message - The message object to send
+     * @returns true if the write was accepted, false if backpressure or error
+     */
+    write(message: object): boolean;
+    /**
+     * Terminate the agent process gracefully.
+     *
+     * Sends SIGTERM first, then SIGKILL after timeout if process doesn't exit.
+     *
+     * @param timeout - Timeout in milliseconds before SIGKILL (default: 5000ms)
+     * @returns Promise that resolves when process has exited
+     */
+    terminate(timeout?: number): Promise<void>;
+    /**
+     * Wait for the process to exit.
+     *
+     * @returns Promise that resolves when process exits
+     */
+    private waitForExit;
+}

package/out/tsc/workers/acp-worker/src/registry-launcher/runtime/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime module barrel export.
+ *
+ * Re-exports the public API for agent runtime management.
+ *
+ * @module runtime
+ */
+export type { RuntimeState, AgentRuntime } from './types.js';
+export { AgentRuntimeImpl } from './agent-runtime.js';
+export { AgentRuntimeManager } from './manager.js';
+export type { AgentExitCallback } from './manager.js';

package/out/tsc/workers/acp-worker/src/registry-launcher/runtime/manager.d.ts

@@ -0,0 +1,82 @@
+import type { AgentRuntime } from './types.js';
+import type { SpawnCommand } from '../registry/types.js';
+/**
+ * Callback type for agent exit events.
+ */
+export type AgentExitCallback = (agentId: string, code: number | null) => void;
+/**
+ * Manager for agent runtime lifecycle.
+ *
+ * Handles spawning, tracking, and terminating agent processes.
+ * Stores runtimes in a Map keyed by agentId.
+ */
+export declare class AgentRuntimeManager {
+    /** Map of agentId to AgentRuntime instances */
+    private readonly runtimes;
+    /** Registered callbacks for agent exit events */
+    private readonly exitCallbacks;
+    /**
+     * Get an existing runtime or spawn a new one for the given agentId.
+     *
+     * If a runtime already exists for the agentId, returns it.
+     * Otherwise, spawns a new agent process using the provided spawn command.
+     *
+     * @param agentId - The agent identifier
+     * @param spawnCommand - The resolved spawn command for spawning a new process
+     * @returns The existing or newly spawned AgentRuntime
+     */
+    getOrSpawn(agentId: string, spawnCommand: SpawnCommand): Promise<AgentRuntime>;
+    /**
+     * Get an existing runtime without spawning.
+     *
+     * @param agentId - The agent identifier
+     * @returns The AgentRuntime if it exists, undefined otherwise
+     */
+    get(agentId: string): AgentRuntime | undefined;
+    /**
+     * Terminate a specific agent runtime.
+     *
+     * Sends SIGTERM to the agent process and waits for it to exit.
+     * If the process doesn't exit within the timeout, sends SIGKILL.
+     *
+     * @param agentId - The agent identifier
+     * @param timeout - Timeout in milliseconds before SIGKILL (default: 5000ms)
+     */
+    terminate(agentId: string, timeout?: number): Promise<void>;
+    /**
+     * Terminate all agent runtimes for graceful shutdown.
+     *
+     * @param timeout - Timeout in milliseconds before SIGKILL (default: 5000ms)
+     */
+    terminateAll(timeout?: number): Promise<void>;
+    /**
+     * Register a callback for agent exit events.
+     *
+     * The callback is invoked when an agent process exits unexpectedly.
+     *
+     * @param callback - Function to call when an agent exits
+     */
+    onAgentExit(callback: AgentExitCallback): void;
+    /**
+     * Handle agent process exit.
+     *
+     * Removes the runtime from the map and notifies registered callbacks.
+     *
+     * @param agentId - The agent identifier
+     * @param code - The exit code (null if terminated by signal)
+     */
+    private handleAgentExit;
+    /**
+     * Get the number of active runtimes.
+     *
+     * @returns The count of runtimes currently in the map
+     */
+    get size(): number;
+    /**
+     * Check if a runtime exists for the given agentId.
+     *
+     * @param agentId - The agent identifier
+     * @returns true if a runtime exists, false otherwise
+     */
+    has(agentId: string): boolean;
+}

package/out/tsc/workers/acp-worker/src/registry-launcher/runtime/types.d.ts

@@ -0,0 +1,20 @@
+import type { ChildProcess } from 'child_process';
+/**
+ * State of an agent runtime.
+ */
+export type RuntimeState = 'starting' | 'running' | 'stopping' | 'stopped';
+/**
+ * Agent runtime representing a spawned agent process.
+ */
+export interface AgentRuntime {
+    /** Agent identifier */
+    agentId: string;
+    /** Current state */
+    state: RuntimeState;
+    /** Child process reference */
+    process: ChildProcess;
+    /** Write a message to the agent's stdin */
+    write(message: object): boolean;
+    /** Terminate the agent process */
+    terminate(timeout?: number): Promise<void>;
+}

package/out/tsc/workers/acp-worker/src/registry-launcher/stream/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stream module barrel export.
+ *
+ * Re-exports the public API for NDJSON stream handling.
+ *
+ * @module stream
+ */
+export { NDJSONHandler, type INDJSONHandler, type MessageCallback, type ErrorCallback, } from './ndjson-handler.js';

package/out/tsc/workers/acp-worker/src/registry-launcher/stream/ndjson-handler.d.ts

@@ -0,0 +1,119 @@
+/**
+ * NDJSON (Newline-Delimited JSON) stream handler for the Registry Launcher.
+ *
+ * Handles buffering and parsing of NDJSON messages from stdin and writing
+ * NDJSON messages to stdout. Supports partial reads across multiple chunks.
+ *
+ * @module stream/ndjson-handler
+ */
+import { Writable } from 'node:stream';
+/**
+ * Callback type for parsed messages.
+ */
+export type MessageCallback = (message: object) => void;
+/**
+ * Callback type for parse errors.
+ */
+export type ErrorCallback = (error: Error, line: string) => void;
+/**
+ * Interface for NDJSON stream handling.
+ */
+export interface INDJSONHandler {
+    /**
+     * Register a callback for parsed messages.
+     */
+    onMessage(callback: MessageCallback): void;
+    /**
+     * Register a callback for parse errors.
+     */
+    onError(callback: ErrorCallback): void;
+    /**
+     * Write a message to the output stream.
+     * @returns true if write was successful, false if stream is not writable
+     */
+    write(message: object): boolean;
+    /**
+     * Process incoming data chunk (call from stdin 'data' event).
+     */
+    processChunk(chunk: Buffer): void;
+}
+/**
+ * NDJSON stream handler implementation.
+ *
+ * This class handles:
+ * - Buffering incoming data until complete newline-delimited messages are received
+ * - Handling partial JSON messages that span multiple read operations
+ * - Appending newline characters after each JSON message when writing
+ * - Splitting on newline boundaries when reading
+ * - Logging errors and skipping malformed lines
+ */
+export declare class NDJSONHandler implements INDJSONHandler {
+    /** Buffer for accumulating partial data */
+    private buffer;
+    /** Output stream for writing messages */
+    private readonly output;
+    /** Registered message callback */
+    private messageCallback;
+    /** Registered error callback */
+    private errorCallback;
+    /**
+     * Create a new NDJSONHandler.
+     * @param output - Writable stream for output (typically process.stdout)
+     */
+    constructor(output: Writable);
+    /**
+     * Register a callback for parsed messages.
+     * Only one callback can be registered at a time.
+     *
+     * @param callback - Function to call with each parsed message
+     */
+    onMessage(callback: MessageCallback): void;
+    /**
+     * Register a callback for parse errors.
+     * Only one callback can be registered at a time.
+     *
+     * @param callback - Function to call with parse errors
+     */
+    onError(callback: ErrorCallback): void;
+    /**
+     * Write a message to the output stream.
+     *
+     * Serializes the message as JSON and appends a newline character.
+     *
+     *  @param message - Object to serialize and write
+     * @returns true if write was successful, false if stream is not writable
+     */
+    write(message: object): boolean;
+    /**
+     * Process incoming data chunk.
+     *
+     * Buffers data and emits complete messages when newline boundaries are found.
+     * Handles partial messages that span multiple chunks.
+     *
+     * @param chunk - Buffer containing incoming data
+     */
+    processChunk(chunk: Buffer): void;
+    /**
+     * Process the internal buffer, extracting and parsing complete lines.
+     *
+     * Splits on newline boundaries and parses each complete line as JSON.
+     * Incomplete lines remain in the buffer for the next chunk.
+     */
+    private processBuffer;
+    /**
+     * Parse a single line as JSON and emit the message.
+     *
+     * If parsing fails, logs the error and invokes the error callback.
+     * Malformed lines are skipped.
+     *
+     * @param line - Line to parse as JSON
+     */
+    private parseLine;
+    /**
+     * Truncate a line for logging purposes.
+     * @param line - Line to truncate
+     * @param maxLength - Maximum length (default: 100)
+     * @returns Truncated line with ellipsis if needed
+     */
+    private truncateLine;
+}

package/out/tsc/workers/acp-worker/src/registry-launcher/test-utils/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Test Utilities for Registry Launcher
+ *
+ * Provides mock implementations and test helpers for unit and integration testing
+ * of the registry launcher components.
+ *
+ * @module registry-launcher/test-utils
+ */
+import { EventEmitter } from 'node:events';
+import { Readable, Writable } from 'node:stream';
+import type { BinaryTarget, Distribution, Platform, Registry, RegistryAgent } from '../registry/types.js';
+/**
+ * Create a mock Registry with the specified agents.
+ *
+ * Fills in default values for any missing required fields in the agent definitions.
+ *
+ * @param agents - Partial agent definitions to include in the registry
+ * @returns A complete Registry object with the specified agents
+ *
+ * @example
+ * ```typescript
+ * const registry = createMockRegistry([
+ *   { id: 'agent-1', name: 'Test Agent 1' },
+ *   { id: 'agent-2', name: 'Test Agent 2', distribution: { uvx: { package: 'my-agent' } } },
+ * ]);
+ * ```
+ */
+export declare function createMockRegistry(agents: Partial<RegistryAgent>[]): Registry;
+/**
+ * Create a mock agent with a specific distribution type.
+ *
+ * Helper function for creating agents with different distribution configurations.
+ *
+ * @param id - Agent identifier
+ * @param distribution - Distribution configuration
+ * @param overrides - Additional agent properties to override
+ * @returns A complete RegistryAgent object
+ */
+export declare function createMockAgent(id: string, distribution: Distribution, overrides?: Partial<Omit<RegistryAgent, 'id' | 'distribution'>>): RegistryAgent;
+/**
+ * Create a mock agent with binary distribution for a specific platform.
+ *
+ * @param id - Agent identifier
+ * @param platforms - Map of platform to binary target
+ * @param overrides - Additional agent properties
+ * @returns A RegistryAgent with binary distribution
+ */
+export declare function createMockBinaryAgent(id: string, platforms: Partial<Record<Platform, BinaryTarget>>, overrides?: Partial<Omit<RegistryAgent, 'id' | 'distribution'>>): RegistryAgent;
+/**
+ * Create a mock agent with npx distribution.
+ *
+ * @param id - Agent identifier
+ * @param packageName - NPM package name (can include version like "pkg@1.0.0")
+ * @param args - Optional command-line arguments
+ * @param overrides - Additional agent properties
+ * @returns A RegistryAgent with npx distribution
+ */
+export declare function createMockNpxAgent(id: string, packageName: string, args?: string[], overrides?: Partial<Omit<RegistryAgent, 'id' | 'distribution'>>): RegistryAgent;
+/**
+ * Create a mock agent with uvx distribution.
+ *
+ * @param id - Agent identifier
+ * @param packageName - Python package name (can include version like "pkg@latest")
+ * @param args - Optional command-line arguments
+ * @param overrides - Additional agent properties
+ * @returns A RegistryAgent with uvx distribution
+ */
+export declare function createMockUvxAgent(id: string, packageName: string, args?: string[], overrides?: Partial<Omit<RegistryAgent, 'id' | 'distribution'>>): RegistryAgent;
+/**
+ * Mock ChildProcess interface for testing agent runtime management.
+ *
+ * Provides controllable stdin/stdout/stderr streams and process lifecycle events.
+ */
+export interface MockChildProcess extends EventEmitter {
+    /** Mock stdin stream for writing to the process */
+    stdin: Writable & {
+        destroyed: boolean;
+    };
+    /** Mock stdout stream for reading from the process */
+    stdout: Readable;
+    /** Mock stderr stream for reading error output */
+    stderr: Readable;
+    /** Process ID (mock value) */
+    pid: number;
+    /** Whether the process has been killed */
+    killed: boolean;
+    /** Exit code (null until process exits) */
+    exitCode: number | null;
+    /** Signal that caused exit (null if exited normally) */
+    signalCode: string | null;
+    /**
+     * Send a kill signal to the mock process.
+     * @param signal - Signal to send (default: 'SIGTERM')
+     * @returns true if signal was sent
+     */
+    kill(signal?: string): boolean;
+    /**
+     * Simulate the process exiting with a specific code.
+     * @param code - Exit code (0 for success)
+     * @param signal - Optional signal that caused exit
+     */
+    simulateExit(code: number, signal?: string | null): void;
+    /**
+     * Simulate the process spawning successfully.
+     */
+    simulateSpawn(): void;
+    /**
+     * Simulate a spawn error.
+     * @param error - Error to emit
+     */
+    simulateError(error: Error): void;
+    /**
+     * Write data to stdout as if the process produced it.
+     * @param data - Data to write
+     */
+    writeToStdout(data: string): void;
+    /**
+     * Write data to stderr as if the process produced it.
+     * @param data - Data to write
+     */
+    writeToStderr(data: string): void;
+    /**
+     * Get all data written to stdin.
+     * @returns Array of strings written to stdin
+     */
+    getStdinWrites(): string[];
+}
+/**
+ * Create a mock ChildProcess for testing agent runtime management.
+ *
+ * The mock process provides controllable streams and lifecycle events,
+ * allowing tests to simulate various process behaviors.
+ *
+ * @param pid - Optional process ID (default: random)
+ * @returns A MockChildProcess instance
+ *
+ * @example
+ * ```typescript
+ * const mockProcess = createMockAgentProcess();
+ *
+ * // Simulate successful spawn
+ * mockProcess.simulateSpawn();
+ *
+ * // Write to stdout as if the agent produced output
+ * mockProcess.writeToStdout('{"jsonrpc":"2.0","id":1,"result":{}}\n');
+ *
+ * // Simulate process exit
+ * mockProcess.simulateExit(0);
+ * ```
+ */
+export declare function createMockAgentProcess(pid?: number): MockChildProcess;
+/**
+ * Test NDJSON stream pair for testing stream handling.
+ *
+ * Provides connected input/output streams for testing NDJSON message flow.
+ */
+export interface TestNDJSONStream {
+    /** Writable stream to send data into the handler */
+    input: Writable;
+    /** Writable stream to capture data from the handler */
+    output: Writable;
+    /**
+     * Write a JSON message to the input stream.
+     * @param message - Object to serialize and write as NDJSON
+     */
+    writeMessage(message: object): void;
+    /**
+     * Get all messages written to the output stream.
+     * @returns Array of parsed JSON objects
+     */
+    getOutputMessages(): object[];
+    /**
+     * Get raw output data as string.
+     * @returns Concatenated output data
+     */
+    getRawOutput(): string;
+}
+/**
+ * Create a test NDJSON stream pair for testing stream handling.
+ *
+ * The input stream can be used to feed data into an NDJSON handler,
+ * while the output stream captures data written by the handler.
+ *
+ * @returns A TestNDJSONStream with connected input/output streams
+ *
+ * @example
+ * ```typescript
+ * const { input, output, writeMessage, getOutputMessages } = createTestNDJSONStream();
+ *
+ * // Create handler with the output stream
+ * const handler = new NDJSONHandler(output);
+ *
+ * // Feed data through input
+ * writeMessage({ jsonrpc: '2.0', method: 'test', id: 1 });
+ *
+ * // Check what was written to output
+ * const messages = getOutputMessages();
+ * ```
+ */
+export declare function createTestNDJSONStream(): TestNDJSONStream;
+/**
+ * Create a mock fetch function for testing registry fetching.
+ *
+ * @param responseData - Data to return from fetch
+ * @param options - Optional configuration for the mock
+ * @returns A mock fetch function
+ */
+export declare function createMockFetch(responseData: unknown, options?: {
+    /** HTTP status code (default: 200) */
+    status?: number;
+    /** Whether to simulate network error */
+    networkError?: boolean;
+    /** Error message for network error */
+    errorMessage?: string;
+}): typeof fetch;
+/**
+ * Wait for a specified number of milliseconds.
+ *
+ * Utility function for tests that need to wait for async operations.
+ *
+ * @param ms - Milliseconds to wait
+ * @returns Promise that resolves after the delay
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Create a deferred promise for testing async operations.
+ *
+ * @returns Object with promise and resolve/reject functions
+ */
+export declare function createDeferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: unknown) => void;
+};