@stdiobus/workers-registry 1.3.7

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

@@ -0,0 +1,163 @@
+/**
+ * Type definitions for the MCP-ACP protocol proxy.
+ *
+ * This module defines TypeScript interfaces for all state objects and message types
+ * used by the proxy to convert between Model Context Protocol (MCP) and Agent Client
+ * Protocol (ACP).
+ */
+/**
+ * Configuration loaded from environment variables.
+ *
+ * @example
+ * ```typescript
+ * const config: ProxyConfig = {
+ *   acpHost: process.env.ACP_HOST || '127.0.0.1',
+ *   acpPort: parseInt(process.env.ACP_PORT || '9011', 10),
+ *   agentId: process.env.AGENT_ID!
+ * };
+ * ```
+ */
+export interface ProxyConfig {
+    /** ACP_HOST environment variable (default: 127.0.0.1) */
+    acpHost: string;
+    /** ACP_PORT environment variable (default: 9011) */
+    acpPort: number;
+    /** AGENT_ID environment variable (required) */
+    agentId: string;
+}
+/**
+ * Pending request tracking information.
+ *
+ * Tracks requests that have been sent but not yet received a response.
+ * Used for correlating responses with their original requests and handling
+ * queued requests (e.g., session/new followed by session/prompt).
+ */
+export interface PendingRequest {
+    /** Original MCP or ACP method name */
+    method: string;
+    /** Original request parameters */
+    params?: unknown;
+    /** For queued requests: original request ID (session/new -> session/prompt) */
+    originalId?: string | number;
+    /** For queued prompts: the prompt text to send after session creation */
+    promptText?: string;
+}
+/**
+ * Session state maintained by the proxy.
+ *
+ * Manages session identifiers, pending requests, and accumulated text for
+ * streaming responses.
+ *
+ * @example
+ * ```typescript
+ * const state: SessionState = {
+ *   proxySessionId: 'proxy-1234567890',
+ *   acpSessionId: 'session-abc123',
+ *   pendingRequests: new Map(),
+ *   accumulatedText: new Map()
+ * };
+ * ```
+ */
+export interface SessionState {
+    /** Session ID for stdio Bus routing (generated by proxy) */
+    proxySessionId: string | null;
+    /** Session ID from ACP agent (received from session/new response) */
+    acpSessionId: string | null;
+    /** Map of request ID to pending request information */
+    pendingRequests: Map<string | number, PendingRequest>;
+    /** Map of request ID to accumulated streaming text */
+    accumulatedText: Map<string | number, string>;
+}
+/**
+ * MCP JSON-RPC request message.
+ *
+ * Represents a request from an MCP client (like Kiro IDE) to the proxy.
+ * Uses JSON-RPC 2.0 format.
+ */
+export type MCPRequest = {
+    /** JSON-RPC version (always '2.0') */
+    jsonrpc: '2.0';
+    /** Request identifier (string or number) */
+    id: string | number;
+    /** MCP method name (e.g., 'initialize', 'tools/list', 'tools/call') */
+    method: string;
+    /** Method-specific parameters */
+    params?: unknown;
+};
+/**
+ * MCP JSON-RPC response message.
+ *
+ * Represents a response from the proxy to an MCP client.
+ * Contains either a result or an error, never both.
+ */
+export type MCPResponse = {
+    /** JSON-RPC version (always '2.0') */
+    jsonrpc: '2.0';
+    /** Request identifier matching the original request */
+    id: string | number;
+    /** Success result (present if no error) */
+    result?: unknown;
+    /** Error information (present if request failed) */
+    error?: {
+        /** JSON-RPC error code */
+        code: number;
+        /** Human-readable error message */
+        message: string;
+    };
+};
+/**
+ * ACP JSON-RPC request message.
+ *
+ * Represents a request from the proxy to an ACP agent via stdio Bus.
+ * Extends JSON-RPC 2.0 with ACP-specific fields.
+ */
+export type ACPRequest = {
+    /** JSON-RPC version (always '2.0') */
+    jsonrpc: '2.0';
+    /** Request identifier (string or number) */
+    id: string | number;
+    /** ACP method name (e.g., 'initialize', 'session/new', 'session/prompt') */
+    method: string;
+    /** Target agent identifier */
+    agentId: string;
+    /** Session identifier for stdio Bus routing */
+    sessionId: string;
+    /** Method-specific parameters */
+    params?: unknown;
+};
+/**
+ * ACP JSON-RPC response message.
+ *
+ * Represents a response from an ACP agent to the proxy.
+ * Contains either a result or an error, never both.
+ */
+export type ACPResponse = {
+    /** JSON-RPC version (always '2.0') */
+    jsonrpc: '2.0';
+    /** Request identifier matching the original request */
+    id: string | number;
+    /** Success result (present if no error) */
+    result?: unknown;
+    /** Error information (present if request failed) */
+    error?: {
+        /** JSON-RPC error code */
+        code: number;
+        /** Human-readable error message */
+        message: string;
+    };
+};
+/**
+ * ACP JSON-RPC notification message.
+ *
+ * Represents a notification from an ACP agent to the proxy.
+ * Notifications do not have an id field and do not expect a response.
+ * Used for streaming updates like agent_message_chunk.
+ */
+export type ACPNotification = {
+    /** JSON-RPC version (always '2.0') */
+    jsonrpc: '2.0';
+    /** Notification method name (e.g., 'session/update') */
+    method: string;
+    /** Notification-specific parameters */
+    params?: unknown;
+};

