apex-code 0.0.1-alpha.9 → 0.0.5

package/dist/core/mcp/oauth/token-client.d.ts

@@ -0,0 +1,33 @@
+import { type FetchLike } from "./discover.ts";
+export declare class TokenEndpointError extends Error {
+    /** The OAuth `error` code from the response body, when the server sent one (e.g. invalid_grant). */
+    code: string | undefined;
+    constructor(message: string, code: string | undefined);
+}
+/** The endpoint could not be reached at all — a path problem, not a server refusal. */
+export declare class TokenEndpointUnreachableError extends TokenEndpointError {
+}
+export interface TokenResponse {
+    accessToken: string;
+    /** Absent when the server did not rotate; callers keep their previous refresh token then. */
+    refreshToken: string | undefined;
+    expiresInSeconds: number;
+}
+interface TokenEndpointOptions {
+    tokenEndpoint: URL;
+    clientId: string;
+    clientSecret?: string;
+    /** The MCP resource indicator; pins the issued token to this server (RFC 8707). */
+    resource?: string;
+    fetch?: FetchLike;
+}
+export declare function exchangeAuthorizationCode(options: TokenEndpointOptions & {
+    code: string;
+    verifier: string;
+    redirectUri: string;
+}): Promise<TokenResponse>;
+export declare function refreshAccessToken(options: TokenEndpointOptions & {
+    refreshToken: string;
+}): Promise<TokenResponse>;
+export {};
+//# sourceMappingURL=token-client.d.ts.map

package/dist/core/mcp/oauth/token-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-client.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/token-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,eAAe,CAAC;AAElE,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,oGAAoG;IACpG,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzB,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAGpD;CACD;AAED,yFAAuF;AACvF,qBAAa,6BAA8B,SAAQ,kBAAkB;CAAG;AAExE,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,oBAAoB;IAC7B,aAAa,EAAE,GAAG,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;CAClB;AA4CD,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,oBAAoB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACrF,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAEnH","sourcesContent":["import { type FetchLike, oauthErrorMessage } from \"./discover.ts\";\n\nexport class TokenEndpointError extends Error {\n\t/** The OAuth `error` code from the response body, when the server sent one (e.g. invalid_grant). */\n\tcode: string | undefined;\n\n\tconstructor(message: string, code: string | undefined) {\n\t\tsuper(message);\n\t\tthis.code = code;\n\t}\n}\n\n/** The endpoint could not be reached at all — a path problem, not a server refusal. */\nexport class TokenEndpointUnreachableError extends TokenEndpointError {}\n\nexport interface TokenResponse {\n\taccessToken: string;\n\t/** Absent when the server did not rotate; callers keep their previous refresh token then. */\n\trefreshToken: string | undefined;\n\texpiresInSeconds: number;\n}\n\ninterface TokenEndpointOptions {\n\ttokenEndpoint: URL;\n\tclientId: string;\n\tclientSecret?: string;\n\t/** The MCP resource indicator; pins the issued token to this server (RFC 8707). */\n\tresource?: string;\n\tfetch?: FetchLike;\n}\n\nasync function postTokenForm(options: TokenEndpointOptions, grant: Record<string, string>): Promise<TokenResponse> {\n\tconst fetch = options.fetch ?? globalThis.fetch;\n\tconst body = new URLSearchParams({ client_id: options.clientId, ...grant });\n\tif (options.clientSecret) body.set(\"client_secret\", options.clientSecret);\n\tif (options.resource) body.set(\"resource\", options.resource);\n\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetch(options.tokenEndpoint, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"content-type\": \"application/x-www-form-urlencoded\" },\n\t\t\tbody,\n\t\t});\n\t} catch (error) {\n\t\tthrow new TokenEndpointUnreachableError(\n\t\t\t`token endpoint unreachable at ${options.tokenEndpoint}: ${oauthErrorMessage(error)}`,\n\t\t\tundefined,\n\t\t);\n\t}\n\n\tconst text = await response.text();\n\tlet parsed: Record<string, unknown> = {};\n\ttry {\n\t\tconst value: unknown = JSON.parse(text);\n\t\tif (typeof value === \"object\" && value !== null) parsed = value as Record<string, unknown>;\n\t} catch {\n\t\t// A non-JSON error body still lands in the status branch below.\n\t}\n\tif (!response.ok) {\n\t\tconst code = typeof parsed.error === \"string\" ? parsed.error : undefined;\n\t\tthrow new TokenEndpointError(`token endpoint answered HTTP ${response.status}${code ? ` (${code})` : \"\"}`, code);\n\t}\n\tif (typeof parsed.access_token !== \"string\" || typeof parsed.expires_in !== \"number\") {\n\t\tthrow new TokenEndpointError(\"token endpoint response is missing access_token or expires_in\", undefined);\n\t}\n\treturn {\n\t\taccessToken: parsed.access_token,\n\t\trefreshToken: typeof parsed.refresh_token === \"string\" ? parsed.refresh_token : undefined,\n\t\texpiresInSeconds: parsed.expires_in,\n\t};\n}\n\nexport function exchangeAuthorizationCode(\n\toptions: TokenEndpointOptions & { code: string; verifier: string; redirectUri: string },\n): Promise<TokenResponse> {\n\treturn postTokenForm(options, {\n\t\tgrant_type: \"authorization_code\",\n\t\tcode: options.code,\n\t\tcode_verifier: options.verifier,\n\t\tredirect_uri: options.redirectUri,\n\t});\n}\n\nexport function refreshAccessToken(options: TokenEndpointOptions & { refreshToken: string }): Promise<TokenResponse> {\n\treturn postTokenForm(options, { grant_type: \"refresh_token\", refresh_token: options.refreshToken });\n}\n"]}

package/dist/core/mcp/oauth/token-client.js

@@ -0,0 +1,65 @@
+import { oauthErrorMessage } from "./discover.js";
+export class TokenEndpointError extends Error {
+    /** The OAuth `error` code from the response body, when the server sent one (e.g. invalid_grant). */
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** The endpoint could not be reached at all — a path problem, not a server refusal. */
+export class TokenEndpointUnreachableError extends TokenEndpointError {
+}
+async function postTokenForm(options, grant) {
+    const fetch = options.fetch ?? globalThis.fetch;
+    const body = new URLSearchParams({ client_id: options.clientId, ...grant });
+    if (options.clientSecret)
+        body.set("client_secret", options.clientSecret);
+    if (options.resource)
+        body.set("resource", options.resource);
+    let response;
+    try {
+        response = await fetch(options.tokenEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body,
+        });
+    }
+    catch (error) {
+        throw new TokenEndpointUnreachableError(`token endpoint unreachable at ${options.tokenEndpoint}: ${oauthErrorMessage(error)}`, undefined);
+    }
+    const text = await response.text();
+    let parsed = {};
+    try {
+        const value = JSON.parse(text);
+        if (typeof value === "object" && value !== null)
+            parsed = value;
+    }
+    catch {
+        // A non-JSON error body still lands in the status branch below.
+    }
+    if (!response.ok) {
+        const code = typeof parsed.error === "string" ? parsed.error : undefined;
+        throw new TokenEndpointError(`token endpoint answered HTTP ${response.status}${code ? ` (${code})` : ""}`, code);
+    }
+    if (typeof parsed.access_token !== "string" || typeof parsed.expires_in !== "number") {
+        throw new TokenEndpointError("token endpoint response is missing access_token or expires_in", undefined);
+    }
+    return {
+        accessToken: parsed.access_token,
+        refreshToken: typeof parsed.refresh_token === "string" ? parsed.refresh_token : undefined,
+        expiresInSeconds: parsed.expires_in,
+    };
+}
+export function exchangeAuthorizationCode(options) {
+    return postTokenForm(options, {
+        grant_type: "authorization_code",
+        code: options.code,
+        code_verifier: options.verifier,
+        redirect_uri: options.redirectUri,
+    });
+}
+export function refreshAccessToken(options) {
+    return postTokenForm(options, { grant_type: "refresh_token", refresh_token: options.refreshToken });
+}
+//# sourceMappingURL=token-client.js.map

