@stdiobus/workers-registry 1.3.7

package/out/tsc/workers/acp-worker/src/mcp/manager.d.ts

@@ -0,0 +1,178 @@
+/**
+ * MCP Manager
+ *
+ * Manages multiple MCP server connections for a session.
+ * Handles connection lifecycle, tool discovery, and tool invocation.
+ *
+ * @module mcp/manager
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
+import type { MCPResource, MCPResourceReadResult, MCPServerConfig, MCPTool, MCPToolCallResult } from './types.js';
+/**
+ * Represents an active MCP connection with its client and transport.
+ */
+export interface MCPConnection {
+    /** The MCP SDK client instance */
+    client: Client;
+    /** The stdio transport for the connection */
+    transport: StdioClientTransport;
+    /** Server configuration */
+    config: MCPServerConfig;
+    /** Whether the connection is active */
+    connected: boolean;
+    /** Server capabilities from initialization handshake */
+    capabilities?: ServerCapabilities;
+    /** Error message if the server crashed */
+    crashError?: string;
+}
+/**
+ * Factory functions for creating MCP SDK instances.
+ * Used for dependency injection in tests.
+ */
+export interface MCPFactories {
+    /** Factory for creating Client instances */
+    createClient: (options: {
+        name: string;
+        version: string;
+    }) => Client;
+    /** Factory for creating StdioClientTransport instances */
+    createTransport: (options: {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    }) => StdioClientTransport;
+}
+/**
+ * Manages MCP server connections for a session.
+ */
+export declare class MCPManager {
+    /** Active connections keyed by server ID */
+    private connections;
+    /** Map from tool name to server ID for routing tool calls */
+    private toolToServer;
+    /** Callback for server crash notifications */
+    private onServerCrash?;
+    /** Factory functions for creating SDK instances (injectable for testing) */
+    private factories;
+    /**
+     * Create a new MCPManager instance.
+     *
+     * @param factories - Optional factory functions for dependency injection (used in tests)
+     */
+    constructor(factories?: Partial<MCPFactories>);
+    /**
+     * Set a callback to be notified when a server crashes.
+     *
+     * @param callback - Function to call when a server crashes
+     */
+    setOnServerCrash(callback: (serverId: string, error: string) => void): void;
+    /**
+     * Connect to MCP servers specified in the configuration.
+     *
+     * @param servers - Array of MCP server configurations
+     */
+    connect(servers: MCPServerConfig[]): Promise<void>;
+    /**
+     * Set up crash detection for an MCP server connection.
+     *
+     * @param serverId - The server ID
+     * @param client - The MCP client
+     */
+    private setupCrashDetection;
+    /**
+     * Get all available tools from connected MCP servers.
+     *
+     * @returns Combined list of tools from all connected servers
+     */
+    listTools(): Promise<MCPTool[]>;
+    /**
+     * Invoke a tool on the appropriate MCP server.
+     * - Finds the server that provides the tool
+     * - Calls client.callTool({ name, arguments }) on the appropriate connection
+     * - Handles CallToolResult response
+     * - Checks isError flag for failures
+     * - Returns errors for calls to crashed server
+     *
+     * @param name - The name of the tool to invoke
+     * @param args - The arguments to pass to the tool
+     * @param serverId - Optional server ID to call the tool on (if known)
+     * @returns The tool call result with content and error status
+     * @throws Error if tool is not found or server is not connected
+     */
+    callTool(name: string, args: Record<string, unknown>, serverId?: string): Promise<MCPToolCallResult>;
+    /**
+     * Get all available resources from connected MCP servers.
+     * - Calls client.listResources() to discover available resources
+     * - Stores resource definitions (uri, name, description, mimeType)
+     * - Handles pagination via nextCursor if present
+     *
+     * @returns Combined list of resources from all connected servers
+     */
+    listResources(): Promise<MCPResource[]>;
+    /**
+     * Read a resource from the appropriate MCP server.
+     * - Calls client.readResource({ uri }) on the appropriate connection
+     * - Handles TextResourceContents and BlobResourceContents
+     * - Determines which server handles the URI based on resource list
+     *
+     * @param uri - The URI of the resource to read
+     * @param serverId - Optional server ID to read from (if known)
+     * @returns The resource contents
+     * @throws Error if resource server is not found or not connected
+     */
+    readResource(uri: string, serverId?: string): Promise<MCPResourceReadResult>;
+    /**
+     * Get a connection by server ID.
+     *
+     * @param serverId - The server ID to look up
+     * @returns The connection or undefined if not found
+     */
+    getConnection(serverId: string): MCPConnection | undefined;
+    /**
+     * Get all active connections.
+     *
+     * @returns Array of all active connections
+     */
+    getAllConnections(): MCPConnection[];
+    /**
+     * Get server capabilities for a specific server.
+     *
+     * @param serverId - The server ID to look up
+     * @returns The server capabilities or undefined if not found/connected
+     */
+    getServerCapabilities(serverId: string): ServerCapabilities | undefined;
+    /**
+     * Close all MCP server connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Abort all pending MCP operations.
+     * Called when a session is cancelled to stop in-flight requests.
+     */
+    abortPendingOperations(): void;
+    /**
+     * Check if a server has crashed.
+     *
+     * @param serverId - The server ID to check
+     * @returns True if the server has crashed
+     */
+    isServerCrashed(serverId: string): boolean;
+    /**
+     * Get the crash error for a server.
+     *
+     * @param serverId - The server ID to check
+     * @returns The crash error message or undefined if not crashed
+     */
+    getServerCrashError(serverId: string): string | undefined;
+    /**
+     * Get all crashed servers.
+     *
+     * @returns Array of crashed server IDs with their error messages
+     */
+    getCrashedServers(): Array<{
+        serverId: string;
+        error: string;
+    }>;
+}