package/out/tsc/workers/acp-worker/src/registry-launcher/config/api-keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * API keys structure for a single agent.
+ */
+export interface AgentApiKeys {
+    /** API key for the agent */
+    apiKey: string;
+    /** Environment variables to pass to the agent */
+    env: Record<string, string>;
+}
+/**
+ * API keys file structure.
+ */
+export interface ApiKeysFile {
+    /** Map of agent ID to API keys */
+    agents: Record<string, AgentApiKeys>;
+    /** Version of the API keys file format */
+    version: string;
+}
+/**
+ * Load API keys from a JSON file.
+ *
+ * @param apiKeysPath - Path to the API keys JSON file
+ * @returns Loaded API keys or empty object if file is missing/malformed
+ */
+export declare function loadApiKeys(apiKeysPath: string): Record<string, AgentApiKeys>;
+/**
+ * Get API key for a specific agent.
+ *
+ * @param apiKeys - Loaded API keys
+ * @param agentId - Agent ID to get key for
+ * @returns API key or undefined if not found
+ */
+export declare function getAgentApiKey(apiKeys: Record<string, AgentApiKeys>, agentId: string): string | undefined;
+/**
+ * Get environment variables for a specific agent.
+ *
+ * @param apiKeys - Loaded API keys
+ * @param agentId - Agent ID to get env vars for
+ * @returns Environment variables or empty object if not found
+ */
+export declare function getAgentEnv(apiKeys: Record<string, AgentApiKeys>, agentId: string): Record<string, string>;

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

@@ -0,0 +1,17 @@
+import { LauncherConfig } from './types.js';
+/**
+ * Load configuration from a JSON file.
+ *
+ * This function:
+ * 1. Reads the config file from the specified path
+ * 2. Parses it as JSON
+ * 3. Validates and applies default values for missing fields
+ * 4. Applies environment variable overrides
+ *
+ * If the config file is missing or malformed, default values are used
+ * and a warning is logged to stderr.
+ *
+ * @param configPath - Path to the JSON config file (optional)
+ * @returns Loaded and validated configuration
+ */
+export declare function loadConfig(configPath?: string): LauncherConfig;

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

@@ -0,0 +1,10 @@
+/**
+ * Config module barrel export.
+ *
+ * Re-exports the public API for configuration loading.
+ *
+ * @module config
+ */
+export { loadConfig } from './config.js';
+export { DEFAULT_CONFIG, type LauncherConfig } from './types.js';
+export { loadApiKeys, getAgentApiKey, getAgentEnv, type AgentApiKeys, type ApiKeysFile } from './api-keys.js';

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