package/dist/core/mcp/oauth/token-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-client.js","sourceRoot":"","sources":["../../../../src/core/mcp/oauth/token-client.ts"],"names":[],"mappings":"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","sourcesContent":["import { type FetchLike, oauthErrorMessage } from \"./discover.ts\";\n\nexport class TokenEndpointError extends Error {\n\t/** The OAuth `error` code from the response body, when the server sent one (e.g. invalid_grant). */\n\tcode: string | undefined;\n\n\tconstructor(message: string, code: string | undefined) {\n\t\tsuper(message);\n\t\tthis.code = code;\n\t}\n}\n\n/** The endpoint could not be reached at all — a path problem, not a server refusal. */\nexport class TokenEndpointUnreachableError extends TokenEndpointError {}\n\nexport interface TokenResponse {\n\taccessToken: string;\n\t/** Absent when the server did not rotate; callers keep their previous refresh token then. */\n\trefreshToken: string | undefined;\n\texpiresInSeconds: number;\n}\n\ninterface TokenEndpointOptions {\n\ttokenEndpoint: URL;\n\tclientId: string;\n\tclientSecret?: string;\n\t/** The MCP resource indicator; pins the issued token to this server (RFC 8707). */\n\tresource?: string;\n\tfetch?: FetchLike;\n}\n\nasync function postTokenForm(options: TokenEndpointOptions, grant: Record<string, string>): Promise<TokenResponse> {\n\tconst fetch = options.fetch ?? globalThis.fetch;\n\tconst body = new URLSearchParams({ client_id: options.clientId, ...grant });\n\tif (options.clientSecret) body.set(\"client_secret\", options.clientSecret);\n\tif (options.resource) body.set(\"resource\", options.resource);\n\n\tlet response: Response;\n\ttry {\n\t\tresponse = await fetch(options.tokenEndpoint, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"content-type\": \"application/x-www-form-urlencoded\" },\n\t\t\tbody,\n\t\t});\n\t} catch (error) {\n\t\tthrow new TokenEndpointUnreachableError(\n\t\t\t`token endpoint unreachable at ${options.tokenEndpoint}: ${oauthErrorMessage(error)}`,\n\t\t\tundefined,\n\t\t);\n\t}\n\n\tconst text = await response.text();\n\tlet parsed: Record<string, unknown> = {};\n\ttry {\n\t\tconst value: unknown = JSON.parse(text);\n\t\tif (typeof value === \"object\" && value !== null) parsed = value as Record<string, unknown>;\n\t} catch {\n\t\t// A non-JSON error body still lands in the status branch below.\n\t}\n\tif (!response.ok) {\n\t\tconst code = typeof parsed.error === \"string\" ? parsed.error : undefined;\n\t\tthrow new TokenEndpointError(`token endpoint answered HTTP ${response.status}${code ? ` (${code})` : \"\"}`, code);\n\t}\n\tif (typeof parsed.access_token !== \"string\" || typeof parsed.expires_in !== \"number\") {\n\t\tthrow new TokenEndpointError(\"token endpoint response is missing access_token or expires_in\", undefined);\n\t}\n\treturn {\n\t\taccessToken: parsed.access_token,\n\t\trefreshToken: typeof parsed.refresh_token === \"string\" ? parsed.refresh_token : undefined,\n\t\texpiresInSeconds: parsed.expires_in,\n\t};\n}\n\nexport function exchangeAuthorizationCode(\n\toptions: TokenEndpointOptions & { code: string; verifier: string; redirectUri: string },\n): Promise<TokenResponse> {\n\treturn postTokenForm(options, {\n\t\tgrant_type: \"authorization_code\",\n\t\tcode: options.code,\n\t\tcode_verifier: options.verifier,\n\t\tredirect_uri: options.redirectUri,\n\t});\n}\n\nexport function refreshAccessToken(options: TokenEndpointOptions & { refreshToken: string }): Promise<TokenResponse> {\n\treturn postTokenForm(options, { grant_type: \"refresh_token\", refresh_token: options.refreshToken });\n}\n"]}

package/dist/core/mcp/runtime.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Assembles the MCP subsystem for one session, or returns undefined when nothing is
+ * configured.
+ *
+ * The undefined case is the point. A session with no `.mcp.json` builds no cache, no
+ * manager, and no tool, so its registry and static prompt prefix are identical to a
+ * build from before this subsystem existed.
+ */
+import type { McpToolOptions } from "./mcp-tool.ts";
+import type { McpConfigDiagnostic, McpConnector } from "./types.ts";
+export interface McpRuntime extends McpToolOptions {
+    diagnostics: readonly McpConfigDiagnostic[];
+    /** Connect `eager` servers and cache their tools, so they are discoverable cold. */
+    warm(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createMcpRuntime(cwd: string, connector?: McpConnector, options?: {
+    projectTrusted?: boolean;
+}): McpRuntime | undefined;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/core/mcp/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,UAAW,SAAQ,cAAc;IACjD,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C,oFAAoF;IACpF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,YAA+B,EAC1C,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,UAAU,GAAG,SAAS,CAwBxB","sourcesContent":["/**\n * Assembles the MCP subsystem for one session, or returns undefined when nothing is\n * configured.\n *\n * The undefined case is the point. A session with no `.mcp.json` builds no cache, no\n * manager, and no tool, so its registry and static prompt prefix are identical to a\n * build from before this subsystem existed.\n */\n\nimport { join } from \"node:path\";\nimport { loadMcpConfig, PROJECT_CONFIG_FILENAME } from \"./config.ts\";\nimport { connectMcpServer } from \"./connector.ts\";\nimport type { McpToolOptions } from \"./mcp-tool.ts\";\nimport { McpMetadataCache } from \"./metadata-cache.ts\";\nimport { McpServerManager } from \"./server-manager.ts\";\nimport type { McpConfigDiagnostic, McpConnector } from \"./types.ts\";\n\nexport interface McpRuntime extends McpToolOptions {\n\tdiagnostics: readonly McpConfigDiagnostic[];\n\t/** Connect `eager` servers and cache their tools, so they are discoverable cold. */\n\twarm(): Promise<void>;\n\tclose(): Promise<void>;\n}\n\nexport function createMcpRuntime(\n\tcwd: string,\n\tconnector: McpConnector = connectMcpServer,\n\toptions: { projectTrusted?: boolean } = {},\n): McpRuntime | undefined {\n\tconst { servers, diagnostics } = loadMcpConfig({\n\t\tprojectPath: options.projectTrusted === false ? undefined : join(cwd, PROJECT_CONFIG_FILENAME),\n\t});\n\tif (servers.size === 0) return undefined;\n\n\tconst cache = new McpMetadataCache();\n\t// A server removed from config stops appearing in search immediately, rather than\n\t// lingering until something happens to overwrite its cache entry.\n\tcache.prune([...servers.values()]);\n\n\tconst manager = new McpServerManager({ servers, connector });\n\n\treturn {\n\t\tservers,\n\t\tcache,\n\t\tmanager,\n\t\tdiagnostics,\n\t\twarm: async () => {\n\t\t\tawait manager.warmEagerServers((server, tools) => cache.set(server, tools));\n\t\t\tcache.save();\n\t\t},\n\t\tclose: () => manager.closeAll(),\n\t};\n}\n"]}