package/out/tsc/workers/acp-worker/src/mcp/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * MCP Types
+ *
+ * Type definitions for MCP client management.
+ *
+ * @module mcp/types
+ */
+/**
+ * Configuration for an MCP server connection.
+ * Matches the McpServerStdio type from ACP SDK.
+ */
+export interface MCPServerConfig {
+    /** Server identifier */
+    id: string;
+    /** Command to spawn the server */
+    command: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** Environment variables for the server process */
+    env?: Record<string, string>;
+}
+/**
+ * Represents an MCP tool definition.
+ */
+export interface MCPTool {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** JSON Schema for tool input */
+    inputSchema: Record<string, unknown>;
+    /** Server ID that provides this tool */
+    serverId: string;
+}
+/**
+ * Represents an MCP resource definition.
+ */
+export interface MCPResource {
+    /** Resource URI */
+    uri: string;
+    /** Resource name */
+    name: string;
+    /** Resource description */
+    description?: string;
+    /** MIME type */
+    mimeType?: string;
+    /** Server ID that provides this resource */
+    serverId: string;
+}
+/**
+ * Content types that can be returned from a tool call.
+ * Matches MCP SDK content types.
+ */
+export interface MCPTextContent {
+    type: 'text';
+    text: string;
+}
+export interface MCPImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface MCPEmbeddedResource {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+}
+export type MCPContent = MCPTextContent | MCPImageContent | MCPEmbeddedResource;
+/**
+ * Result of a tool call.
+ */
+export interface MCPToolCallResult {
+    /** Content blocks returned by the tool */
+    content: MCPContent[];
+    /** Whether the tool execution resulted in an error */
+    isError?: boolean;
+}
+/**
+ * Text resource contents from MCP server.
+ */
+export interface MCPTextResourceContents {
+    /** Resource URI */
+    uri: string;
+    /** MIME type */
+    mimeType?: string;
+    /** Text content */
+    text: string;
+}
+/**
+ * Blob resource contents from MCP server.
+ */
+export interface MCPBlobResourceContents {
+    /** Resource URI */
+    uri: string;
+    /** MIME type */
+    mimeType?: string;
+    /** Base64-encoded blob data */
+    blob: string;
+}
+/**
+ * Resource contents returned from readResource.
+ */
+export type MCPResourceContents = MCPTextResourceContents | MCPBlobResourceContents;
+/**
+ * Result of reading a resource.
+ */
+export interface MCPResourceReadResult {
+    /** Array of resource contents (usually one, but can be multiple) */
+    contents: MCPResourceContents[];
+}

package/out/tsc/workers/acp-worker/src/mcp-proxy/connection.d.ts