@@ -0,0 +1,15 @@
+/**
+ * Configuration for the Registry Launcher.
+ */
+export interface LauncherConfig {
+    /** Registry URL (default: official ACP Registry) */
+    registryUrl: string;
+    /** Path to API keys JSON file (default: ./api-keys.json) */
+    apiKeysPath: string;
+    /** Agent shutdown timeout in seconds (default: 5) */
+    shutdownTimeoutSec: number;
+}
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_CONFIG: LauncherConfig;

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

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

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

@@ -0,0 +1,77 @@
+/**
+ * Logging utilities for the Registry Launcher.
+ *
+ * Provides structured logging to stderr with ISO 8601 timestamps and severity levels.
+ * All logs go to stderr only - stdout is reserved for NDJSON protocol messages.
+ *
+ * @module log
+ */
+/**
+ * Log severity levels.
+ */
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+/**
+ * Log a message to stderr with ISO 8601 timestamp and severity level.
+ *
+ * @param level - Severity level (DEBUG, INFO, WARN, ERROR)
+ * @param message - Log message
+ * @param context - Optional context identifier (defaults to 'registry-launcher')
+ */
+export declare function log(level: LogLevel, message: string, context?: string): void;
+/**
+ * Log an agent spawn event.
+ *
+ * @param agentId - The agent identifier
+ * @param command - The spawn command
+ * @param args - The spawn command arguments
+ */
+export declare function logSpawn(agentId: string, command: string, args: string[]): void;
+/**
+ * Log an agent exit event.
+ *
+ * @param agentId - The agent identifier
+ * @param exitCode - The exit code (null if terminated by signal)
+ * @param signal - The signal that terminated the process (null if exited normally)
+ */
+export declare function logExit(agentId: string, exitCode: number | null, signal?: string | null): void;
+/**
+ * Log a backpressure warning when writing to an agent process fails.
+ *
+ * @param agentId - The agent identifier
+ */
+export declare function logBackpressure(agentId: string): void;
+/**
+ * Log an error when an agent's stdin closes unexpectedly.
+ *
+ * @param agentId - The agent identifier
+ * @param error - The error that occurred
+ */
+export declare function logStdinClosed(agentId: string, error?: Error): void;
+/**
+ * Convenience function for logging debug messages.
+ *
+ * @param message - Debug message
+ * @param context - Optional context identifier
+ */
+export declare function logDebug(message: string, context?: string): void;
+/**
+ * Convenience function for logging info messages.
+ *
+ * @param message - Info message
+ * @param context - Optional context identifier
+ */
+export declare function logInfo(message: string, context?: string): void;
+/**
+ * Convenience function for logging warning messages.
+ *
+ * @param message - Warning message
+ * @param context - Optional context identifier
+ */
+export declare function logWarn(message: string, context?: string): void;
+/**
+ * Convenience function for logging error messages.
+ *
+ * @param message - Error message
+ * @param context - Optional context identifier
+ */
+export declare function logError(message: string, context?: string): void;

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