package/dist/core/mcp/runtime.js

@@ -0,0 +1,37 @@
+/**
+ * Assembles the MCP subsystem for one session, or returns undefined when nothing is
+ * configured.
+ *
+ * The undefined case is the point. A session with no `.mcp.json` builds no cache, no
+ * manager, and no tool, so its registry and static prompt prefix are identical to a
+ * build from before this subsystem existed.
+ */
+import { join } from "node:path";
+import { loadMcpConfig, PROJECT_CONFIG_FILENAME } from "./config.js";
+import { connectMcpServer } from "./connector.js";
+import { McpMetadataCache } from "./metadata-cache.js";
+import { McpServerManager } from "./server-manager.js";
+export function createMcpRuntime(cwd, connector = connectMcpServer, options = {}) {
+    const { servers, diagnostics } = loadMcpConfig({
+        projectPath: options.projectTrusted === false ? undefined : join(cwd, PROJECT_CONFIG_FILENAME),
+    });
+    if (servers.size === 0)
+        return undefined;
+    const cache = new McpMetadataCache();
+    // A server removed from config stops appearing in search immediately, rather than
+    // lingering until something happens to overwrite its cache entry.
+    cache.prune([...servers.values()]);
+    const manager = new McpServerManager({ servers, connector });
+    return {
+        servers,
+        cache,
+        manager,
+        diagnostics,
+        warm: async () => {
+            await manager.warmEagerServers((server, tools) => cache.set(server, tools));
+            cache.save();
+        },
+        close: () => manager.closeAll(),
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/core/mcp/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/core/mcp/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAUvD,MAAM,UAAU,gBAAgB,CAC/B,GAAW,EACX,SAAS,GAAiB,gBAAgB,EAC1C,OAAO,GAAiC,EAAE,EACjB;IACzB,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,aAAa,CAAC;QAC9C,WAAW,EAAE,OAAO,CAAC,cAAc,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,uBAAuB,CAAC;KAC9F,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,MAAM,KAAK,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACrC,kFAAkF;IAClF,kEAAkE;IAClE,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAEnC,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IAE7D,OAAO;QACN,OAAO;QACP,KAAK;QACL,OAAO;QACP,WAAW;QACX,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;YAC5E,KAAK,CAAC,IAAI,EAAE,CAAC;QAAA,CACb;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE;KAC/B,CAAC;AAAA,CACF","sourcesContent":["/**\n * Assembles the MCP subsystem for one session, or returns undefined when nothing is\n * configured.\n *\n * The undefined case is the point. A session with no `.mcp.json` builds no cache, no\n * manager, and no tool, so its registry and static prompt prefix are identical to a\n * build from before this subsystem existed.\n */\n\nimport { join } from \"node:path\";\nimport { loadMcpConfig, PROJECT_CONFIG_FILENAME } from \"./config.ts\";\nimport { connectMcpServer } from \"./connector.ts\";\nimport type { McpToolOptions } from \"./mcp-tool.ts\";\nimport { McpMetadataCache } from \"./metadata-cache.ts\";\nimport { McpServerManager } from \"./server-manager.ts\";\nimport type { McpConfigDiagnostic, McpConnector } from \"./types.ts\";\n\nexport interface McpRuntime extends McpToolOptions {\n\tdiagnostics: readonly McpConfigDiagnostic[];\n\t/** Connect `eager` servers and cache their tools, so they are discoverable cold. */\n\twarm(): Promise<void>;\n\tclose(): Promise<void>;\n}\n\nexport function createMcpRuntime(\n\tcwd: string,\n\tconnector: McpConnector = connectMcpServer,\n\toptions: { projectTrusted?: boolean } = {},\n): McpRuntime | undefined {\n\tconst { servers, diagnostics } = loadMcpConfig({\n\t\tprojectPath: options.projectTrusted === false ? undefined : join(cwd, PROJECT_CONFIG_FILENAME),\n\t});\n\tif (servers.size === 0) return undefined;\n\n\tconst cache = new McpMetadataCache();\n\t// A server removed from config stops appearing in search immediately, rather than\n\t// lingering until something happens to overwrite its cache entry.\n\tcache.prune([...servers.values()]);\n\n\tconst manager = new McpServerManager({ servers, connector });\n\n\treturn {\n\t\tservers,\n\t\tcache,\n\t\tmanager,\n\t\tdiagnostics,\n\t\twarm: async () => {\n\t\t\tawait manager.warmEagerServers((server, tools) => cache.set(server, tools));\n\t\t\tcache.save();\n\t\t},\n\t\tclose: () => manager.closeAll(),\n\t};\n}\n"]}

package/dist/core/mcp/schema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `mcp` tool's parameter schema, and the single source of its param type.
+ *
+ * It lives apart from the tool itself so the contract (`contract.ts`) can type its
+ * permission grammar against the same shape without importing the tool, which would
+ * be a cycle: the tool needs the contract.
+ */
+import { type Static, Type } from "typebox";
+export declare const mcpToolSchema: Type.TObject<{
+    search: Type.TOptional<Type.TString>;
+    server: Type.TOptional<Type.TString>;
+    describe: Type.TOptional<Type.TString>;
+    tool: Type.TOptional<Type.TString>;
+    args: Type.TOptional<Type.TUnknown>;
+}>;
+export type McpToolParams = Static<typeof mcpToolSchema>;
+export interface McpToolDetails {
+    action: "search" | "describe" | "list" | "call";
+    server: string | undefined;
+    tool: string | undefined;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/mcp/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,eAAO,MAAM,aAAa;;;;;;EAmBxB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IAChD,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB","sourcesContent":["/**\n * The `mcp` tool's parameter schema, and the single source of its param type.\n *\n * It lives apart from the tool itself so the contract (`contract.ts`) can type its\n * permission grammar against the same shape without importing the tool, which would\n * be a cycle: the tool needs the contract.\n */\n\nimport { type Static, Type } from \"typebox\";\n\nexport const mcpToolSchema = Type.Object({\n\tsearch: Type.Optional(\n\t\tType.String({\n\t\t\tdescription:\n\t\t\t\t\"Find tools across configured MCP servers by keyword. Reads a local cache, so it works without starting a server.\",\n\t\t}),\n\t),\n\tserver: Type.Optional(\n\t\tType.String({ description: \"Restrict a search to one server, or list that server's tools when used alone.\" }),\n\t),\n\tdescribe: Type.Optional(\n\t\tType.String({ description: 'Show one tool\\'s full input schema. Qualified as \"<server>:<tool>\".' }),\n\t),\n\ttool: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: 'The tool to call, qualified as \"<server>:<tool>\". Requires the server to be reachable.',\n\t\t}),\n\t),\n\targs: Type.Optional(Type.Unknown({ description: \"Arguments for the called tool, matching its input schema.\" })),\n});\n\nexport type McpToolParams = Static<typeof mcpToolSchema>;\n\nexport interface McpToolDetails {\n\taction: \"search\" | \"describe\" | \"list\" | \"call\";\n\tserver: string | undefined;\n\ttool: string | undefined;\n}\n"]}