@@ -0,0 +1,80 @@
+import { ACPNotification, ACPRequest, ACPResponse, ProxyConfig } from './types.js';
+/**
+ * TCP connection handler with NDJSON streaming.
+ *
+ * Manages the TCP connection to stdio Bus, handling:
+ * - Connection establishment and lifecycle
+ * - NDJSON buffering and line parsing
+ * - Sending ACP requests
+ * - Receiving ACP responses and notifications
+ *
+ * @example
+ * ```typescript
+ * const connection = new ACPConnection(
+ *   config,
+ *   (msg) => console.log('Received:', msg),
+ *   (err) => console.error('Error:', err)
+ * );
+ *
+ * connection.send({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'initialize',
+ *   agentId: 'my-agent',
+ *   sessionId: 'session-123',
+ *   params: {}
+ * });
+ * ```
+ */
+export declare class ACPConnection {
+    private config;
+    private onMessage;
+    private onError;
+    private socket;
+    private buffer;
+    private connected;
+    /**
+     * Creates a new ACP connection.
+     *
+     * @param config - Proxy configuration with host and port
+     * @param onMessage - Callback for received ACP messages (responses or notifications)
+     * @param onError - Callback for connection errors
+     */
+    constructor(config: ProxyConfig, onMessage: (msg: ACPResponse | ACPNotification) => void, onError: (err: Error) => void);
+    /**
+     * Setup event handlers for the TCP socket.
+     *
+     * Handles connect, error, data, and close events.
+     */
+    private setupHandlers;
+    /**
+     * Buffer and parse NDJSON lines from incoming data.
+     *
+     * Accumulates data in a buffer and processes complete lines (ending with \n).
+     * Incomplete lines remain in the buffer until more data arrives.
+     *
+     * @param data - Raw data received from the socket
+     */
+    private handleData;
+    /**
+     * Send an ACP request as NDJSON.
+     *
+     * Serializes the request to JSON and appends a newline character.
+     * Logs the request to stderr for debugging.
+     *
+     * @param request - ACP request to send
+     */
+    send(request: ACPRequest): void;
+    /**
+     * Close the connection gracefully.
+     *
+     * Ends the socket connection, allowing any pending writes to complete.
+     */
+    close(): void;
+    /**
+     * Check if the connection is currently established.
+     *
+     * @returns true if connected, false otherwise
+     */
+    isConnected(): boolean;
+}

