apex-code 0.0.1-alpha.1 → 0.0.1-alpha.11

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,98 @@
+/**
+ * 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 bearer token. OAuth is a spec non-goal (ADR 0015). */
+    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;
+    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,wFAAwF;IACxF,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,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 bearer token. OAuth is a spec non-goal (ADR 0015). */\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\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 bearer token. OAuth is a spec non-goal (ADR 0015). */\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\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/model-config.d.ts

@@ -38,6 +38,7 @@ declare const ModelDefinitionSchema: Type.TObject<{
         supportsDeveloperRole: Type.TOptional<Type.TBoolean>;
         supportsReasoningEffort: Type.TOptional<Type.TBoolean>;
         supportsUsageInStreaming: Type.TOptional<Type.TBoolean>;
+        supportsFinishReason: Type.TOptional<Type.TBoolean>;
         maxTokensField: Type.TOptional<Type.TUnion<[Type.TLiteral<"max_completion_tokens">, Type.TLiteral<"max_tokens">]>>;
         requiresToolResultName: Type.TOptional<Type.TBoolean>;
         requiresAssistantAfterToolResult: Type.TOptional<Type.TBoolean>;
@@ -103,6 +104,7 @@ declare const ModelDefinitionSchema: Type.TObject<{
         supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
         supportsStrictMode: Type.TOptional<Type.TBoolean>;
         supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+        supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
         supportsToolSearch: Type.TOptional<Type.TBoolean>;
     }>, Type.TObject<{
         supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -151,6 +153,7 @@ declare const ModelOverrideSchema: Type.TObject<{
         supportsDeveloperRole: Type.TOptional<Type.TBoolean>;
         supportsReasoningEffort: Type.TOptional<Type.TBoolean>;
         supportsUsageInStreaming: Type.TOptional<Type.TBoolean>;
+        supportsFinishReason: Type.TOptional<Type.TBoolean>;
         maxTokensField: Type.TOptional<Type.TUnion<[Type.TLiteral<"max_completion_tokens">, Type.TLiteral<"max_tokens">]>>;
         requiresToolResultName: Type.TOptional<Type.TBoolean>;
         requiresAssistantAfterToolResult: Type.TOptional<Type.TBoolean>;
@@ -216,6 +219,7 @@ declare const ModelOverrideSchema: Type.TObject<{
         supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
         supportsStrictMode: Type.TOptional<Type.TBoolean>;
         supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+        supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
         supportsToolSearch: Type.TOptional<Type.TBoolean>;
     }>, Type.TObject<{
         supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -241,6 +245,7 @@ declare const ProviderConfigSchema: Type.TObject<{
         supportsDeveloperRole: Type.TOptional<Type.TBoolean>;
         supportsReasoningEffort: Type.TOptional<Type.TBoolean>;
         supportsUsageInStreaming: Type.TOptional<Type.TBoolean>;
+        supportsFinishReason: Type.TOptional<Type.TBoolean>;
         maxTokensField: Type.TOptional<Type.TUnion<[Type.TLiteral<"max_completion_tokens">, Type.TLiteral<"max_tokens">]>>;
         requiresToolResultName: Type.TOptional<Type.TBoolean>;
         requiresAssistantAfterToolResult: Type.TOptional<Type.TBoolean>;
@@ -306,6 +311,7 @@ declare const ProviderConfigSchema: Type.TObject<{
         supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
         supportsStrictMode: Type.TOptional<Type.TBoolean>;
         supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+        supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
         supportsToolSearch: Type.TOptional<Type.TBoolean>;
     }>, Type.TObject<{
         supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -357,6 +363,7 @@ declare const ProviderConfigSchema: Type.TObject<{
             supportsDeveloperRole: Type.TOptional<Type.TBoolean>;
             supportsReasoningEffort: Type.TOptional<Type.TBoolean>;
             supportsUsageInStreaming: Type.TOptional<Type.TBoolean>;
+            supportsFinishReason: Type.TOptional<Type.TBoolean>;
             maxTokensField: Type.TOptional<Type.TUnion<[Type.TLiteral<"max_completion_tokens">, Type.TLiteral<"max_tokens">]>>;
             requiresToolResultName: Type.TOptional<Type.TBoolean>;
             requiresAssistantAfterToolResult: Type.TOptional<Type.TBoolean>;
@@ -422,6 +429,7 @@ declare const ProviderConfigSchema: Type.TObject<{
             supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
             supportsStrictMode: Type.TOptional<Type.TBoolean>;
             supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+            supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
             supportsToolSearch: Type.TOptional<Type.TBoolean>;
         }>, Type.TObject<{
             supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -470,6 +478,7 @@ declare const ProviderConfigSchema: Type.TObject<{
             supportsDeveloperRole: Type.TOptional<Type.TBoolean>;
             supportsReasoningEffort: Type.TOptional<Type.TBoolean>;
             supportsUsageInStreaming: Type.TOptional<Type.TBoolean>;
+            supportsFinishReason: Type.TOptional<Type.TBoolean>;
             maxTokensField: Type.TOptional<Type.TUnion<[Type.TLiteral<"max_completion_tokens">, Type.TLiteral<"max_tokens">]>>;
             requiresToolResultName: Type.TOptional<Type.TBoolean>;
             requiresAssistantAfterToolResult: Type.TOptional<Type.TBoolean>;
@@ -535,6 +544,7 @@ declare const ProviderConfigSchema: Type.TObject<{
             supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
             supportsStrictMode: Type.TOptional<Type.TBoolean>;
             supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+            supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
             supportsToolSearch: Type.TOptional<Type.TBoolean>;
         }>, Type.TObject<{
             supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -549,17 +559,25 @@ declare const ProviderConfigSchema: Type.TObject<{
         }>]>>;
     }>>>;
 }>;
+declare const RoleDefinitionSchema: Type.TObject<{
+    /** Ordered, non-empty list of canonical "provider/modelId" candidates. */
+    models: Type.TArray<Type.TString>;
+}>;
 export type ModelsJsonModel = Static<typeof ModelDefinitionSchema>;
 export type ModelsJsonModelOverride = Static<typeof ModelOverrideSchema>;
 export type ModelsJsonProvider = Static<typeof ProviderConfigSchema>;
+export type ModelsJsonRoleDefinition = Static<typeof RoleDefinitionSchema>;
 /** One immutable load of models.json. */
 export declare class ModelConfig {
     private readonly providers;
+    private readonly roles;
     private readonly error;
     private constructor();
     static load(modelsJsonPath: string | undefined): Promise<ModelConfig>;
     getProvider(providerId: string): ModelsJsonProvider | undefined;
     getProviderIds(): readonly string[];
+    /** Additive role -> ordered "provider/modelId" candidate references, unresolved. */
+    getRoles(): ReadonlyMap<string, readonly string[]>;
     getError(): string | undefined;
 }
 export {};

package/dist/core/model-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-config.d.ts","sourceRoot":"","sources":["../../src/core/model-config.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAGxD,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAwJ5C,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAczB,CAAC;AAEH,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBvB,CAAC;AAEH,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWxB,CAAC;AAOH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACnE,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAsBrE,yCAAyC;AACzC,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C,OAAO,eAGN;IAED,OAAa,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAuC1E;IAED,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE9D;IAED,cAAc,IAAI,SAAS,MAAM,EAAE,CAElC;IAED,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7B;CACD","sourcesContent":["/** Immutable, credential-blind models.json snapshot. */\n\nimport { readFile } from \"node:fs/promises\";\nimport { type Static, Type } from \"typebox\";\nimport { Compile } from \"typebox/compile\";\nimport type { TLocalizedValidationError } from \"typebox/error\";\nimport { stripJsonComments } from \"../utils/json.ts\";\nimport { normalizePath } from \"../utils/paths.ts\";\n\nconst PercentileCutoffsSchema = Type.Object({\n\tp50: Type.Optional(Type.Number()),\n\tp75: Type.Optional(Type.Number()),\n\tp90: Type.Optional(Type.Number()),\n\tp99: Type.Optional(Type.Number()),\n});\n\nconst OpenRouterRoutingSchema = Type.Object({\n\tallow_fallbacks: Type.Optional(Type.Boolean()),\n\trequire_parameters: Type.Optional(Type.Boolean()),\n\tdata_collection: Type.Optional(Type.Union([Type.Literal(\"deny\"), Type.Literal(\"allow\")])),\n\tzdr: Type.Optional(Type.Boolean()),\n\tenforce_distillable_text: Type.Optional(Type.Boolean()),\n\torder: Type.Optional(Type.Array(Type.String())),\n\tonly: Type.Optional(Type.Array(Type.String())),\n\tignore: Type.Optional(Type.Array(Type.String())),\n\tquantizations: Type.Optional(Type.Array(Type.String())),\n\tsort: Type.Optional(\n\t\tType.Union([\n\t\t\tType.String(),\n\t\t\tType.Object({\n\t\t\t\tby: Type.Optional(Type.String()),\n\t\t\t\tpartition: Type.Optional(Type.Union([Type.String(), Type.Null()])),\n\t\t\t}),\n\t\t]),\n\t),\n\tmax_price: Type.Optional(\n\t\tType.Object({\n\t\t\tprompt: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\tcompletion: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\timage: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\taudio: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\trequest: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t}),\n\t),\n\tpreferred_min_throughput: Type.Optional(Type.Union([Type.Number(), PercentileCutoffsSchema])),\n\tpreferred_max_latency: Type.Optional(Type.Union([Type.Number(), PercentileCutoffsSchema])),\n});\n\nconst VercelGatewayRoutingSchema = Type.Object({\n\tonly: Type.Optional(Type.Array(Type.String())),\n\torder: Type.Optional(Type.Array(Type.String())),\n});\n\nconst ThinkingLevelMapValueSchema = Type.Union([Type.String(), Type.Null()]);\nconst ThinkingLevelMapSchema = Type.Object({\n\toff: Type.Optional(ThinkingLevelMapValueSchema),\n\tminimal: Type.Optional(ThinkingLevelMapValueSchema),\n\tlow: Type.Optional(ThinkingLevelMapValueSchema),\n\tmedium: Type.Optional(ThinkingLevelMapValueSchema),\n\thigh: Type.Optional(ThinkingLevelMapValueSchema),\n\txhigh: Type.Optional(ThinkingLevelMapValueSchema),\n\tmax: Type.Optional(ThinkingLevelMapValueSchema),\n});\n\nconst ChatTemplateKwargScalarSchema = Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]);\nconst ChatTemplateKwargVariableSchema = Type.Object({\n\t$var: Type.Union([Type.Literal(\"thinking.enabled\"), Type.Literal(\"thinking.effort\")]),\n\tomitWhenOff: Type.Optional(Type.Boolean()),\n});\nconst ChatTemplateKwargSchema = Type.Union([ChatTemplateKwargScalarSchema, ChatTemplateKwargVariableSchema]);\n\nconst OpenAICompletionsCompatSchema = Type.Object({\n\tsupportsStore: Type.Optional(Type.Boolean()),\n\tsupportsDeveloperRole: Type.Optional(Type.Boolean()),\n\tsupportsReasoningEffort: Type.Optional(Type.Boolean()),\n\tsupportsUsageInStreaming: Type.Optional(Type.Boolean()),\n\tmaxTokensField: Type.Optional(Type.Union([Type.Literal(\"max_completion_tokens\"), Type.Literal(\"max_tokens\")])),\n\trequiresToolResultName: Type.Optional(Type.Boolean()),\n\trequiresAssistantAfterToolResult: Type.Optional(Type.Boolean()),\n\trequiresThinkingAsText: Type.Optional(Type.Boolean()),\n\trequiresReasoningContentOnAssistantMessages: Type.Optional(Type.Boolean()),\n\tthinkingFormat: Type.Optional(\n\t\tType.Union([\n\t\t\tType.Literal(\"openai\"),\n\t\t\tType.Literal(\"openrouter\"),\n\t\t\tType.Literal(\"together\"),\n\t\t\tType.Literal(\"baseten\"),\n\t\t\tType.Literal(\"deepseek\"),\n\t\t\tType.Literal(\"zai\"),\n\t\t\tType.Literal(\"qwen\"),\n\t\t\tType.Literal(\"chat-template\"),\n\t\t\tType.Literal(\"qwen-chat-template\"),\n\t\t\tType.Literal(\"string-thinking\"),\n\t\t\tType.Literal(\"ant-ling\"),\n\t\t]),\n\t),\n\tchatTemplateKwargs: Type.Optional(Type.Record(Type.String(), ChatTemplateKwargSchema)),\n\tchatTemplateArgs: Type.Optional(Type.Record(Type.String(), ChatTemplateKwargSchema)),\n\tcacheControlFormat: Type.Optional(Type.Literal(\"anthropic\")),\n\topenRouterRouting: Type.Optional(OpenRouterRoutingSchema),\n\tvercelGatewayRouting: Type.Optional(VercelGatewayRoutingSchema),\n\tsupportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),\n\tsupportsStrictMode: Type.Optional(Type.Boolean()),\n\tsendSessionAffinityHeaders: Type.Optional(Type.Boolean()),\n\tdeferredToolsMode: Type.Optional(Type.Literal(\"kimi\")),\n\tsessionAffinityFormat: Type.Optional(\n\t\tType.Union([Type.Literal(\"openai\"), Type.Literal(\"openai-nosession\"), Type.Literal(\"openrouter\")]),\n\t),\n\tsupportsLongCacheRetention: Type.Optional(Type.Boolean()),\n});\n\nconst OpenAIResponsesCompatSchema = Type.Object({\n\tsupportsDeveloperRole: Type.Optional(Type.Boolean()),\n\tsessionAffinityFormat: Type.Optional(\n\t\tType.Union([Type.Literal(\"openai\"), Type.Literal(\"openai-nosession\"), Type.Literal(\"openrouter\")]),\n\t),\n\tsupportsLongCacheRetention: Type.Optional(Type.Boolean()),\n\tsupportsStrictMode: Type.Optional(Type.Boolean()),\n\tsupportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),\n\tsupportsToolSearch: Type.Optional(Type.Boolean()),\n});\n\nconst AnthropicMessagesCompatSchema = Type.Object({\n\tsupportsEagerToolInputStreaming: Type.Optional(Type.Boolean()),\n\tsupportsLongCacheRetention: Type.Optional(Type.Boolean()),\n\tsendSessionAffinityHeaders: Type.Optional(Type.Boolean()),\n\tsupportsCacheControlOnTools: Type.Optional(Type.Boolean()),\n\tsupportsTemperature: Type.Optional(Type.Boolean()),\n\tforceAdaptiveThinking: Type.Optional(Type.Boolean()),\n\tallowEmptySignature: Type.Optional(Type.Boolean()),\n\tsupportsStrictTools: Type.Optional(Type.Boolean()),\n\tsupportsToolReferences: Type.Optional(Type.Boolean()),\n});\n\nconst ProviderCompatSchema = Type.Union([\n\tOpenAICompletionsCompatSchema,\n\tOpenAIResponsesCompatSchema,\n\tAnthropicMessagesCompatSchema,\n]);\n\nconst ModelCostRatesSchema = {\n\tinput: Type.Number(),\n\toutput: Type.Number(),\n\tcacheRead: Type.Number(),\n\tcacheWrite: Type.Number(),\n};\nconst ModelCostTierSchema = Type.Object({\n\tinputTokensAbove: Type.Number(),\n\t...ModelCostRatesSchema,\n});\nconst ModelCostSchema = Type.Object({\n\t...ModelCostRatesSchema,\n\ttiers: Type.Optional(Type.Array(ModelCostTierSchema)),\n});\n\nconst ModelDefinitionSchema = Type.Object({\n\tid: Type.String({ minLength: 1 }),\n\tname: Type.Optional(Type.String({ minLength: 1 })),\n\tapi: Type.Optional(Type.String({ minLength: 1 })),\n\tbaseUrl: Type.Optional(Type.String({ minLength: 1 })),\n\treasoning: Type.Optional(Type.Boolean()),\n\tthinkingLevelMap: Type.Optional(ThinkingLevelMapSchema),\n\tinput: Type.Optional(Type.Array(Type.Union([Type.Literal(\"text\"), Type.Literal(\"image\")]))),\n\tcost: Type.Optional(ModelCostSchema),\n\tcontextWindow: Type.Optional(Type.Number()),\n\tmaxTokens: Type.Optional(Type.Number()),\n\tsamplingParams: Type.Optional(Type.Record(Type.String(), Type.Unknown())),\n\theaders: Type.Optional(Type.Record(Type.String(), Type.String())),\n\tcompat: Type.Optional(ProviderCompatSchema),\n});\n\nconst ModelOverrideSchema = Type.Object({\n\tname: Type.Optional(Type.String({ minLength: 1 })),\n\treasoning: Type.Optional(Type.Boolean()),\n\tthinkingLevelMap: Type.Optional(ThinkingLevelMapSchema),\n\tinput: Type.Optional(Type.Array(Type.Union([Type.Literal(\"text\"), Type.Literal(\"image\")]))),\n\tcost: Type.Optional(\n\t\tType.Object({\n\t\t\tinput: Type.Optional(Type.Number()),\n\t\t\toutput: Type.Optional(Type.Number()),\n\t\t\tcacheRead: Type.Optional(Type.Number()),\n\t\t\tcacheWrite: Type.Optional(Type.Number()),\n\t\t\ttiers: Type.Optional(Type.Array(ModelCostTierSchema)),\n\t\t}),\n\t),\n\tcontextWindow: Type.Optional(Type.Number()),\n\tmaxTokens: Type.Optional(Type.Number()),\n\tsamplingParams: Type.Optional(Type.Record(Type.String(), Type.Unknown())),\n\theaders: Type.Optional(Type.Record(Type.String(), Type.String())),\n\tcompat: Type.Optional(ProviderCompatSchema),\n});\n\nconst ProviderConfigSchema = Type.Object({\n\tname: Type.Optional(Type.String({ minLength: 1 })),\n\tbaseUrl: Type.Optional(Type.String({ minLength: 1 })),\n\tapiKey: Type.Optional(Type.String({ minLength: 1 })),\n\tapi: Type.Optional(Type.String({ minLength: 1 })),\n\toauth: Type.Optional(Type.Literal(\"radius\")),\n\theaders: Type.Optional(Type.Record(Type.String(), Type.String())),\n\tcompat: Type.Optional(ProviderCompatSchema),\n\tauthHeader: Type.Optional(Type.Boolean()),\n\tmodels: Type.Optional(Type.Array(ModelDefinitionSchema)),\n\tmodelOverrides: Type.Optional(Type.Record(Type.String(), ModelOverrideSchema)),\n});\n\nconst ModelsConfigSchema = Type.Object({\n\tproviders: Type.Record(Type.String(), ProviderConfigSchema),\n});\nconst validateModelsConfig = Compile(ModelsConfigSchema);\n\nexport type ModelsJsonModel = Static<typeof ModelDefinitionSchema>;\nexport type ModelsJsonModelOverride = Static<typeof ModelOverrideSchema>;\nexport type ModelsJsonProvider = Static<typeof ProviderConfigSchema>;\ntype ModelsJson = Static<typeof ModelsConfigSchema>;\n\nfunction formatValidationPath(error: TLocalizedValidationError): string {\n\tif (error.keyword === \"required\") {\n\t\tconst requiredProperties = (error.params as { requiredProperties?: string[] }).requiredProperties;\n\t\tconst requiredProperty = requiredProperties?.[0];\n\t\tif (requiredProperty) {\n\t\t\tconst basePath = error.instancePath.replace(/^\\//, \"\").replace(/\\//g, \".\");\n\t\t\treturn basePath ? `${basePath}.${requiredProperty}` : requiredProperty;\n\t\t}\n\t}\n\tconst path = error.instancePath.replace(/^\\//, \"\").replace(/\\//g, \".\");\n\treturn path || \"root\";\n}\n\nfunction deepFreeze<T>(value: T): T {\n\tif (typeof value !== \"object\" || value === null || Object.isFrozen(value)) return value;\n\tfor (const child of Object.values(value)) deepFreeze(child);\n\treturn Object.freeze(value);\n}\n\n/** One immutable load of models.json. */\nexport class ModelConfig {\n\tprivate readonly providers: ReadonlyMap<string, ModelsJsonProvider>;\n\tprivate readonly error: string | undefined;\n\n\tprivate constructor(providers: ReadonlyMap<string, ModelsJsonProvider>, error?: string) {\n\t\tthis.providers = providers;\n\t\tthis.error = error;\n\t}\n\n\tstatic async load(modelsJsonPath: string | undefined): Promise<ModelConfig> {\n\t\tif (!modelsJsonPath) return new ModelConfig(new Map());\n\t\tconst path = normalizePath(modelsJsonPath);\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = await readFile(path, \"utf-8\");\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return new ModelConfig(new Map());\n\t\t\treturn new ModelConfig(\n\t\t\t\tnew Map(),\n\t\t\t\t`Failed to load models.json: ${error instanceof Error ? error.message : error}\\n\\nFile: ${path}`,\n\t\t\t);\n\t\t}\n\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(stripJsonComments(content));\n\t\t} catch (error) {\n\t\t\treturn new ModelConfig(\n\t\t\t\tnew Map(),\n\t\t\t\t`Failed to parse models.json: ${error instanceof Error ? error.message : error}\\n\\nFile: ${path}`,\n\t\t\t);\n\t\t}\n\n\t\tif (!validateModelsConfig.Check(parsed)) {\n\t\t\tconst errors =\n\t\t\t\tvalidateModelsConfig\n\t\t\t\t\t.Errors(parsed)\n\t\t\t\t\t.map((error) => `  - ${formatValidationPath(error)}: ${error.message}`)\n\t\t\t\t\t.join(\"\\n\") || \"Unknown schema error\";\n\t\t\treturn new ModelConfig(new Map(), `Invalid models.json schema:\\n${errors}\\n\\nFile: ${path}`);\n\t\t}\n\n\t\tconst config = parsed as ModelsJson;\n\t\tconst providers = new Map<string, ModelsJsonProvider>();\n\t\tfor (const [providerId, provider] of Object.entries(config.providers)) {\n\t\t\tproviders.set(providerId, deepFreeze(structuredClone(provider)));\n\t\t}\n\t\treturn new ModelConfig(providers);\n\t}\n\n\tgetProvider(providerId: string): ModelsJsonProvider | undefined {\n\t\treturn this.providers.get(providerId);\n\t}\n\n\tgetProviderIds(): readonly string[] {\n\t\treturn [...this.providers.keys()];\n\t}\n\n\tgetError(): string | undefined {\n\t\treturn this.error;\n\t}\n}\n"]}
+{"version":3,"file":"model-config.d.ts","sourceRoot":"","sources":["../../src/core/model-config.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAGxD,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AA2J5C,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAczB,CAAC;AAEH,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBvB,CAAC;AAEH,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWxB,CAAC;AAEH,QAAA,MAAM,oBAAoB;IACzB,0EAA0E;;EAEzE,CAAC;AASH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACnE,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACrE,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAsB3E,yCAAyC;AACzC,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0C;IACpE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyC;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C,OAAO,eAQN;IAED,OAAa,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CA6C1E;IAED,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE9D;IAED,cAAc,IAAI,SAAS,MAAM,EAAE,CAElC;IAED,oFAAoF;IACpF,QAAQ,IAAI,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAEjD;IAED,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7B;CACD","sourcesContent":["/** Immutable, credential-blind models.json snapshot. */\n\nimport { readFile } from \"node:fs/promises\";\nimport { type Static, Type } from \"typebox\";\nimport { Compile } from \"typebox/compile\";\nimport type { TLocalizedValidationError } from \"typebox/error\";\nimport { stripJsonComments } from \"../utils/json.ts\";\nimport { normalizePath } from \"../utils/paths.ts\";\nimport { stripBom } from \"../utils/text.ts\";\n\nconst PercentileCutoffsSchema = Type.Object({\n\tp50: Type.Optional(Type.Number()),\n\tp75: Type.Optional(Type.Number()),\n\tp90: Type.Optional(Type.Number()),\n\tp99: Type.Optional(Type.Number()),\n});\n\nconst OpenRouterRoutingSchema = Type.Object({\n\tallow_fallbacks: Type.Optional(Type.Boolean()),\n\trequire_parameters: Type.Optional(Type.Boolean()),\n\tdata_collection: Type.Optional(Type.Union([Type.Literal(\"deny\"), Type.Literal(\"allow\")])),\n\tzdr: Type.Optional(Type.Boolean()),\n\tenforce_distillable_text: Type.Optional(Type.Boolean()),\n\torder: Type.Optional(Type.Array(Type.String())),\n\tonly: Type.Optional(Type.Array(Type.String())),\n\tignore: Type.Optional(Type.Array(Type.String())),\n\tquantizations: Type.Optional(Type.Array(Type.String())),\n\tsort: Type.Optional(\n\t\tType.Union([\n\t\t\tType.String(),\n\t\t\tType.Object({\n\t\t\t\tby: Type.Optional(Type.String()),\n\t\t\t\tpartition: Type.Optional(Type.Union([Type.String(), Type.Null()])),\n\t\t\t}),\n\t\t]),\n\t),\n\tmax_price: Type.Optional(\n\t\tType.Object({\n\t\t\tprompt: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\tcompletion: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\timage: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\taudio: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t\trequest: Type.Optional(Type.Union([Type.Number(), Type.String()])),\n\t\t}),\n\t),\n\tpreferred_min_throughput: Type.Optional(Type.Union([Type.Number(), PercentileCutoffsSchema])),\n\tpreferred_max_latency: Type.Optional(Type.Union([Type.Number(), PercentileCutoffsSchema])),\n});\n\nconst VercelGatewayRoutingSchema = Type.Object({\n\tonly: Type.Optional(Type.Array(Type.String())),\n\torder: Type.Optional(Type.Array(Type.String())),\n});\n\nconst ThinkingLevelMapValueSchema = Type.Union([Type.String(), Type.Null()]);\nconst ThinkingLevelMapSchema = Type.Object({\n\toff: Type.Optional(ThinkingLevelMapValueSchema),\n\tminimal: Type.Optional(ThinkingLevelMapValueSchema),\n\tlow: Type.Optional(ThinkingLevelMapValueSchema),\n\tmedium: Type.Optional(ThinkingLevelMapValueSchema),\n\thigh: Type.Optional(ThinkingLevelMapValueSchema),\n\txhigh: Type.Optional(ThinkingLevelMapValueSchema),\n\tmax: Type.Optional(ThinkingLevelMapValueSchema),\n});\n\nconst ChatTemplateKwargScalarSchema = Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]);\nconst ChatTemplateKwargVariableSchema = Type.Object({\n\t$var: Type.Union([Type.Literal(\"thinking.enabled\"), Type.Literal(\"thinking.effort\")]),\n\tomitWhenOff: Type.Optional(Type.Boolean()),\n});\nconst ChatTemplateKwargSchema = Type.Union([ChatTemplateKwargScalarSchema, ChatTemplateKwargVariableSchema]);\n\nconst OpenAICompletionsCompatSchema = Type.Object({\n\tsupportsStore: Type.Optional(Type.Boolean()),\n\tsupportsDeveloperRole: Type.Optional(Type.Boolean()),\n\tsupportsReasoningEffort: Type.Optional(Type.Boolean()),\n\tsupportsUsageInStreaming: Type.Optional(Type.Boolean()),\n\tsupportsFinishReason: Type.Optional(Type.Boolean()),\n\tmaxTokensField: Type.Optional(Type.Union([Type.Literal(\"max_completion_tokens\"), Type.Literal(\"max_tokens\")])),\n\trequiresToolResultName: Type.Optional(Type.Boolean()),\n\trequiresAssistantAfterToolResult: Type.Optional(Type.Boolean()),\n\trequiresThinkingAsText: Type.Optional(Type.Boolean()),\n\trequiresReasoningContentOnAssistantMessages: Type.Optional(Type.Boolean()),\n\tthinkingFormat: Type.Optional(\n\t\tType.Union([\n\t\t\tType.Literal(\"openai\"),\n\t\t\tType.Literal(\"openrouter\"),\n\t\t\tType.Literal(\"together\"),\n\t\t\tType.Literal(\"baseten\"),\n\t\t\tType.Literal(\"deepseek\"),\n\t\t\tType.Literal(\"zai\"),\n\t\t\tType.Literal(\"qwen\"),\n\t\t\tType.Literal(\"chat-template\"),\n\t\t\tType.Literal(\"qwen-chat-template\"),\n\t\t\tType.Literal(\"string-thinking\"),\n\t\t\tType.Literal(\"ant-ling\"),\n\t\t]),\n\t),\n\tchatTemplateKwargs: Type.Optional(Type.Record(Type.String(), ChatTemplateKwargSchema)),\n\tchatTemplateArgs: Type.Optional(Type.Record(Type.String(), ChatTemplateKwargSchema)),\n\tcacheControlFormat: Type.Optional(Type.Literal(\"anthropic\")),\n\topenRouterRouting: Type.Optional(OpenRouterRoutingSchema),\n\tvercelGatewayRouting: Type.Optional(VercelGatewayRoutingSchema),\n\tsupportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),\n\tsupportsStrictMode: Type.Optional(Type.Boolean()),\n\tsendSessionAffinityHeaders: Type.Optional(Type.Boolean()),\n\tdeferredToolsMode: Type.Optional(Type.Literal(\"kimi\")),\n\tsessionAffinityFormat: Type.Optional(\n\t\tType.Union([Type.Literal(\"openai\"), Type.Literal(\"openai-nosession\"), Type.Literal(\"openrouter\")]),\n\t),\n\tsupportsLongCacheRetention: Type.Optional(Type.Boolean()),\n});\n\nconst OpenAIResponsesCompatSchema = Type.Object({\n\tsupportsDeveloperRole: Type.Optional(Type.Boolean()),\n\tsessionAffinityFormat: Type.Optional(\n\t\tType.Union([Type.Literal(\"openai\"), Type.Literal(\"openai-nosession\"), Type.Literal(\"openrouter\")]),\n\t),\n\tsupportsLongCacheRetention: Type.Optional(Type.Boolean()),\n\tsupportsStrictMode: Type.Optional(Type.Boolean()),\n\tsupportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),\n\tsupportsAdditionalTools: Type.Optional(Type.Boolean()),\n\tsupportsToolSearch: Type.Optional(Type.Boolean()),\n});\n\nconst AnthropicMessagesCompatSchema = Type.Object({\n\tsupportsEagerToolInputStreaming: Type.Optional(Type.Boolean()),\n\tsupportsLongCacheRetention: Type.Optional(Type.Boolean()),\n\tsendSessionAffinityHeaders: Type.Optional(Type.Boolean()),\n\tsupportsCacheControlOnTools: Type.Optional(Type.Boolean()),\n\tsupportsTemperature: Type.Optional(Type.Boolean()),\n\tforceAdaptiveThinking: Type.Optional(Type.Boolean()),\n\tallowEmptySignature: Type.Optional(Type.Boolean()),\n\tsupportsStrictTools: Type.Optional(Type.Boolean()),\n\tsupportsToolReferences: Type.Optional(Type.Boolean()),\n});\n\nconst ProviderCompatSchema = Type.Union([\n\tOpenAICompletionsCompatSchema,\n\tOpenAIResponsesCompatSchema,\n\tAnthropicMessagesCompatSchema,\n]);\n\nconst ModelCostRatesSchema = {\n\tinput: Type.Number(),\n\toutput: Type.Number(),\n\tcacheRead: Type.Number(),\n\tcacheWrite: Type.Number(),\n};\nconst ModelCostTierSchema = Type.Object({\n\tinputTokensAbove: Type.Number(),\n\t...ModelCostRatesSchema,\n});\nconst ModelCostSchema = Type.Object({\n\t...ModelCostRatesSchema,\n\ttiers: Type.Optional(Type.Array(ModelCostTierSchema)),\n});\n\nconst ModelDefinitionSchema = Type.Object({\n\tid: Type.String({ minLength: 1 }),\n\tname: Type.Optional(Type.String({ minLength: 1 })),\n\tapi: Type.Optional(Type.String({ minLength: 1 })),\n\tbaseUrl: Type.Optional(Type.String({ minLength: 1 })),\n\treasoning: Type.Optional(Type.Boolean()),\n\tthinkingLevelMap: Type.Optional(ThinkingLevelMapSchema),\n\tinput: Type.Optional(Type.Array(Type.Union([Type.Literal(\"text\"), Type.Literal(\"image\")]))),\n\tcost: Type.Optional(ModelCostSchema),\n\tcontextWindow: Type.Optional(Type.Number()),\n\tmaxTokens: Type.Optional(Type.Number()),\n\tsamplingParams: Type.Optional(Type.Record(Type.String(), Type.Unknown())),\n\theaders: Type.Optional(Type.Record(Type.String(), Type.String())),\n\tcompat: Type.Optional(ProviderCompatSchema),\n});\n\nconst ModelOverrideSchema = Type.Object({\n\tname: Type.Optional(Type.String({ minLength: 1 })),\n\treasoning: Type.Optional(Type.Boolean()),\n\tthinkingLevelMap: Type.Optional(ThinkingLevelMapSchema),\n\tinput: Type.Optional(Type.Array(Type.Union([Type.Literal(\"text\"), Type.Literal(\"image\")]))),\n\tcost: Type.Optional(\n\t\tType.Object({\n\t\t\tinput: Type.Optional(Type.Number()),\n\t\t\toutput: Type.Optional(Type.Number()),\n\t\t\tcacheRead: Type.Optional(Type.Number()),\n\t\t\tcacheWrite: Type.Optional(Type.Number()),\n\t\t\ttiers: Type.Optional(Type.Array(ModelCostTierSchema)),\n\t\t}),\n\t),\n\tcontextWindow: Type.Optional(Type.Number()),\n\tmaxTokens: Type.Optional(Type.Number()),\n\tsamplingParams: Type.Optional(Type.Record(Type.String(), Type.Unknown())),\n\theaders: Type.Optional(Type.Record(Type.String(), Type.String())),\n\tcompat: Type.Optional(ProviderCompatSchema),\n});\n\nconst ProviderConfigSchema = Type.Object({\n\tname: Type.Optional(Type.String({ minLength: 1 })),\n\tbaseUrl: Type.Optional(Type.String({ minLength: 1 })),\n\tapiKey: Type.Optional(Type.String({ minLength: 1 })),\n\tapi: Type.Optional(Type.String({ minLength: 1 })),\n\toauth: Type.Optional(Type.Literal(\"radius\")),\n\theaders: Type.Optional(Type.Record(Type.String(), Type.String())),\n\tcompat: Type.Optional(ProviderCompatSchema),\n\tauthHeader: Type.Optional(Type.Boolean()),\n\tmodels: Type.Optional(Type.Array(ModelDefinitionSchema)),\n\tmodelOverrides: Type.Optional(Type.Record(Type.String(), ModelOverrideSchema)),\n});\n\nconst RoleDefinitionSchema = Type.Object({\n\t/** Ordered, non-empty list of canonical \"provider/modelId\" candidates. */\n\tmodels: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),\n});\n\nconst ModelsConfigSchema = Type.Object({\n\tproviders: Type.Record(Type.String(), ProviderConfigSchema),\n\t/** Additive, credential-blind role -> ordered model-candidate mapping. */\n\troles: Type.Optional(Type.Record(Type.String(), RoleDefinitionSchema)),\n});\nconst validateModelsConfig = Compile(ModelsConfigSchema);\n\nexport type ModelsJsonModel = Static<typeof ModelDefinitionSchema>;\nexport type ModelsJsonModelOverride = Static<typeof ModelOverrideSchema>;\nexport type ModelsJsonProvider = Static<typeof ProviderConfigSchema>;\nexport type ModelsJsonRoleDefinition = Static<typeof RoleDefinitionSchema>;\ntype ModelsJson = Static<typeof ModelsConfigSchema>;\n\nfunction formatValidationPath(error: TLocalizedValidationError): string {\n\tif (error.keyword === \"required\") {\n\t\tconst requiredProperties = (error.params as { requiredProperties?: string[] }).requiredProperties;\n\t\tconst requiredProperty = requiredProperties?.[0];\n\t\tif (requiredProperty) {\n\t\t\tconst basePath = error.instancePath.replace(/^\\//, \"\").replace(/\\//g, \".\");\n\t\t\treturn basePath ? `${basePath}.${requiredProperty}` : requiredProperty;\n\t\t}\n\t}\n\tconst path = error.instancePath.replace(/^\\//, \"\").replace(/\\//g, \".\");\n\treturn path || \"root\";\n}\n\nfunction deepFreeze<T>(value: T): T {\n\tif (typeof value !== \"object\" || value === null || Object.isFrozen(value)) return value;\n\tfor (const child of Object.values(value)) deepFreeze(child);\n\treturn Object.freeze(value);\n}\n\n/** One immutable load of models.json. */\nexport class ModelConfig {\n\tprivate readonly providers: ReadonlyMap<string, ModelsJsonProvider>;\n\tprivate readonly roles: ReadonlyMap<string, readonly string[]>;\n\tprivate readonly error: string | undefined;\n\n\tprivate constructor(\n\t\tproviders: ReadonlyMap<string, ModelsJsonProvider>,\n\t\troles: ReadonlyMap<string, readonly string[]> = new Map(),\n\t\terror?: string,\n\t) {\n\t\tthis.providers = providers;\n\t\tthis.roles = roles;\n\t\tthis.error = error;\n\t}\n\n\tstatic async load(modelsJsonPath: string | undefined): Promise<ModelConfig> {\n\t\tif (!modelsJsonPath) return new ModelConfig(new Map());\n\t\tconst path = normalizePath(modelsJsonPath);\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = await readFile(path, \"utf-8\");\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return new ModelConfig(new Map());\n\t\t\treturn new ModelConfig(\n\t\t\t\tnew Map(),\n\t\t\t\tnew Map(),\n\t\t\t\t`Failed to load models.json: ${error instanceof Error ? error.message : error}\\n\\nFile: ${path}`,\n\t\t\t);\n\t\t}\n\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(stripJsonComments(stripBom(content)));\n\t\t} catch (error) {\n\t\t\treturn new ModelConfig(\n\t\t\t\tnew Map(),\n\t\t\t\tnew Map(),\n\t\t\t\t`Failed to parse models.json: ${error instanceof Error ? error.message : error}\\n\\nFile: ${path}`,\n\t\t\t);\n\t\t}\n\n\t\tif (!validateModelsConfig.Check(parsed)) {\n\t\t\tconst errors =\n\t\t\t\tvalidateModelsConfig\n\t\t\t\t\t.Errors(parsed)\n\t\t\t\t\t.map((error) => `  - ${formatValidationPath(error)}: ${error.message}`)\n\t\t\t\t\t.join(\"\\n\") || \"Unknown schema error\";\n\t\t\treturn new ModelConfig(new Map(), new Map(), `Invalid models.json schema:\\n${errors}\\n\\nFile: ${path}`);\n\t\t}\n\n\t\tconst config = parsed as ModelsJson;\n\t\tconst providers = new Map<string, ModelsJsonProvider>();\n\t\tfor (const [providerId, provider] of Object.entries(config.providers)) {\n\t\t\tproviders.set(providerId, deepFreeze(structuredClone(provider)));\n\t\t}\n\t\tconst roles = new Map<string, readonly string[]>();\n\t\tfor (const [roleName, role] of Object.entries(config.roles ?? {})) {\n\t\t\troles.set(roleName, Object.freeze([...role.models]));\n\t\t}\n\t\treturn new ModelConfig(providers, roles);\n\t}\n\n\tgetProvider(providerId: string): ModelsJsonProvider | undefined {\n\t\treturn this.providers.get(providerId);\n\t}\n\n\tgetProviderIds(): readonly string[] {\n\t\treturn [...this.providers.keys()];\n\t}\n\n\t/** Additive role -> ordered \"provider/modelId\" candidate references, unresolved. */\n\tgetRoles(): ReadonlyMap<string, readonly string[]> {\n\t\treturn this.roles;\n\t}\n\n\tgetError(): string | undefined {\n\t\treturn this.error;\n\t}\n}\n"]}

package/dist/core/model-config.js

@@ -4,6 +4,7 @@ import { Type } from "typebox";
 import { Compile } from "typebox/compile";
 import { stripJsonComments } from "../utils/json.js";
 import { normalizePath } from "../utils/paths.js";
+import { stripBom } from "../utils/text.js";
 const PercentileCutoffsSchema = Type.Object({
     p50: Type.Optional(Type.Number()),
     p75: Type.Optional(Type.Number()),
@@ -62,6 +63,7 @@ const OpenAICompletionsCompatSchema = Type.Object({
     supportsDeveloperRole: Type.Optional(Type.Boolean()),
     supportsReasoningEffort: Type.Optional(Type.Boolean()),
     supportsUsageInStreaming: Type.Optional(Type.Boolean()),
+    supportsFinishReason: Type.Optional(Type.Boolean()),
     maxTokensField: Type.Optional(Type.Union([Type.Literal("max_completion_tokens"), Type.Literal("max_tokens")])),
     requiresToolResultName: Type.Optional(Type.Boolean()),
     requiresAssistantAfterToolResult: Type.Optional(Type.Boolean()),
@@ -98,6 +100,7 @@ const OpenAIResponsesCompatSchema = Type.Object({
     supportsLongCacheRetention: Type.Optional(Type.Boolean()),
     supportsStrictMode: Type.Optional(Type.Boolean()),
     supportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),
+    supportsAdditionalTools: Type.Optional(Type.Boolean()),
     supportsToolSearch: Type.Optional(Type.Boolean()),
 });
 const AnthropicMessagesCompatSchema = Type.Object({
@@ -175,8 +178,14 @@ const ProviderConfigSchema = Type.Object({
     models: Type.Optional(Type.Array(ModelDefinitionSchema)),
     modelOverrides: Type.Optional(Type.Record(Type.String(), ModelOverrideSchema)),
 });
+const RoleDefinitionSchema = Type.Object({
+    /** Ordered, non-empty list of canonical "provider/modelId" candidates. */
+    models: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+});
 const ModelsConfigSchema = Type.Object({
     providers: Type.Record(Type.String(), ProviderConfigSchema),
+    /** Additive, credential-blind role -> ordered model-candidate mapping. */
+    roles: Type.Optional(Type.Record(Type.String(), RoleDefinitionSchema)),
 });
 const validateModelsConfig = Compile(ModelsConfigSchema);
 function formatValidationPath(error) {
@@ -201,9 +210,11 @@ function deepFreeze(value) {
 /** One immutable load of models.json. */
 export class ModelConfig {
     providers;
+    roles;
     error;
-    constructor(providers, error) {
+    constructor(providers, roles = new Map(), error) {
         this.providers = providers;
+        this.roles = roles;
         this.error = error;
     }
     static async load(modelsJsonPath) {
@@ -217,28 +228,32 @@ export class ModelConfig {
         catch (error) {
             if (error.code === "ENOENT")
                 return new ModelConfig(new Map());
-            return new ModelConfig(new Map(), `Failed to load models.json: ${error instanceof Error ? error.message : error}\n\nFile: ${path}`);
+            return new ModelConfig(new Map(), new Map(), `Failed to load models.json: ${error instanceof Error ? error.message : error}\n\nFile: ${path}`);
         }
         let parsed;
         try {
-            parsed = JSON.parse(stripJsonComments(content));
+            parsed = JSON.parse(stripJsonComments(stripBom(content)));
         }
         catch (error) {
-            return new ModelConfig(new Map(), `Failed to parse models.json: ${error instanceof Error ? error.message : error}\n\nFile: ${path}`);
+            return new ModelConfig(new Map(), new Map(), `Failed to parse models.json: ${error instanceof Error ? error.message : error}\n\nFile: ${path}`);
         }
         if (!validateModelsConfig.Check(parsed)) {
             const errors = validateModelsConfig
                 .Errors(parsed)
                 .map((error) => `  - ${formatValidationPath(error)}: ${error.message}`)
                 .join("\n") || "Unknown schema error";
-            return new ModelConfig(new Map(), `Invalid models.json schema:\n${errors}\n\nFile: ${path}`);
+            return new ModelConfig(new Map(), new Map(), `Invalid models.json schema:\n${errors}\n\nFile: ${path}`);
         }
         const config = parsed;
         const providers = new Map();
         for (const [providerId, provider] of Object.entries(config.providers)) {
             providers.set(providerId, deepFreeze(structuredClone(provider)));
         }
-        return new ModelConfig(providers);
+        const roles = new Map();
+        for (const [roleName, role] of Object.entries(config.roles ?? {})) {
+            roles.set(roleName, Object.freeze([...role.models]));
+        }
+        return new ModelConfig(providers, roles);
     }
     getProvider(providerId) {
         return this.providers.get(providerId);
@@ -246,6 +261,10 @@ export class ModelConfig {
     getProviderIds() {
         return [...this.providers.keys()];
     }
+    /** Additive role -> ordered "provider/modelId" candidate references, unresolved. */
+    getRoles() {
+        return this.roles;
+    }
     getError() {
         return this.error;
     }