package/dist/core/mcp/schema.js

@@ -0,0 +1,20 @@
+/**
+ * The `mcp` tool's parameter schema, and the single source of its param type.
+ *
+ * It lives apart from the tool itself so the contract (`contract.ts`) can type its
+ * permission grammar against the same shape without importing the tool, which would
+ * be a cycle: the tool needs the contract.
+ */
+import { Type } from "typebox";
+export const mcpToolSchema = Type.Object({
+    search: Type.Optional(Type.String({
+        description: "Find tools across configured MCP servers by keyword. Reads a local cache, so it works without starting a server.",
+    })),
+    server: Type.Optional(Type.String({ description: "Restrict a search to one server, or list that server's tools when used alone." })),
+    describe: Type.Optional(Type.String({ description: 'Show one tool\'s full input schema. Qualified as "<server>:<tool>".' })),
+    tool: Type.Optional(Type.String({
+        description: 'The tool to call, qualified as "<server>:<tool>". Requires the server to be reachable.',
+    })),
+    args: Type.Optional(Type.Unknown({ description: "Arguments for the called tool, matching its input schema." })),
+});
+//# sourceMappingURL=schema.js.map

package/dist/core/mcp/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/core/mcp/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,IAAI,CAAC,QAAQ,CACpB,IAAI,CAAC,MAAM,CAAC;QACX,WAAW,EACV,kHAAkH;KACnH,CAAC,CACF;IACD,MAAM,EAAE,IAAI,CAAC,QAAQ,CACpB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,+EAA+E,EAAE,CAAC,CAC7G;IACD,QAAQ,EAAE,IAAI,CAAC,QAAQ,CACtB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,qEAAqE,EAAE,CAAC,CACnG;IACD,IAAI,EAAE,IAAI,CAAC,QAAQ,CAClB,IAAI,CAAC,MAAM,CAAC;QACX,WAAW,EAAE,wFAAwF;KACrG,CAAC,CACF;IACD,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,2DAA2D,EAAE,CAAC,CAAC;CAC/G,CAAC,CAAC","sourcesContent":["/**\n * The `mcp` tool's parameter schema, and the single source of its param type.\n *\n * It lives apart from the tool itself so the contract (`contract.ts`) can type its\n * permission grammar against the same shape without importing the tool, which would\n * be a cycle: the tool needs the contract.\n */\n\nimport { type Static, Type } from \"typebox\";\n\nexport const mcpToolSchema = Type.Object({\n\tsearch: Type.Optional(\n\t\tType.String({\n\t\t\tdescription:\n\t\t\t\t\"Find tools across configured MCP servers by keyword. Reads a local cache, so it works without starting a server.\",\n\t\t}),\n\t),\n\tserver: Type.Optional(\n\t\tType.String({ description: \"Restrict a search to one server, or list that server's tools when used alone.\" }),\n\t),\n\tdescribe: Type.Optional(\n\t\tType.String({ description: 'Show one tool\\'s full input schema. Qualified as \"<server>:<tool>\".' }),\n\t),\n\ttool: Type.Optional(\n\t\tType.String({\n\t\t\tdescription: 'The tool to call, qualified as \"<server>:<tool>\". Requires the server to be reachable.',\n\t\t}),\n\t),\n\targs: Type.Optional(Type.Unknown({ description: \"Arguments for the called tool, matching its input schema.\" })),\n});\n\nexport type McpToolParams = Static<typeof mcpToolSchema>;\n\nexport interface McpToolDetails {\n\taction: \"search\" | \"describe\" | \"list\" | \"call\";\n\tserver: string | undefined;\n\ttool: string | undefined;\n}\n"]}