package/out/tsc/workers/acp-worker/src/mcp-proxy/converter.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Protocol conversion logic for the MCP-ACP protocol proxy.
+ *
+ * This module provides the ProtocolConverter class which handles bidirectional
+ * conversion between Model Context Protocol (MCP) and Agent Client Protocol (ACP).
+ *
+ * The converter:
+ * - Converts MCP requests to ACP requests
+ * - Converts ACP responses back to MCP responses
+ * - Handles ACP notifications (e.g., streaming text chunks)
+ * - Manages session creation and request queuing
+ */
+import { ACPNotification, ACPRequest, ACPResponse, MCPRequest, MCPResponse, ProxyConfig } from './types.js';
+import { StateManager } from './state.js';
+/**
+ * Protocol converter for MCP ↔ ACP translation.
+ *
+ * Handles all protocol conversion logic, including:
+ * - MCP method routing (initialize, tools/list, tools/call, etc.)
+ * - ACP response conversion based on pending request method
+ * - Session creation and queuing for tools/call without session
+ * - Text accumulation for streaming responses
+ *
+ * @example
+ * ```typescript
+ * const config = { acpHost: '127.0.0.1', acpPort: 9011, agentId: 'my-agent' };
+ * const state = new StateManager();
+ * const converter = new ProtocolConverter(config, state);
+ *
+ * const mcpReq = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
+ * const acpReq = converter.convertMCPtoACP(mcpReq);
+ * ```
+ */
+export declare class ProtocolConverter {
+    private config;
+    private state;
+    private sendACPCallback?;
+    constructor(config: ProxyConfig, state: StateManager, sendACPCallback?: ((request: ACPRequest) => void) | undefined);
+    /**
+     * Convert MCP request to ACP request.
+     *
+     * Routes MCP methods to appropriate conversion handlers. Some methods
+     * (like tools/list) return null because they're handled directly without
+     * forwarding to ACP.
+     *
+     * @param mcpReq - The MCP request to convert
+     * @returns ACP request to send, or null if response should be sent directly to MCP client
+     *
+     * @example
+     * ```typescript
+     * const mcpReq = { jsonrpc: '2.0', id: 1, method: 'initialize', params: {} };
+     * const acpReq = converter.convertMCPtoACP(mcpReq);
+     * // Returns ACP initialize request
+     * ```
+     */
+    convertMCPtoACP(mcpReq: MCPRequest): ACPRequest | null;
+    /**
+     * Convert ACP response to MCP response.
+     *
+     * Looks up the pending request to determine how to convert the response.
+     * Different ACP methods require different conversion logic.
+     *
+     * @param acpResp - The ACP response to convert
+     * @returns MCP response to send, or null if no response should be sent
+     *
+     * @example
+     * ```typescript
+     * const acpResp = { jsonrpc: '2.0', id: 1, result: { agentInfo: {...} } };
+     * const mcpResp = converter.convertACPtoMCP(acpResp);
+     * // Returns MCP initialize response
+     * ```
+     */
+    convertACPtoMCP(acpResp: ACPResponse): MCPResponse | null;
+    /**
+     * Handle ACP notifications (messages without id field).
+     *
+     * Processes notifications like session/update which contain streaming
+     * text chunks from the agent.
+     *
+     * @param notification - The ACP notification to handle
+     *
+     * @example
+     * ```typescript
+     * const notification = {
+     *   jsonrpc: '2.0',
+     *   method: 'session/update',
+     *   params: { update: { sessionUpdate: 'agent_message_chunk', content: { text: 'Hello' } } }
+     * };
+     * converter.handleACPNotification(notification);
+     * ```
+     */
+    handleACPNotification(notification: ACPNotification): void;
+    /**
+     * Convert MCP initialize request to ACP initialize request.
+     */
+    private convertInitialize;
+    /**
+     * Handle MCP tools/list request.
+     * Returns static tool list directly to MCP client without forwarding to ACP.
+     */
+    private handleToolsList;
+    /**
+     * Convert MCP tools/call request to ACP session/prompt request.
+     * If no ACP session exists, creates session/new request first and queues the prompt.
+     */
+    private convertToolsCall;
+    /**
+     * Handle MCP resources/list request.
+     * Returns empty resources array directly to MCP client.
+     */
+    private handleResourcesList;
+    /**
+     * Handle MCP resources/templates/list request.
+     * Returns empty resource templates array directly to MCP client.
+     */
+    private handleResourceTemplatesList;
+    /**
+     * Handle MCP prompts/list request.
+     * Returns empty prompts array directly to MCP client.
+     */
+    private handlePromptsList;
+    /**
+     * Handle unknown MCP method.
+     * Returns JSON-RPC error -32601 (method not found).
+     */
+    private handleUnknownMethod;
+    /**
+     * Convert ACP initialize response to MCP initialize response.
+     */
+    private convertInitializeResponse;
+    /**
+     * Handle ACP session/new response.
+     * Stores the ACP session ID and sends queued prompt if exists.
+     */
+    private handleSessionNewResponse;
+    /**
+     * Convert ACP session/prompt response to MCP tool call result.
+     * Returns accumulated text from streaming notifications.
+     */
+    private convertSessionPromptResponse;
+    /**
+     * Handle session/update notification.
+     * Accumulates text chunks for agent_message_chunk updates.
+     */
+    private handleSessionUpdate;
+    /**
+     * Send MCP response directly to stdout.
+     * Used for methods that don't require ACP forwarding.
+     */
+    private sendMCPDirect;
+    /**
+     * Send ACP request directly to TCP socket.
+     * Used for queued requests (session/new -> session/prompt).
+     */
+    private sendACPDirect;
+}

