@routecraft/ai 0.3.0 → 0.4.0-canary.10

package/dist/index.d.cts

@@ -1,5 +1,5 @@
+import { ResolveKey, Exchange, Destination, MergedOptions, CraftContext, CraftPlugin, DirectServerOptions, DirectRouteMetadata, Source } from '@routecraft/routecraft';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { Exchange, Destination, MergedOptions, CraftContext, CraftPlugin, DirectServerOptions, DirectRouteMetadata, Source } from '@routecraft/routecraft';
 
 /**
  * Cross-instance identity for @routecraft/ai: Symbol.for() keys and type guards.
@@ -10,9 +10,92 @@ declare const BRAND: {
 };
 declare function isMcpAdapter(obj: unknown): boolean;
 
-/** Store key for plugin-registered providers (provider id → LlmModelConfig). */
+/**
+ * Type registries for AI adapter compile-time safety via declaration merging.
+ *
+ * Users populate these empty interfaces to constrain `llm()` and `mcp()`
+ * adapters to only accept configured providers and servers. When a registry
+ * is empty, the adapter falls back to accepting any string.
+ *
+ * @example
+ * ```typescript
+ * declare module '@routecraft/ai' {
+ *   interface LlmProviderRegistry {
+ *     openai: true;
+ *     anthropic: true;
+ *     ollama: true;
+ *   }
+ *   interface McpServerRegistry {
+ *     github: true;
+ *     'local-postgres': true;
+ *   }
+ * }
+ *
+ * // Now llm('openai:gpt-5') autocompletes the provider prefix.
+ * // llm('qwen:model') shows a red line if qwen is not registered.
+ * // mcp('github:create_issue') autocompletes server names.
+ * ```
+ */
+
+/**
+ * Registry for configured LLM providers.
+ *
+ * Keys are provider names (e.g. 'openai', 'anthropic', 'ollama'),
+ * values should be `true`. Populate via declaration merging to constrain
+ * the `llm()` adapter's model ID prefix.
+ *
+ * @experimental
+ */
+interface LlmProviderRegistry {
+}
+/**
+ * Registry for configured MCP servers.
+ *
+ * Keys are server names (e.g. 'github', 'local-postgres'),
+ * values should be `true`. Populate via declaration merging to constrain
+ * the `mcp()` adapter's shorthand syntax.
+ *
+ * @experimental
+ */
+interface McpServerRegistry {
+}
+/**
+ * Resolved LLM model ID type.
+ * When `LlmProviderRegistry` is populated, constrains to `'provider:modelName'`
+ * where provider must be a registered key. Falls back to `string` when empty.
+ *
+ * @experimental
+ */
+type RegisteredLlmModelId = keyof LlmProviderRegistry extends never ? string : `${Extract<keyof LlmProviderRegistry, string>}:${string}`;
+/**
+ * Resolved MCP server key type.
+ * When `McpServerRegistry` is populated, resolves to the union of registered server keys
+ * (e.g. `'github' | 'local-postgres'`) via `ResolveKey<McpServerRegistry>`.
+ * Falls back to `string` when empty.
+ *
+ * For the `'server:tool'` shorthand format, see `RegisteredMcpShorthand`.
+ *
+ * @experimental
+ */
+type RegisteredMcpServer = ResolveKey<McpServerRegistry>;
+/**
+ * Resolved MCP shorthand type for 'server:tool' syntax.
+ * When `McpServerRegistry` is populated, constrains the server prefix.
+ * Falls back to `` `${string}:${string}` `` when empty.
+ *
+ * @experimental
+ */
+type RegisteredMcpShorthand = keyof McpServerRegistry extends never ? `${string}:${string}` : `${Extract<keyof McpServerRegistry, string>}:${string}`;
+
+/**
+ * Store key for plugin-registered providers (provider id -> LlmModelConfig).
+ * @experimental
+ */
 declare const ADAPTER_LLM_PROVIDERS: unique symbol;