package/dist/core/mcp/server-manager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Owns when a server is running and nothing about how it is reached.
+ *
+ * The `McpConnection` seam is why this module has no MCP SDK import and no child
+ * process: lifecycle is the part with the interesting failure modes (a connect that
+ * never returns, a broken server retried on every call, two callers racing the same
+ * spawn) and all of it is testable against a fake.
+ */
+import type { CachedTool, McpConnection, McpConnector, McpServerConfig, ServerState } from "./types.ts";
+export interface McpServerManagerOptions {
+    servers: ReadonlyMap<string, McpServerConfig>;
+    connector: McpConnector;
+    now?: () => number;
+    connectTimeoutMs?: number;
+}
+export declare class McpServerManager {
+    private readonly servers;
+    private readonly connector;
+    private readonly now;
+    private readonly connectTimeoutMs;
+    private readonly entries;
+    constructor(options: McpServerManagerOptions);
+    state(name: string): ServerState;
+    private entry;
+    private connect;
+    private acquire;
+    withConnection<T>(name: string, use: (connection: McpConnection) => Promise<T>): Promise<T>;
+    /**
+     * Connect every `eager` server and cache what it publishes.
+     *
+     * This is the answer to the cold-cache problem. A lazily configured server has no
+     * cached tools until something calls one, so it cannot be discovered by search; a
+     * user who wants a server discoverable from the first turn declares it `eager`.
+     * Failures are swallowed on purpose, because a broken server must not stop a
+     * session from starting.
+     */
+    warmEagerServers(onTools: (server: McpServerConfig, tools: CachedTool[]) => void): Promise<void>;
+    /** Close every `ready` server whose idle window has passed, unless it is kept alive. */
+    sweepIdle(): Promise<void>;
+    private disconnect;
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=server-manager.d.ts.map

package/dist/core/mcp/server-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-manager.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/server-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAYxG,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC9C,SAAS,EAAE,YAAY,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,YAAY,OAAO,EAAE,uBAAuB,EAK3C;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAE/B;IAED,OAAO,CAAC,KAAK;YASC,OAAO;YAiCP,OAAO;IAkBf,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOhG;IAED;;;;;;;;OAQG;IACG,gBAAgB,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAWrG;IAED,wFAAwF;IAClF,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ/B;YAEa,UAAU;IAUlB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9B;CACD","sourcesContent":["/**\n * Owns when a server is running and nothing about how it is reached.\n *\n * The `McpConnection` seam is why this module has no MCP SDK import and no child\n * process: lifecycle is the part with the interesting failure modes (a connect that\n * never returns, a broken server retried on every call, two callers racing the same\n * spawn) and all of it is testable against a fake.\n */\n\nimport type { CachedTool, McpConnection, McpConnector, McpServerConfig, ServerState } from \"./types.ts\";\n\nconst DEFAULT_CONNECT_TIMEOUT_MS = 30_000;\nconst FAILURE_BACKOFF_MS = 60_000;\n\ninterface Entry {\n\tstate: ServerState;\n\tconnection: McpConnection | undefined;\n\t/** Held so concurrent callers await one spawn instead of racing a second. */\n\tpending: Promise<McpConnection> | undefined;\n}\n\nexport interface McpServerManagerOptions {\n\tservers: ReadonlyMap<string, McpServerConfig>;\n\tconnector: McpConnector;\n\tnow?: () => number;\n\tconnectTimeoutMs?: number;\n}\n\nfunction isKeptAlive(server: McpServerConfig): boolean {\n\treturn server.lifecycle === \"keep-alive\" || server.lifecycle === \"lazy-keep-alive\";\n}\n\nexport class McpServerManager {\n\tprivate readonly servers: ReadonlyMap<string, McpServerConfig>;\n\tprivate readonly connector: McpConnector;\n\tprivate readonly now: () => number;\n\tprivate readonly connectTimeoutMs: number;\n\tprivate readonly entries = new Map<string, Entry>();\n\n\tconstructor(options: McpServerManagerOptions) {\n\t\tthis.servers = options.servers;\n\t\tthis.connector = options.connector;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;\n\t}\n\n\tstate(name: string): ServerState {\n\t\treturn this.entries.get(name)?.state ?? { kind: \"disconnected\" };\n\t}\n\n\tprivate entry(name: string): Entry {\n\t\tlet entry = this.entries.get(name);\n\t\tif (!entry) {\n\t\t\tentry = { state: { kind: \"disconnected\" }, connection: undefined, pending: undefined };\n\t\t\tthis.entries.set(name, entry);\n\t\t}\n\t\treturn entry;\n\t}\n\n\tprivate async connect(server: McpServerConfig, entry: Entry): Promise<McpConnection> {\n\t\tentry.state = { kind: \"connecting\", since: this.now() };\n\n\t\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\t\tconst timeout = new Promise<never>((_, reject) => {\n\t\t\ttimer = setTimeout(\n\t\t\t\t() => reject(new Error(`Connecting to MCP server \"${server.name}\" timed out`)),\n\t\t\t\tthis.connectTimeoutMs,\n\t\t\t);\n\t\t});\n\n\t\ttry {\n\t\t\tconst connection = await Promise.race([this.connector(server), timeout]);\n\t\t\tconst at = this.now();\n\t\t\tentry.connection = connection;\n\t\t\tentry.state = { kind: \"ready\", since: at, lastUsed: at };\n\t\t\treturn connection;\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tentry.connection = undefined;\n\t\t\tentry.state = {\n\t\t\t\tkind: \"failed\",\n\t\t\t\terror: message,\n\t\t\t\tfailedAt: this.now(),\n\t\t\t\tretryAfter: this.now() + FAILURE_BACKOFF_MS,\n\t\t\t};\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tif (timer) clearTimeout(timer);\n\t\t\tentry.pending = undefined;\n\t\t}\n\t}\n\n\tprivate async acquire(name: string): Promise<McpConnection> {\n\t\tconst server = this.servers.get(name);\n\t\tif (!server) throw new Error(`MCP server \"${name}\" is not configured`);\n\n\t\tconst entry = this.entry(name);\n\t\tif (entry.state.kind === \"ready\" && entry.connection) return entry.connection;\n\t\tif (entry.pending) return entry.pending;\n\n\t\t// A server that just failed is not retried until its window passes, so one\n\t\t// broken server cannot cost every call a spawn attempt.\n\t\tif (entry.state.kind === \"failed\" && this.now() < entry.state.retryAfter) {\n\t\t\tthrow new Error(entry.state.error);\n\t\t}\n\n\t\tentry.pending = this.connect(server, entry);\n\t\treturn entry.pending;\n\t}\n\n\tasync withConnection<T>(name: string, use: (connection: McpConnection) => Promise<T>): Promise<T> {\n\t\tconst connection = await this.acquire(name);\n\t\tconst result = await use(connection);\n\n\t\tconst entry = this.entry(name);\n\t\tif (entry.state.kind === \"ready\") entry.state = { ...entry.state, lastUsed: this.now() };\n\t\treturn result;\n\t}\n\n\t/**\n\t * Connect every `eager` server and cache what it publishes.\n\t *\n\t * This is the answer to the cold-cache problem. A lazily configured server has no\n\t * cached tools until something calls one, so it cannot be discovered by search; a\n\t * user who wants a server discoverable from the first turn declares it `eager`.\n\t * Failures are swallowed on purpose, because a broken server must not stop a\n\t * session from starting.\n\t */\n\tasync warmEagerServers(onTools: (server: McpServerConfig, tools: CachedTool[]) => void): Promise<void> {\n\t\tfor (const server of this.servers.values()) {\n\t\t\tif (server.lifecycle !== \"eager\") continue;\n\t\t\ttry {\n\t\t\t\tawait this.withConnection(server.name, async (connection) => {\n\t\t\t\t\tonTools(server, await connection.listTools());\n\t\t\t\t});\n\t\t\t} catch {\n\t\t\t\t// Recorded as `failed` by `connect`; the next call reports it.\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Close every `ready` server whose idle window has passed, unless it is kept alive. */\n\tasync sweepIdle(): Promise<void> {\n\t\tconst at = this.now();\n\t\tfor (const [name, entry] of this.entries) {\n\t\t\tconst server = this.servers.get(name);\n\t\t\tif (!server || entry.state.kind !== \"ready\" || isKeptAlive(server)) continue;\n\t\t\tif (at - entry.state.lastUsed < server.idleTimeoutMinutes * 60_000) continue;\n\t\t\tawait this.disconnect(name, entry);\n\t\t}\n\t}\n\n\tprivate async disconnect(name: string, entry: Entry): Promise<void> {\n\t\tconst connection = entry.connection;\n\t\tentry.connection = undefined;\n\t\tentry.state = { kind: \"disconnected\" };\n\t\tif (connection) {\n\t\t\tawait connection.close().catch(() => undefined);\n\t\t}\n\t\tthis.entries.set(name, entry);\n\t}\n\n\tasync closeAll(): Promise<void> {\n\t\tfor (const [name, entry] of this.entries) {\n\t\t\tawait this.disconnect(name, entry);\n\t\t}\n\t}\n}\n"]}

package/dist/core/mcp/server-manager.js