package/out/tsc/workers/acp-worker/src/mcp-proxy/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/out/tsc/workers/acp-worker/src/mcp-proxy/state.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Session state management for the MCP-ACP protocol proxy.
+ *
+ * This module provides the StateManager class which manages session identifiers,
+ * pending request tracking, and text accumulation for streaming responses.
+ */
+import { PendingRequest } from './types.js';
+/**
+ * Manages session state for the MCP-ACP proxy.
+ *
+ * Tracks proxy session ID, ACP session ID, pending requests,
+ * and accumulated text for streaming responses.
+ *
+ * @example
+ * ```typescript
+ * const state = new StateManager();
+ * const sessionId = state.ensureProxySessionId();
+ * state.addPendingRequest(1, { method: 'initialize', params: {} });
+ * const pending = state.takePendingRequest(1);
+ * ```
+ */
+export declare class StateManager {
+    private state;
+    constructor();
+    /**
+     * Generate unique proxy session ID on first request.
+     *
+     * The proxy session ID is used for stdio Bus routing to ensure all
+     * requests from this proxy instance are routed to the same worker.
+     *
+     * @returns The proxy session ID (generates new one if not exists)
+     *
+     * @example
+     * ```typescript
+     * const sessionId = state.ensureProxySessionId();
+     * // First call: 'proxy-1234567890'
+     * const sameId = state.ensureProxySessionId();
+     * // Subsequent calls: 'proxy-1234567890' (same value)
+     * ```
+     */
+    ensureProxySessionId(): string;
+    /**
+     * Store ACP session ID from session/new response.
+     *
+     * The ACP session ID is received from the agent and used for subsequent
+     * session-specific requests like session/prompt.
+     *
+     * @param sessionId - The session ID from the ACP agent
+     *
+     * @example
+     * ```typescript
+     * state.setAcpSessionId('session-abc123');
+     * ```
+     */
+    setAcpSessionId(sessionId: string): void;
+    /**
+     * Get current ACP session ID.
+     *
+     * @returns The ACP session ID, or null if no session has been created yet
+     *
+     * @example
+     * ```typescript
+     * const sessionId = state.getAcpSessionId();
+     * if (sessionId) {
+     *   // Can send session/prompt requests
+     * } else {
+     *   // Need to create session first
+     * }
+     * ```
+     */
+    getAcpSessionId(): string | null;
+    /**
+     * Track a pending request.
+     *
+     * Stores request information keyed by request ID for later correlation
+     * with responses. Used to track method, parameters, and queued requests.
+     *
+     * @param id - The request ID (string or number)
+     * @param request - The pending request information
+     *
+     * @example
+     * ```typescript
+     * state.addPendingRequest(1, {
+     *   method: 'session/prompt',
+     *   params: { prompt: 'Hello' }
+     * });
+     * ```
+     */
+    addPendingRequest(id: string | number, request: PendingRequest): void;
+    /**
+     * Retrieve and remove a pending request.
+     *
+     * Looks up a pending request by ID and removes it from the map.
+     * Returns undefined if no request with that ID exists.
+     *
+     * @param id - The request ID to look up
+     * @returns The pending request information, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const pending = state.takePendingRequest(1);
+     * if (pending) {
+     *   console.log(`Received response for ${pending.method}`);
+     * }
+     * ```
+     */
+    takePendingRequest(id: string | number): PendingRequest | undefined;
+    /**
+     * Accumulate text for streaming responses.
+     *
+     * Appends text chunks to the accumulated string for a given request ID.
+     * Used to collect agent_message_chunk notifications during session/prompt.
+     *
+     * @param id - The request ID
+     * @param text - The text chunk to append
+     *
+     * @example
+     * ```typescript
+     * state.accumulateText(1, 'Hello ');
+     * state.accumulateText(1, 'world!');
+     * const result = state.takeAccumulatedText(1);
+     * // result: 'Hello world!'
+     * ```
+     */
+    accumulateText(id: string | number, text: string): void;
+    /**
+     * Retrieve and clear accumulated text.
+     *
+     * Returns the accumulated text for a request ID and removes it from the map.
+     * Returns empty string if no text has been accumulated.
+     *
+     * @param id - The request ID
+     * @returns The accumulated text (empty string if none)
+     *
+     * @example
+     * ```typescript
+     * state.accumulateText(1, 'Hello ');
+     * state.accumulateText(1, 'world!');
+     * const text = state.takeAccumulatedText(1);
+     * // text: 'Hello world!'
+     * const again = state.takeAccumulatedText(1);
+     * // again: '' (cleared after first take)
+     * ```
+     */
+    takeAccumulatedText(id: string | number): string;
+    /**
+     * Find pending session/prompt request for notification handling.
+     *
+     * Searches through pending requests to find a session/prompt request.
+     * Used when processing session/update notifications to determine which
+     * request the notification belongs to.
+     *
+     * @returns Tuple of [requestId, pendingRequest] or null if not found
+     *
+     * @example
+     * ```typescript
+     * const result = state.findPendingPromptRequest();
+     * if (result) {
+     *   const [id, pending] = result;
+     *   state.accumulateText(id, 'chunk text');
+     * }
+     * ```
+     */
+    findPendingPromptRequest(): [string | number, PendingRequest] | null;
+}