-/** Store key for context-level default LLM options. */
+/**
+ * Store key for context-level default LLM options.
+ * @experimental
+ */
 declare const ADAPTER_LLM_OPTIONS: unique symbol;
 declare module "@routecraft/routecraft" {
     interface StoreRegistry {
@@ -152,10 +235,11 @@ interface LlmPluginOptions {
  * registered via llmPlugin({ providers: { ollama: { provider: "ollama" }, ... } }).
  * When options.outputSchema is provided, the result type narrows so body.output is typed downstream.
  *
+ * @experimental
  * @param modelId - "providerId:modelName"; the provider is resolved from the plugin, the model name is sent to the provider.
  * @param options - Optional overrides (systemPrompt, userPrompt, temperature, maxTokens, outputSchema, etc.). User prompt defaults to exchange.body.
  */
-declare function llm<S extends StandardSchemaV1 | undefined = undefined>(modelId: LlmModelId, options?: Partial<LlmOptions> & {
+declare function llm<S extends StandardSchemaV1 | undefined = undefined>(modelId: RegisteredLlmModelId, options?: Partial<LlmOptions> & {
     outputSchema?: S;
 }): Destination<unknown, LlmResultWithOutput<S>>;
 
@@ -164,6 +248,7 @@ declare function llm<S extends StandardSchemaV1 | undefined = undefined>(modelId
  * resolves the provider from the plugin store, merges options, and calls the provider with the model name.
  * Use with .enrich(llm("providerId:modelName", options)) or .to(llm(...)).
  *
+ * @experimental
  * @template S - Output schema type when outputSchema is provided; narrows result.output for downstream typing.
  */
 declare class LlmDestinationAdapter<S extends StandardSchemaV1 | undefined = undefined> implements Destination<unknown, LlmResultWithOutput<S>>, MergedOptions<LlmOptionsMerged> {
@@ -187,6 +272,8 @@ declare class LlmDestinationAdapter<S extends StandardSchemaV1 | undefined = und
  *
  * Advanced users can set the store directly: context.setStore(ADAPTER_LLM_PROVIDERS, map)
  * and context.setStore(ADAPTER_LLM_OPTIONS, partialOptions) without using this plugin.
+ *
+ * @experimental
  */
 declare function llmPlugin(options?: LlmPluginOptions): CraftPlugin;
 
@@ -196,14 +283,97 @@ declare function llmPlugin(options?: LlmPluginOptions): CraftPlugin;
  */
 declare function validateLlmPluginOptions(options: LlmPluginOptions): void;
 
-/** Store key set by mcpPlugin() when applied; routes using .from(mcp(...)) require it. */
+/**
+ * Central registry of all MCP tools from all sources.
+ * Stored in context store under MCP_TOOL_REGISTRY for agent adapter discovery.
+ *
+ * Sources:
+ * - "local": mcp() routes from ADAPTER_DIRECT_REGISTRY (tools exposed by this context)
+ * - stdio clients: long-lived subprocess MCP servers
+ * - HTTP clients: remote HTTP MCP servers (tools refreshed periodically)
+ *
+ * @experimental
+ */
+declare class McpToolRegistry {
+    /** Nested Map: source -> toolName -> McpToolRegistryEntry */
+    private tools;
+    /**
+     * Set all tools for a given source (replaces previous tools from that source).
+     * Called on initial tool listing and on re-listing after restart/refresh.
+     *
+     * @param source - Identifier for the tool source (e.g. server ID or "local")
+     * @param transport - How the tools are reached ("stdio", "http", or "local")
+     * @param tools - Tool definitions to register for this source
+     */
+    setToolsForSource(source: string, transport: "stdio" | "http" | "local", tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+    }>): void;
+    /**
+     * Remove all tools for a source (when a client is permanently stopped).
+     *
+     * @param source - Source identifier whose tools should be removed
+     */
+    removeSource(source: string): void;
+    /**
+     * Get all tools across all sources.
+     *
+     * @returns Array of every registered tool entry
+     */
+    getTools(): McpToolRegistryEntry[];
+    /**
+     * Get tools from a specific source/server.
+     *
+     * @param serverId - Source identifier to filter by
+     * @returns Array of tool entries belonging to that source
+     */
+    getToolsByServer(serverId: string): McpToolRegistryEntry[];
+    /**
+     * Get a specific tool by name. Returns first match if name exists in multiple sources.
+     *
+     * @param name - Tool name to search for
+     * @returns The first matching entry, or undefined
+     */
+    getTool(name: string): McpToolRegistryEntry | undefined;
+    /**
+     * Get a specific tool by source and name.
+     *
+     * @param source - Source identifier
+     * @param name - Tool name
+     * @returns The matching entry, or undefined
+     */
+    getToolBySource(source: string, name: string): McpToolRegistryEntry | undefined;
+}
+
+/**
+ * Store key set by mcpPlugin() when applied; routes using .from(mcp(...)) require it.
+ * @internal
+ */
 declare const MCP_PLUGIN_REGISTERED: unique symbol;
-/** Store key for named remote MCP servers (mcpPlugin({ clients })). Used by McpClient to resolve serverId. */
+/**
+ * Store key for named remote MCP servers (mcpPlugin({ clients })). Used by McpClient to resolve serverId.
+ * @internal
+ */
 declare const ADAPTER_MCP_CLIENT_SERVERS: unique symbol;
+/**
+ * Store key for the unified MCP tool registry. Used by agent adapter for tool discovery.
+ * @internal
+ */
+declare const MCP_TOOL_REGISTRY: unique symbol;
+/**
+ * Store key for stdio client managers. Used by destination adapter to call tools on stdio clients.
+ * @internal
+ */
+declare const MCP_STDIO_MANAGERS: unique symbol;
 declare module "@routecraft/routecraft" {
     interface StoreRegistry {
         [MCP_PLUGIN_REGISTERED]: boolean;
-        [ADAPTER_MCP_CLIENT_SERVERS]: Map<string, McpClientHttpConfig$1 | string>;
+        [ADAPTER_MCP_CLIENT_SERVERS]: Map<string, McpClientHttpConfig$1 | McpClientStdioConfig | string>;
+        [MCP_TOOL_REGISTRY]: McpToolRegistry;
+        [MCP_STDIO_MANAGERS]: Map<string, {
+            callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+        }>;
     }
 }
 /**
@@ -215,15 +385,22 @@ interface McpClientHttpConfig$1 {
     url: string;
 }
 /**
- * Stdio client config for a remote MCP server (subprocess).
- * Not yet accepted in plugin options; for future use.
+ * Stdio client config for a local MCP server subprocess.
+ * Used in mcpPlugin({ clients: { name: config } }).
+ * The plugin spawns the process, manages its lifecycle, and auto-restarts on crash.
  */
 interface McpClientStdioConfig {
     transport: "stdio";
+    /** The executable to run (e.g. "npx", "node", "python"). */
     command: string;
+    /** Command line arguments to pass to the executable. */
     args?: string[];
+    /** Environment variables for the child process. Defaults to a safe subset of the parent env. */
+    env?: Record<string, string>;
+    /** Working directory for the child process. Defaults to the current working directory. */
+    cwd?: string;
 }
-/** Union of client configs. Plugin options use McpClientHttpConfig only for now. */
+/** Union of client configs accepted by mcpPlugin({ clients }). */
 type McpClientServerConfig = McpClientHttpConfig$1 | McpClientStdioConfig;
 /**
  * Options for the MCP plugin (mcpPlugin).
@@ -246,10 +423,32 @@ interface McpPluginOptions {
      */
     tools?: string[] | ((meta: DirectRouteMetadata) => boolean);
     /**
-     * Named remote MCP servers for .to(mcp("name:tool")). Keys are server names; values are HTTP config (url).
-     * Stdio config not yet supported in plugin options.
+     * Named remote MCP servers for .to(mcp("name:tool")).
+     * Keys are server names; values are HTTP or stdio config.
+     * Stdio clients are managed as subprocesses with auto-restart.
+     * HTTP clients are used for ephemeral tool calls.
      */
-    clients?: Record<string, McpClientHttpConfig$1>;
+    clients?: Record<string, McpClientHttpConfig$1 | McpClientStdioConfig>;
+    /**
+     * Max auto-restart attempts for stdio clients before giving up.
+     * Applies to all stdio clients. Default: 5.
+     */
+    maxRestarts?: number;
+    /**
+     * Base delay in ms before the first restart attempt.
+     * Subsequent attempts use exponential backoff. Default: 1000.
+     */
+    restartDelayMs?: number;
+    /**
+     * Multiplier for exponential backoff between restart attempts.
+     * Delay = restartDelayMs * (restartBackoffMultiplier ^ restartCount). Default: 2.
+     */
+    restartBackoffMultiplier?: number;
+    /**
+     * Interval in ms to re-list tools from HTTP clients.
+     * Set to 0 to disable periodic refresh. Default: 60000 (60s).
+     */
+    toolRefreshIntervalMs?: number;
 }
 /**
  * Options for mcp() when used as a server in .from().
@@ -268,9 +467,11 @@ type McpArgsExtractor$1 = (exchange: Exchange<unknown>) => Record<string, unknow
  * Options for mcp() when used as a Client in .to() to call a remote MCP server.
  * Provide either url (inline HTTP) or serverId (from plugin/store); tool is required.
  *
- * **Stdio is not supported in routes.** Only HTTP is allowed: use `url` for an inline
- * HTTP endpoint or `serverId` for a named backend from mcpPlugin({ clients }) or
- * context store. Stdio MCP clients are managed by the plugin lifecycle only.
+ * Supported transports:
+ * - **HTTP:** use `url` for an inline endpoint or `serverId` for a named backend.
+ * - **Stdio:** use `serverId` referencing a stdio client from mcpPlugin({ clients }).
+ *   The destination adapter resolves the manager from the context store and calls
+ *   tools directly on the subprocess -- no HTTP involved.
  */
 interface McpClientOptions {
     /** URL of the remote MCP server (HTTP/HTTPS only). Omit when using serverId. */
@@ -281,7 +482,7 @@ interface McpClientOptions {
     serverId?: string;
     /**
      * Extract tool arguments from the exchange. Receives the full exchange.
-     * Default: body as object → use as args; otherwise { input: body }.
+     * Default: body as object -> use as args; otherwise { input: body }.
      */
     args?: McpArgsExtractor$1;
 }
@@ -298,6 +499,22 @@ interface McpTool {
         [key: string]: unknown;
     };
 }
+/**
+ * A tool entry in the unified MCP tool registry.
+ * Combines local mcp() route tools and remote client tools (stdio and HTTP).
+ */
+interface McpToolRegistryEntry {
+    /** Tool name (unique within a source, may collide across sources). */
+    name: string;
+    /** Human-readable description of the tool. */
+    description?: string;
+    /** JSON Schema for tool input. */
+    inputSchema: Record<string, unknown>;
+    /** Source server ID. Local mcp() routes use "local". */
+    source: string;
+    /** Transport type of the source. */
+    transport: "stdio" | "http" | "local";
+}
 /**
  * MCP tool call result
  */
@@ -329,6 +546,7 @@ interface McpClientHttpConfig {
 /**
  * Brand symbol for MCP adapter type checking.
  * Used internally to identify MCP adapters.
+ * @experimental
  */
 declare const BRAND_MCP_ADAPTER: unique symbol;
 
@@ -358,6 +576,8 @@ declare const defaultArgs: McpArgsExtractor$1;
  * @param options - Server options (source) or args extractor (destination)
  * @returns Source when called with two arguments; Destination when called with one argument
  *
+ * @experimental
+ *
  * @example
  * ```typescript
  * // Source route (MCP tool)
@@ -374,23 +594,29 @@ declare function mcp<S extends StandardSchemaV1 | undefined = undefined>(endpoin
     schema?: S;
 }): Source<McpMessage<S>>;
 declare function mcp(clientOptions: McpClientOptions): Destination<unknown, unknown>;
-declare function mcp(shorthand: `${string}:${string}`, options?: {
+declare function mcp(shorthand: RegisteredMcpShorthand, options?: {
     args?: McpArgsExtractor$1;
 }): Destination<unknown, unknown>;
 
 /**
  * MCP plugin: one plugin per adapter. Starts the MCP server during plugin apply (before routes start) so startup failures fail context build. Exposes mcp() routes to external MCP clients.
  * Optional clients: register named remote MCP servers so routes can use .to(mcp("name:tool")) without passing url.
+ * Stdio clients are spawned as subprocesses with auto-restart; HTTP clients are used for ephemeral tool calls.
+ * All discovered external tools (stdio, HTTP) are stored in a unified McpToolRegistry for agent adapter discovery.
  * Required when any route uses .from(mcp(...)); the route will fail at start if this plugin is not applied.
+ *
+ * @experimental
  */
 declare function mcpPlugin(options?: McpPluginOptions): CraftPlugin;
 
 /**
- * McpServer wraps the MCP SDK and bridges it to RouteCraft's DirectChannel infrastructure.
+ * McpServer wraps the MCP SDK and bridges it to Routecraft's DirectChannel infrastructure.
  * It reads the MCP route registry lazily (on first tools/list request) to ensure routes have subscribed.
  *
  * Note: Uses dynamic imports to avoid TypeScript compatibility issues with the MCP SDK.
  * Supports both stdio and streamable-http transports.
+ *
+ * @experimental
  */
 declare class McpServer {
     private context;
@@ -439,7 +665,7 @@ declare class McpServer {
      */
     getAvailableTools(): Array<Record<string, unknown>>;
     /**
-     * Convert RouteCraft mcp() route metadata to MCP tool format
+     * Convert Routecraft mcp() route metadata to MCP tool format
      */
     private metadataToMcpTool;
     /**
@@ -503,6 +729,7 @@ interface AgentResult {
 /**
  * Create an agent destination.
  *
+ * @experimental
  * @param options Agent options (modelId, systemPrompt, allowedRoutes, etc.)
  * @returns Destination that produces AgentResult
  */
@@ -511,6 +738,8 @@ declare function agent(options: AgentOptions): Destination<unknown, AgentResult>
 /**
  * Agent destination adapter.
  * Use via agent(); do not instantiate AgentRunner directly.
+ *
+ * @experimental
  */
 declare class AgentDestinationAdapter implements Destination<unknown, AgentResult> {
     readonly adapterId = "routecraft.adapter.agent";
@@ -583,6 +812,8 @@ type EmbeddingModelId = "huggingface:all-MiniLM-L6-v2" | "huggingface:sentence-t
  * Embedding destination adapter. Expects model id as "providerId:modelName"
  * (e.g. huggingface:all-MiniLM-L6-v2), resolves the provider from the plugin store,
  * and returns { embedding: number[] }. Use with .enrich(embedding("provider:model", { using: ... })).
+ *
+ * @experimental
  */
 declare class EmbeddingDestinationAdapter<T = unknown> implements Destination<T, EmbeddingResult>, MergedOptions<EmbeddingOptions> {
     private readonly modelId;
@@ -598,6 +829,7 @@ declare class EmbeddingDestinationAdapter<T = unknown> implements Destination<T,
  * Use with .enrich(). Pass model id as "providerId:modelName" (e.g. huggingface:all-MiniLM-L6-v2).
  * The provider must be registered via embeddingPlugin({ providers: { huggingface: {} } }).
  *
+ * @experimental
  * @param modelId - "providerId:modelName"; the provider is resolved from the plugin.
  * @param options - using(exchange) returns the string (or string[]) to embed.
  */
@@ -608,6 +840,8 @@ declare function embedding<T = unknown>(modelId: EmbeddingModelId, options?: Par
  * cache when the context stops (releases native/ONNX resources).
  * Use embedding("providerId:modelName", { using: ... }),
  * e.g. embedding("huggingface:all-MiniLM-L6-v2", { using: (e) => e.body.title }).
+ *
+ * @experimental
  */
 declare function embeddingPlugin(options?: EmbeddingPluginOptions): CraftPlugin;
 
@@ -615,10 +849,12 @@ declare function embeddingPlugin(options?: EmbeddingPluginOptions): CraftPlugin;
  * Dispose all cached HuggingFace pipelines and clear the cache. Call on context
  * shutdown so pipeline.dispose() releases native/ONNX resources.
  *
- * Callers must avoid process.exit() after this — let the event loop drain
+ * Callers must avoid process.exit() after this -- let the event loop drain
  * naturally so ONNX Runtime's C++ statics aren't torn down prematurely
  * (onnxruntime#25038: "mutex lock failed: Invalid argument").
+ *
+ * @experimental
  */
 declare function disposeEmbeddingPipelineCache(): Promise<void>;
 
-export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, type McpArgsExtractor, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpMessage, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpTool, type McpToolResult, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, llm, llmPlugin, mcp, mcpPlugin, validateLlmPluginOptions, validateWithSchema };
+export { ADAPTER_LLM_OPTIONS, ADAPTER_LLM_PROVIDERS, ADAPTER_MCP_CLIENT_SERVERS, AgentDestinationAdapter, type AgentModelId, type AgentOptions, type AgentPromptSource, type AgentResult, BRAND, BRAND_MCP_ADAPTER, EmbeddingDestinationAdapter, type EmbeddingModelConfig, type EmbeddingModelConfigHuggingFace, type EmbeddingModelConfigOllama, type EmbeddingModelConfigOpenAI, type EmbeddingModelId, type EmbeddingOptions, type EmbeddingPluginOptions, type EmbeddingPluginProviders, type EmbeddingProviderType, type EmbeddingResult, type LlmAnthropicProviderOptions, LlmDestinationAdapter, type LlmGeminiProviderOptions, type LlmModelConfig, type LlmModelConfigAnthropic, type LlmModelConfigGemini, type LlmModelConfigOllama, type LlmModelConfigOpenAI, type LlmModelConfigOpenRouter, type LlmModelId, type LlmOllamaProviderOptions, type LlmOpenAIProviderOptions, type LlmOpenRouterProviderOptions, type LlmOptions, type LlmPluginOptions, type LlmPluginProviders, type LlmPromptSource, type LlmProviderRegistry, type LlmProviderType, type LlmResult, type LlmUsage, MCP_PLUGIN_REGISTERED, MCP_STDIO_MANAGERS, MCP_TOOL_REGISTRY, type McpArgsExtractor, type McpClientHttpConfig, type McpClientOptions, type McpClientServerConfig, type McpClientStdioConfig, type McpMessage, type McpOptions, type McpPluginOptions, McpServer, type McpServerOptions, type McpServerRegistry, type McpTool, McpToolRegistry, type McpToolRegistryEntry, type McpToolResult, type RegisteredLlmModelId, type RegisteredMcpServer, type RegisteredMcpShorthand, agent, defaultArgs, disposeEmbeddingPipelineCache, embedding, embeddingPlugin, isMcpAdapter, llm, llmPlugin, mcp, mcpPlugin, validateLlmPluginOptions, validateWithSchema };