@@ -0,0 +1,142 @@
+/**
+ * Owns when a server is running and nothing about how it is reached.
+ *
+ * The `McpConnection` seam is why this module has no MCP SDK import and no child
+ * process: lifecycle is the part with the interesting failure modes (a connect that
+ * never returns, a broken server retried on every call, two callers racing the same
+ * spawn) and all of it is testable against a fake.
+ */
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+const FAILURE_BACKOFF_MS = 60_000;
+function isKeptAlive(server) {
+    return server.lifecycle === "keep-alive" || server.lifecycle === "lazy-keep-alive";
+}
+export class McpServerManager {
+    servers;
+    connector;
+    now;
+    connectTimeoutMs;
+    entries = new Map();
+    constructor(options) {
+        this.servers = options.servers;
+        this.connector = options.connector;
+        this.now = options.now ?? Date.now;
+        this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    }
+    state(name) {
+        return this.entries.get(name)?.state ?? { kind: "disconnected" };
+    }
+    entry(name) {
+        let entry = this.entries.get(name);
+        if (!entry) {
+            entry = { state: { kind: "disconnected" }, connection: undefined, pending: undefined };
+            this.entries.set(name, entry);
+        }
+        return entry;
+    }
+    async connect(server, entry) {
+        entry.state = { kind: "connecting", since: this.now() };
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Connecting to MCP server "${server.name}" timed out`)), this.connectTimeoutMs);
+        });
+        try {
+            const connection = await Promise.race([this.connector(server), timeout]);
+            const at = this.now();
+            entry.connection = connection;
+            entry.state = { kind: "ready", since: at, lastUsed: at };
+            return connection;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            entry.connection = undefined;
+            entry.state = {
+                kind: "failed",
+                error: message,
+                failedAt: this.now(),
+                retryAfter: this.now() + FAILURE_BACKOFF_MS,
+            };
+            throw error;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            entry.pending = undefined;
+        }
+    }
+    async acquire(name) {
+        const server = this.servers.get(name);
+        if (!server)
+            throw new Error(`MCP server "${name}" is not configured`);
+        const entry = this.entry(name);
+        if (entry.state.kind === "ready" && entry.connection)
+            return entry.connection;
+        if (entry.pending)
+            return entry.pending;
+        // A server that just failed is not retried until its window passes, so one
+        // broken server cannot cost every call a spawn attempt.
+        if (entry.state.kind === "failed" && this.now() < entry.state.retryAfter) {
+            throw new Error(entry.state.error);
+        }
+        entry.pending = this.connect(server, entry);
+        return entry.pending;
+    }
+    async withConnection(name, use) {
+        const connection = await this.acquire(name);
+        const result = await use(connection);
+        const entry = this.entry(name);
+        if (entry.state.kind === "ready")
+            entry.state = { ...entry.state, lastUsed: this.now() };
+        return result;
+    }
+    /**
+     * Connect every `eager` server and cache what it publishes.
+     *
+     * This is the answer to the cold-cache problem. A lazily configured server has no
+     * cached tools until something calls one, so it cannot be discovered by search; a
+     * user who wants a server discoverable from the first turn declares it `eager`.
+     * Failures are swallowed on purpose, because a broken server must not stop a
+     * session from starting.
+     */
+    async warmEagerServers(onTools) {
+        for (const server of this.servers.values()) {
+            if (server.lifecycle !== "eager")
+                continue;
+            try {
+                await this.withConnection(server.name, async (connection) => {
+                    onTools(server, await connection.listTools());
+                });
+            }
+            catch {
+                // Recorded as `failed` by `connect`; the next call reports it.
+            }
+        }
+    }
+    /** Close every `ready` server whose idle window has passed, unless it is kept alive. */
+    async sweepIdle() {
+        const at = this.now();
+        for (const [name, entry] of this.entries) {
+            const server = this.servers.get(name);
+            if (!server || entry.state.kind !== "ready" || isKeptAlive(server))
+                continue;
+            if (at - entry.state.lastUsed < server.idleTimeoutMinutes * 60_000)
+                continue;
+            await this.disconnect(name, entry);
+        }
+    }
+    async disconnect(name, entry) {
+        const connection = entry.connection;
+        entry.connection = undefined;
+        entry.state = { kind: "disconnected" };
+        if (connection) {
+            await connection.close().catch(() => undefined);
+        }
+        this.entries.set(name, entry);
+    }
+    async closeAll() {
+        for (const [name, entry] of this.entries) {
+            await this.disconnect(name, entry);
+        }
+    }
+}
+//# sourceMappingURL=server-manager.js.map

package/dist/core/mcp/server-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-manager.js","sourceRoot":"","sources":["../../../src/core/mcp/server-manager.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Owns when a server is running and nothing about how it is reached.\n *\n * The `McpConnection` seam is why this module has no MCP SDK import and no child\n * process: lifecycle is the part with the interesting failure modes (a connect that\n * never returns, a broken server retried on every call, two callers racing the same\n * spawn) and all of it is testable against a fake.\n */\n\nimport type { CachedTool, McpConnection, McpConnector, McpServerConfig, ServerState } from \"./types.ts\";\n\nconst DEFAULT_CONNECT_TIMEOUT_MS = 30_000;\nconst FAILURE_BACKOFF_MS = 60_000;\n\ninterface Entry {\n\tstate: ServerState;\n\tconnection: McpConnection | undefined;\n\t/** Held so concurrent callers await one spawn instead of racing a second. */\n\tpending: Promise<McpConnection> | undefined;\n}\n\nexport interface McpServerManagerOptions {\n\tservers: ReadonlyMap<string, McpServerConfig>;\n\tconnector: McpConnector;\n\tnow?: () => number;\n\tconnectTimeoutMs?: number;\n}\n\nfunction isKeptAlive(server: McpServerConfig): boolean {\n\treturn server.lifecycle === \"keep-alive\" || server.lifecycle === \"lazy-keep-alive\";\n}\n\nexport class McpServerManager {\n\tprivate readonly servers: ReadonlyMap<string, McpServerConfig>;\n\tprivate readonly connector: McpConnector;\n\tprivate readonly now: () => number;\n\tprivate readonly connectTimeoutMs: number;\n\tprivate readonly entries = new Map<string, Entry>();\n\n\tconstructor(options: McpServerManagerOptions) {\n\t\tthis.servers = options.servers;\n\t\tthis.connector = options.connector;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;\n\t}\n\n\tstate(name: string): ServerState {\n\t\treturn this.entries.get(name)?.state ?? { kind: \"disconnected\" };\n\t}\n\n\tprivate entry(name: string): Entry {\n\t\tlet entry = this.entries.get(name);\n\t\tif (!entry) {\n\t\t\tentry = { state: { kind: \"disconnected\" }, connection: undefined, pending: undefined };\n\t\t\tthis.entries.set(name, entry);\n\t\t}\n\t\treturn entry;\n\t}\n\n\tprivate async connect(server: McpServerConfig, entry: Entry): Promise<McpConnection> {\n\t\tentry.state = { kind: \"connecting\", since: this.now() };\n\n\t\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\t\tconst timeout = new Promise<never>((_, reject) => {\n\t\t\ttimer = setTimeout(\n\t\t\t\t() => reject(new Error(`Connecting to MCP server \"${server.name}\" timed out`)),\n\t\t\t\tthis.connectTimeoutMs,\n\t\t\t);\n\t\t});\n\n\t\ttry {\n\t\t\tconst connection = await Promise.race([this.connector(server), timeout]);\n\t\t\tconst at = this.now();\n\t\t\tentry.connection = connection;\n\t\t\tentry.state = { kind: \"ready\", since: at, lastUsed: at };\n\t\t\treturn connection;\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tentry.connection = undefined;\n\t\t\tentry.state = {\n\t\t\t\tkind: \"failed\",\n\t\t\t\terror: message,\n\t\t\t\tfailedAt: this.now(),\n\t\t\t\tretryAfter: this.now() + FAILURE_BACKOFF_MS,\n\t\t\t};\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tif (timer) clearTimeout(timer);\n\t\t\tentry.pending = undefined;\n\t\t}\n\t}\n\n\tprivate async acquire(name: string): Promise<McpConnection> {\n\t\tconst server = this.servers.get(name);\n\t\tif (!server) throw new Error(`MCP server \"${name}\" is not configured`);\n\n\t\tconst entry = this.entry(name);\n\t\tif (entry.state.kind === \"ready\" && entry.connection) return entry.connection;\n\t\tif (entry.pending) return entry.pending;\n\n\t\t// A server that just failed is not retried until its window passes, so one\n\t\t// broken server cannot cost every call a spawn attempt.\n\t\tif (entry.state.kind === \"failed\" && this.now() < entry.state.retryAfter) {\n\t\t\tthrow new Error(entry.state.error);\n\t\t}\n\n\t\tentry.pending = this.connect(server, entry);\n\t\treturn entry.pending;\n\t}\n\n\tasync withConnection<T>(name: string, use: (connection: McpConnection) => Promise<T>): Promise<T> {\n\t\tconst connection = await this.acquire(name);\n\t\tconst result = await use(connection);\n\n\t\tconst entry = this.entry(name);\n\t\tif (entry.state.kind === \"ready\") entry.state = { ...entry.state, lastUsed: this.now() };\n\t\treturn result;\n\t}\n\n\t/**\n\t * Connect every `eager` server and cache what it publishes.\n\t *\n\t * This is the answer to the cold-cache problem. A lazily configured server has no\n\t * cached tools until something calls one, so it cannot be discovered by search; a\n\t * user who wants a server discoverable from the first turn declares it `eager`.\n\t * Failures are swallowed on purpose, because a broken server must not stop a\n\t * session from starting.\n\t */\n\tasync warmEagerServers(onTools: (server: McpServerConfig, tools: CachedTool[]) => void): Promise<void> {\n\t\tfor (const server of this.servers.values()) {\n\t\t\tif (server.lifecycle !== \"eager\") continue;\n\t\t\ttry {\n\t\t\t\tawait this.withConnection(server.name, async (connection) => {\n\t\t\t\t\tonTools(server, await connection.listTools());\n\t\t\t\t});\n\t\t\t} catch {\n\t\t\t\t// Recorded as `failed` by `connect`; the next call reports it.\n\t\t\t}\n\t\t}\n\t}\n\n\t/** Close every `ready` server whose idle window has passed, unless it is kept alive. */\n\tasync sweepIdle(): Promise<void> {\n\t\tconst at = this.now();\n\t\tfor (const [name, entry] of this.entries) {\n\t\t\tconst server = this.servers.get(name);\n\t\t\tif (!server || entry.state.kind !== \"ready\" || isKeptAlive(server)) continue;\n\t\t\tif (at - entry.state.lastUsed < server.idleTimeoutMinutes * 60_000) continue;\n\t\t\tawait this.disconnect(name, entry);\n\t\t}\n\t}\n\n\tprivate async disconnect(name: string, entry: Entry): Promise<void> {\n\t\tconst connection = entry.connection;\n\t\tentry.connection = undefined;\n\t\tentry.state = { kind: \"disconnected\" };\n\t\tif (connection) {\n\t\t\tawait connection.close().catch(() => undefined);\n\t\t}\n\t\tthis.entries.set(name, entry);\n\t}\n\n\tasync closeAll(): Promise<void> {\n\t\tfor (const [name, entry] of this.entries) {\n\t\t\tawait this.disconnect(name, entry);\n\t\t}\n\t}\n}\n"]}