@@ -0,0 +1,109 @@
+/**
+ * Registry Index for the ACP Registry.
+ *
+ * Handles fetching, parsing, and querying the ACP Registry.
+ * Supports configurable registry URL via environment variable.
+ *
+ * @module registry/index
+ */
+import { Registry, RegistryAgent, SpawnCommand } from './types.js';
+export type { Platform, BinaryDistribution, BinaryTarget, NpxDistribution, UvxDistribution, Distribution, RegistryAgent, Registry, SpawnCommand, } from './types.js';
+export { PlatformNotSupportedError, NoDistributionError, getCurrentPlatform, resolve } from './resolver.js';
+/**
+ * Error thrown when registry fetch fails.
+ */
+export declare class RegistryFetchError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when registry JSON is malformed.
+ */
+export declare class RegistryParseError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when an agent is not found in the registry.
+ */
+export declare class AgentNotFoundError extends Error {
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+/**
+ * Interface for the RegistryIndex.
+ */
+export interface IRegistryIndex {
+    /**
+     * Fetch and parse the ACP Registry from the configured URL.
+     * @throws RegistryFetchError if fetch fails
+     * @throws RegistryParseError if JSON is malformed
+     */
+    fetch(): Promise<void>;
+    /**
+     * Look up an agent by ID.
+     * @returns The agent entry or undefined if not found
+     */
+    lookup(agentId: string): RegistryAgent | undefined;
+    /**
+     * Resolve an agent ID to a spawn command.
+     * @throws AgentNotFoundError if agent not in registry
+     * @throws PlatformNotSupportedError if binary distribution doesn't support current platform
+     */
+    resolve(agentId: string): SpawnCommand;
+}
+/**
+ * Parse and validate registry JSON data.
+ *
+ * @param data - Raw JSON data to parse
+ * @returns Parsed and validated Registry object
+ * @throws RegistryParseError if JSON is malformed or invalid
+ */
+export declare function parseRegistry(data: unknown): Registry;
+/**
+ * Registry Index implementation.
+ *
+ * Fetches, parses, and provides lookup functionality for the ACP Registry.
+ */
+export declare class RegistryIndex implements IRegistryIndex {
+    /** Configured registry URL */
+    private readonly registryUrl;
+    /** Parsed registry data (null until fetch() is called) */
+    private registry;
+    /** Map of agent ID to agent entry for fast lookup */
+    private agentMap;
+    /**
+     * Create a new RegistryIndex.
+     *
+     * @param registryUrl - URL to fetch the registry from (can be overridden by ACP_REGISTRY_URL env var)
+     */
+    constructor(registryUrl: string);
+    /**
+     * Fetch and parse the ACP Registry from the configured URL.
+     *
+     * @throws RegistryFetchError if fetch fails
+     * @throws RegistryParseError if JSON is malformed
+     */
+    fetch(): Promise<void>;
+    /**
+     * Look up an agent by ID.
+     *
+     * @param agentId - Agent ID to look up
+     * @returns The agent entry or undefined if not found
+     */
+    lookup(agentId: string): RegistryAgent | undefined;
+    /**
+     * Resolve an agent ID to a spawn command.
+     *
+     * @param agentId - Agent ID to resolve
+     * @returns Resolved spawn command
+     * @throws AgentNotFoundError if agent not in registry
+     * @throws PlatformNotSupportedError if binary distribution doesn't support current platform
+     */
+    resolve(agentId: string): SpawnCommand;
+    /**
+     * Get the parsed registry data.
+     * @returns The parsed registry or null if not yet fetched
+     */
+    getRegistry(): Registry | null;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Distribution Resolver for the ACP Registry.
+ *
+ * Resolves distribution metadata to spawn commands based on distribution type.
+ * Supports binary (platform-specific), npx (npm), and uvx (Python) distributions.
+ *
+ * @module registry/resolver
+ */
+import { BinaryDistribution, Distribution, NpxDistribution, Platform, SpawnCommand, UvxDistribution } from './types.js';
+/**
+ * Error thrown when the current platform is not supported by a binary distribution.
+ */
+export declare class PlatformNotSupportedError extends Error {
+    readonly agentId: string;
+    readonly platform: Platform;
+    constructor(agentId: string, platform: Platform);
+}
+/**
+ * Error thrown when no supported distribution type is available.
+ */
+export declare class NoDistributionError extends Error {
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+/**
+ * Get the current platform identifier.
+ * Maps Node.js platform/arch to ACP Registry platform format.
+ *
+ * @returns Platform identifier for the current OS and architecture
+ */
+export declare function getCurrentPlatform(): Platform;
+/**
+ * Resolve a binary distribution to a spawn command.
+ *
+ * @param distribution - Binary distribution to resolve
+ * @param agentId - Agent ID for error messages
+ * @returns Resolved spawn command
+ * @throws PlatformNotSupportedError if current platform is not supported
+ */
+export declare function resolveBinary(distribution: BinaryDistribution, agentId: string): SpawnCommand;
+/**
+ * Resolve an npx distribution to a spawn command.
+ *
+ * @param distribution - NPX distribution to resolve
+ * @returns Resolved spawn command
+ */
+export declare function resolveNpx(distribution: NpxDistribution): SpawnCommand;
+/**
+ * Resolve a uvx distribution to a spawn command.
+ *
+ * @param distribution - UVX distribution to resolve
+ * @returns Resolved spawn command
+ */
+export declare function resolveUvx(distribution: UvxDistribution): SpawnCommand;
+/**
+ * Resolve a distribution to a spawn command.
+ *
+ * Priority order: npx > uvx > binary
+ * (npx/uvx are preferred as they don't require platform-specific handling)
+ *
+ * @param distribution - Distribution to resolve
+ * @param agentId - Agent ID for error messages
+ * @returns Resolved spawn command
+ * @throws PlatformNotSupportedError if binary distribution doesn't support current platform
+ * @throws NoDistributionError if no distribution type is available
+ */
+export declare function resolve(distribution: Distribution, agentId: string): SpawnCommand;

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

@@ -0,0 +1,105 @@
+/**
+ * Type definitions for the ACP Registry.
+ *
+ * These types match the official ACP Registry schema:
+ * https://cdn.agentclientprotocol.com/registry/v1/latest/registry.schema.json
+ */
+/**
+ * Platform identifiers for binary distributions.
+ * Format: <os>-<arch>
+ */
+export type Platform = 'darwin-aarch64' | 'darwin-x86_64' | 'linux-aarch64' | 'linux-x86_64' | 'windows-aarch64' | 'windows-x86_64';
+/**
+ * Binary target metadata for a specific platform.
+ */
+export interface BinaryTarget {
+    /** URL to download archive */
+    archive: string;
+    /** Command to execute after extraction */
+    cmd: string;
+    /** Optional command-line arguments */
+    args?: string[];
+    /** Optional environment variables */
+    env?: Record<string, string>;
+}
+/**
+ * Binary distribution - platform-specific executables.
+ */
+export type BinaryDistribution = Partial<Record<Platform, BinaryTarget>>;
+/**
+ * NPX distribution - Node packages run via npx.
+ */
+export interface NpxDistribution {
+    /** Package name with optional version (e.g., "@scope/pkg@1.0.0") */
+    package: string;
+    /** Optional command-line arguments */
+    args?: string[];
+    /** Optional environment variables */
+    env?: Record<string, string>;
+}
+/**
+ * UVX distribution - Python packages run via uvx.
+ */
+export interface UvxDistribution {
+    /** Package name with optional version (e.g., "pkg@latest") */
+    package: string;
+    /** Optional command-line arguments */
+    args?: string[];
+    /** Optional environment variables */
+    env?: Record<string, string>;
+}
+/**
+ * Distribution object containing one or more distribution types.
+ * An agent may provide multiple distribution methods.
+ */
+export interface Distribution {
+    /** Binary distribution (platform-specific executables) */
+    binary?: BinaryDistribution;
+    /** NPX distribution (Node packages) */
+    npx?: NpxDistribution;
+    /** UVX distribution (Python packages) */
+    uvx?: UvxDistribution;
+}
+/**
+ * Agent entry in the ACP Registry.
+ */
+export interface RegistryAgent {
+    /** Unique agent identifier */
+    id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Semantic version of the agent */
+    version: string;
+    /** Brief description */
+    description?: string;
+    /** Source code repository URL */
+    repository?: string;
+    /** Author/organization names */
+    authors?: string[];
+    /** SPDX license identifier */
+    license?: string;
+    /** Icon URL or path */
+    icon?: string;
+    /** Distribution methods */
+    distribution: Distribution;
+}
+/**
+ * Parsed ACP Registry structure.
+ */
+export interface Registry {
+    /** Registry schema version */
+    version: string;
+    /** List of registered agents */
+    agents: RegistryAgent[];
+}
+/**
+ * Resolved spawn command for an agent.
+ */
+export interface SpawnCommand {
+    /** Command to execute */
+    command: string;
+    /** Command-line arguments */
+    args: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Router module barrel export.
+ *
+ * Re-exports the public API for message routing.
+ *
+ * @module router
+ */
+export { MessageRouter, RoutingErrorCodes, createErrorResponse, extractAgentId, extractId, transformMessage, type ErrorResponse, type WriteCallback, } from './message-router.js';