package/dist/core/mcp/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Core MCP data shapes. Settled before any logic consumes them, per the plan's U1:
+ * a late change to `ServerState` or `CachedTool` is a rewrite of the server manager
+ * and the proxy tool, where an early one is a one-line diff.
+ */
+import type { Capability } from "../tools/contract.ts";
+/**
+ * How to reach a server. Inferred from which fields the config entry carries, never
+ * declared: every MCP host writes `command` for stdio and `url` for HTTP, and none
+ * writes a `transport` field, so requiring one would reject the config files users
+ * already have.
+ */
+export type McpTransport = {
+    kind: "stdio";
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string | undefined;
+} | {
+    kind: "http";
+    url: string;
+    headers: Record<string, string>;
+    /** Environment variable holding a static bearer token. OAuth lives in the credential store (spec 2026-09-01-mcp-oauth). */
+    bearerTokenEnv: string | undefined;
+};
+export type McpLifecycle = "lazy" | "eager" | "keep-alive" | "lazy-keep-alive";
+export declare const DEFAULT_LIFECYCLE: McpLifecycle;
+export declare const DEFAULT_IDLE_TIMEOUT_MINUTES = 10;
+/**
+ * A server's declared authority, and the only place it is stated. The capability set
+ * feeds the tool contract every tool on this server projects (ADR 0010), which is why
+ * an absent set resolves to the full one rather than the empty one.
+ */
+export interface McpServerConfig {
+    name: string;
+    transport: McpTransport;
+    /** Set when the user opted this HTTP server into OAuth (spec 2026-09-01-mcp-oauth). Server-level, so metadata cache keys ignore it. */
+    auth?: "oauth";
+    capabilities: ReadonlySet<Capability>;
+    lifecycle: McpLifecycle;
+    idleTimeoutMinutes: number;
+}
+/**
+ * Connection state. A union rather than a `connected` boolean beside a `lastError`
+ * string, so a state cannot carry data that is invalid for it.
+ */
+export type ServerState = {
+    kind: "disconnected";
+} | {
+    kind: "connecting";
+    since: number;
+} | {
+    kind: "ready";
+    since: number;
+    lastUsed: number;
+} | {
+    kind: "failed";
+    error: string;
+    failedAt: number;
+    retryAfter: number;
+};
+/**
+ * What the disk cache holds. Everything here is producible without a live connection,
+ * which is the property that lets search and describe answer with no server running.
+ */
+export interface CachedTool {
+    server: string;
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+/** A config problem that dropped an entry or fell back to a default. Never thrown. */
+export interface McpConfigDiagnostic {
+    path: string;
+    server: string | undefined;
+    message: string;
+}
+export interface McpConfig {
+    servers: ReadonlyMap<string, McpServerConfig>;
+    diagnostics: readonly McpConfigDiagnostic[];
+}
+/** One tool call's result, in the shape the proxy tool converts to `AgentToolResult`. */
+export interface McpCallResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * A live session with one server. The seam that keeps the MCP SDK out of the
+ * lifecycle logic, and lets the server manager be tested without a child process.
+ */
+export interface McpConnection {
+    listTools(): Promise<CachedTool[]>;
+    callTool(name: string, args: unknown): Promise<McpCallResult>;
+    close(): Promise<void>;
+}
+export type McpConnector = (server: McpServerConfig) => Promise<McpConnection>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACrB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACvB,GACD;IACA,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,2HAA2H;IAC3H,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAE/E,eAAO,MAAM,iBAAiB,EAAE,YAAqB,CAAC;AACtD,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,YAAY,CAAC;IACxB,uIAAuI;IACvI,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IACtC,SAAS,EAAE,YAAY,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACpB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACrB;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC9C,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC5C;AAED,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC","sourcesContent":["/**\n * Core MCP data shapes. Settled before any logic consumes them, per the plan's U1:\n * a late change to `ServerState` or `CachedTool` is a rewrite of the server manager\n * and the proxy tool, where an early one is a one-line diff.\n */\n\nimport type { Capability } from \"../tools/contract.ts\";\n\n/**\n * How to reach a server. Inferred from which fields the config entry carries, never\n * declared: every MCP host writes `command` for stdio and `url` for HTTP, and none\n * writes a `transport` field, so requiring one would reject the config files users\n * already have.\n */\nexport type McpTransport =\n\t| {\n\t\t\tkind: \"stdio\";\n\t\t\tcommand: string;\n\t\t\targs: string[];\n\t\t\tenv: Record<string, string>;\n\t\t\tcwd: string | undefined;\n\t  }\n\t| {\n\t\t\tkind: \"http\";\n\t\t\turl: string;\n\t\t\theaders: Record<string, string>;\n\t\t\t/** Environment variable holding a static bearer token. OAuth lives in the credential store (spec 2026-09-01-mcp-oauth). */\n\t\t\tbearerTokenEnv: string | undefined;\n\t  };\n\nexport type McpLifecycle = \"lazy\" | \"eager\" | \"keep-alive\" | \"lazy-keep-alive\";\n\nexport const DEFAULT_LIFECYCLE: McpLifecycle = \"lazy\";\nexport const DEFAULT_IDLE_TIMEOUT_MINUTES = 10;\n\n/**\n * A server's declared authority, and the only place it is stated. The capability set\n * feeds the tool contract every tool on this server projects (ADR 0010), which is why\n * an absent set resolves to the full one rather than the empty one.\n */\nexport interface McpServerConfig {\n\tname: string;\n\ttransport: McpTransport;\n\t/** Set when the user opted this HTTP server into OAuth (spec 2026-09-01-mcp-oauth). Server-level, so metadata cache keys ignore it. */\n\tauth?: \"oauth\";\n\tcapabilities: ReadonlySet<Capability>;\n\tlifecycle: McpLifecycle;\n\tidleTimeoutMinutes: number;\n}\n\n/**\n * Connection state. A union rather than a `connected` boolean beside a `lastError`\n * string, so a state cannot carry data that is invalid for it.\n */\nexport type ServerState =\n\t| { kind: \"disconnected\" }\n\t| { kind: \"connecting\"; since: number }\n\t| { kind: \"ready\"; since: number; lastUsed: number }\n\t| { kind: \"failed\"; error: string; failedAt: number; retryAfter: number };\n\n/**\n * What the disk cache holds. Everything here is producible without a live connection,\n * which is the property that lets search and describe answer with no server running.\n */\nexport interface CachedTool {\n\tserver: string;\n\tname: string;\n\tdescription: string;\n\tinputSchema: unknown;\n}\n\n/** A config problem that dropped an entry or fell back to a default. Never thrown. */\nexport interface McpConfigDiagnostic {\n\tpath: string;\n\tserver: string | undefined;\n\tmessage: string;\n}\n\nexport interface McpConfig {\n\tservers: ReadonlyMap<string, McpServerConfig>;\n\tdiagnostics: readonly McpConfigDiagnostic[];\n}\n\n/** One tool call's result, in the shape the proxy tool converts to `AgentToolResult`. */\nexport interface McpCallResult {\n\tcontent: Array<{ type: \"text\"; text: string }>;\n\tisError?: boolean;\n}\n\n/**\n * A live session with one server. The seam that keeps the MCP SDK out of the\n * lifecycle logic, and lets the server manager be tested without a child process.\n */\nexport interface McpConnection {\n\tlistTools(): Promise<CachedTool[]>;\n\tcallTool(name: string, args: unknown): Promise<McpCallResult>;\n\tclose(): Promise<void>;\n}\n\nexport type McpConnector = (server: McpServerConfig) => Promise<McpConnection>;\n"]}

package/dist/core/mcp/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core MCP data shapes. Settled before any logic consumes them, per the plan's U1:
+ * a late change to `ServerState` or `CachedTool` is a rewrite of the server manager
+ * and the proxy tool, where an early one is a one-line diff.
+ */
+export const DEFAULT_LIFECYCLE = "lazy";
+export const DEFAULT_IDLE_TIMEOUT_MINUTES = 10;
+//# sourceMappingURL=types.js.map

package/dist/core/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/mcp/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4BH,MAAM,CAAC,MAAM,iBAAiB,GAAiB,MAAM,CAAC;AACtD,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAC","sourcesContent":["/**\n * Core MCP data shapes. Settled before any logic consumes them, per the plan's U1:\n * a late change to `ServerState` or `CachedTool` is a rewrite of the server manager\n * and the proxy tool, where an early one is a one-line diff.\n */\n\nimport type { Capability } from \"../tools/contract.ts\";\n\n/**\n * How to reach a server. Inferred from which fields the config entry carries, never\n * declared: every MCP host writes `command` for stdio and `url` for HTTP, and none\n * writes a `transport` field, so requiring one would reject the config files users\n * already have.\n */\nexport type McpTransport =\n\t| {\n\t\t\tkind: \"stdio\";\n\t\t\tcommand: string;\n\t\t\targs: string[];\n\t\t\tenv: Record<string, string>;\n\t\t\tcwd: string | undefined;\n\t  }\n\t| {\n\t\t\tkind: \"http\";\n\t\t\turl: string;\n\t\t\theaders: Record<string, string>;\n\t\t\t/** Environment variable holding a static bearer token. OAuth lives in the credential store (spec 2026-09-01-mcp-oauth). */\n\t\t\tbearerTokenEnv: string | undefined;\n\t  };\n\nexport type McpLifecycle = \"lazy\" | \"eager\" | \"keep-alive\" | \"lazy-keep-alive\";\n\nexport const DEFAULT_LIFECYCLE: McpLifecycle = \"lazy\";\nexport const DEFAULT_IDLE_TIMEOUT_MINUTES = 10;\n\n/**\n * A server's declared authority, and the only place it is stated. The capability set\n * feeds the tool contract every tool on this server projects (ADR 0010), which is why\n * an absent set resolves to the full one rather than the empty one.\n */\nexport interface McpServerConfig {\n\tname: string;\n\ttransport: McpTransport;\n\t/** Set when the user opted this HTTP server into OAuth (spec 2026-09-01-mcp-oauth). Server-level, so metadata cache keys ignore it. */\n\tauth?: \"oauth\";\n\tcapabilities: ReadonlySet<Capability>;\n\tlifecycle: McpLifecycle;\n\tidleTimeoutMinutes: number;\n}\n\n/**\n * Connection state. A union rather than a `connected` boolean beside a `lastError`\n * string, so a state cannot carry data that is invalid for it.\n */\nexport type ServerState =\n\t| { kind: \"disconnected\" }\n\t| { kind: \"connecting\"; since: number }\n\t| { kind: \"ready\"; since: number; lastUsed: number }\n\t| { kind: \"failed\"; error: string; failedAt: number; retryAfter: number };\n\n/**\n * What the disk cache holds. Everything here is producible without a live connection,\n * which is the property that lets search and describe answer with no server running.\n */\nexport interface CachedTool {\n\tserver: string;\n\tname: string;\n\tdescription: string;\n\tinputSchema: unknown;\n}\n\n/** A config problem that dropped an entry or fell back to a default. Never thrown. */\nexport interface McpConfigDiagnostic {\n\tpath: string;\n\tserver: string | undefined;\n\tmessage: string;\n}\n\nexport interface McpConfig {\n\tservers: ReadonlyMap<string, McpServerConfig>;\n\tdiagnostics: readonly McpConfigDiagnostic[];\n}\n\n/** One tool call's result, in the shape the proxy tool converts to `AgentToolResult`. */\nexport interface McpCallResult {\n\tcontent: Array<{ type: \"text\"; text: string }>;\n\tisError?: boolean;\n}\n\n/**\n * A live session with one server. The seam that keeps the MCP SDK out of the\n * lifecycle logic, and lets the server manager be tested without a child process.\n */\nexport interface McpConnection {\n\tlistTools(): Promise<CachedTool[]>;\n\tcallTool(name: string, args: unknown): Promise<McpCallResult>;\n\tclose(): Promise<void>;\n}\n\nexport type McpConnector = (server: McpServerConfig) => Promise<McpConnection>;\n"]}