@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/keys/keys.d.ts

@@ -0,0 +1,41 @@
+import type { CreateCredentialRequest, CredentialInfo, HostModelView, PutHostModelRequest, RotateCredentialRequest, SelectHostModelRequest, SigningKeyView } from "@nylorun/core/contracts";
+import type { SessionStore } from "../store/types.js";
+import { type SigningKeys } from "../tenant/signing-keys.js";
+import type { VaultService } from "../vault/service.js";
+/** One JWT to sign: its `typ` and every claim, `iss`, `aud`, `sub`, `iat`, `exp` and `jti` included. */
+export interface SignRequest {
+    readonly typ: string;
+    readonly claims: Readonly<Record<string, unknown>>;
+}
+export interface Signed {
+    readonly token: string;
+    /** The signing key's id, the token's `kid`. */
+    readonly keyId: string;
+}
+export interface Keys {
+    createCredential(vaultId: string, body: CreateCredentialRequest): Promise<CredentialInfo>;
+    rotateCredential(vaultId: string, id: string, body: RotateCredentialRequest): Promise<CredentialInfo>;
+    putHostModel(body: PutHostModelRequest): Promise<HostModelView>;
+    selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>;
+    /** Signs with the current key, creating the Tenant's keys if it has none. */
+    sign(request: SignRequest): Promise<Signed>;
+    /** Rotates the signing keys (`SigningKeys.rotate`); 409 while the previous key may verify live tokens. */
+    rotateSigningKeys(request: {
+        maxTtlSeconds: number;
+        force: boolean;
+    }): Promise<SigningKeyView[]>;
+    /** Creates the current and standby keys when the Tenant has none. */
+    ensureSigningKeys(): Promise<void>;
+}
+/** The operations, by the name the HTTP route carries. */
+export declare const KEYS_OPERATIONS: readonly ["createCredential", "rotateCredential", "putHostModel", "selectHostModel", "sign", "rotateSigningKeys", "ensureSigningKeys"];
+export type KeysOperation = (typeof KEYS_OPERATIONS)[number];
+export interface InProcessKeysOptions {
+    readonly store: SessionStore;
+    /** Its vault key is `kek`. */
+    readonly vault: VaultService;
+    readonly signingKeys: SigningKeys;
+    /** The vault key. */
+    readonly kek: () => Buffer;
+}
+export declare function inProcessKeys(options: InProcessKeysOptions): Keys;

package/dist/keys/keys.js

@@ -0,0 +1,50 @@
+/**
+ * The keys seam (blueprint §14, F4.2): everything that needs the vault key. Vault writes that
+ * touch a secret (creating and rotating a credential, setting and selecting the host model;
+ * rotation and selection decrypt the old secret first) and all token signing (subject and
+ * delivery tokens, signing-key rotation) run here, whole, so the process that calls them never
+ * holds the key or a private signing key.
+ *
+ * Two implementations: `inProcessKeys` (embedding, the ephemeral Runtime, tests, and the gates
+ * service itself, which serves the HTTP routes with it), and `httpKeys` (`client.ts`), the
+ * runtime container's client of the `keys` service in the gateway.
+ */
+import { SignJWT } from "jose";
+import { signingKeyView } from "../tenant/signing-keys.js";
+/** The operations, by the name the HTTP route carries. */
+export const KEYS_OPERATIONS = [
+    "createCredential",
+    "rotateCredential",
+    "putHostModel",
+    "selectHostModel",
+    "sign",
+    "rotateSigningKeys",
+    "ensureSigningKeys",
+];
+export function inProcessKeys(options) {
+    const { store, vault, signingKeys, kek } = options;
+    return {
+        createCredential: (vaultId, body) => vault.createCredential(vaultId, body),
+        rotateCredential: (vaultId, id, body) => vault.rotateCredential(vaultId, id, body),
+        putHostModel: (body) => vault.putHostModel(body),
+        selectHostModel: (body) => vault.selectHostModel(body),
+        async sign(request) {
+            const key = kek();
+            const row = await store.tx((t) => signingKeys.ensure(t, key));
+            const signer = await signingKeys.privateKey(row, key);
+            const token = await new SignJWT({ ...request.claims })
+                .setProtectedHeader({ alg: "ES256", typ: request.typ, kid: signer.id })
+                .sign(signer.key);
+            return { token, keyId: signer.id };
+        },
+        async rotateSigningKeys(request) {
+            const key = kek();
+            const rows = await store.tx((t) => signingKeys.rotate(t, key, request.maxTtlSeconds, request.force));
+            return rows.map(signingKeyView);
+        },
+        async ensureSigningKeys() {
+            const key = kek();
+            await store.tx((t) => signingKeys.ensure(t, key));
+        },
+    };
+}

package/dist/mcp/connect.d.ts

@@ -2,10 +2,49 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { McpServerManifest } from "@nylorun/core/define";
 import type { AuthorizeResult } from "../vault/service.js";
 import { type McpDiagnostic, type McpToolRecord } from "./snapshot.js";
+/** Options of one MCP request. */
+export interface McpRequestOptions {
+    readonly signal?: AbortSignal;
+}
+/** Options of one tool call. */
+export interface McpCallOptions extends McpRequestOptions {
+    /**
+     * The call's effect id. A gate runs a keyed call once and keeps its outcome, so a re-send
+     * after a takeover joins it (F4.1). An in-process connection ignores it.
+     */
+    readonly key?: string;
+}
+/** A page of `tools/list`, as the MCP SDK returns it. */
+export interface McpToolPage {
+    readonly tools: readonly {
+        readonly name: string;
+        readonly description?: string;
+        readonly inputSchema?: unknown;
+        readonly outputSchema?: unknown;
+    }[];
+    readonly nextCursor?: string;
+}
+/**
+ * What the pool needs of an MCP client: the SDK `Client` over a transport of this process
+ * (`sdkClient`), or a client of the gates service that holds the real connection
+ * (`gates/tool-client.ts`).
+ */
+export interface McpClient {
+    listTools(params?: {
+        cursor?: string;
+    }, options?: McpRequestOptions): Promise<McpToolPage>;
+    /** The raw `CallToolResult`; `callMcpTool` reads it. */
+    callTool(params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }, options?: McpCallOptions): Promise<Record<string, unknown>>;
+}
 export interface LiveConnection {
-    readonly client: Client;
+    readonly client: McpClient;
     close(): Promise<void>;
 }
+/** An SDK `Client` as an `McpClient`. */
+export declare function sdkClient(client: Client): McpClient;
 export declare function openMcpServer(input: {
     server: McpServerManifest;
     authorize?: (url: string) => Promise<AuthorizeResult>;
@@ -13,15 +52,16 @@ export declare function openMcpServer(input: {
     pluginData: string;
     childEnv?: Readonly<Record<string, string>>;
 }): Promise<LiveConnection>;
-export declare function listMcpTools(client: Client, input: {
+export declare function listMcpTools(client: McpClient, input: {
     capabilityId: string;
     serverName: string;
     taken: Set<string>;
+    signal?: AbortSignal;
 }): Promise<{
     tools: McpToolRecord[];
     omitted: string[];
 }>;
-export declare function callMcpTool(client: Client, serverToolName: string, args: unknown): Promise<{
+export declare function callMcpTool(client: McpClient, serverToolName: string, args: unknown, options?: McpCallOptions): Promise<{
     kind: "completed";
     output: unknown;
 } | {

package/dist/mcp/connect.js

@@ -5,6 +5,13 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { schemaFromJSON } from "@nylorun/core/define";
 import { modelToolName, } from "./snapshot.js";
 import { prepareStdioLaunch } from "./stdio.js";
+/** An SDK `Client` as an `McpClient`. */
+export function sdkClient(client) {
+    return {
+        listTools: (params, options) => client.listTools(params, options?.signal ? { signal: options.signal } : undefined),
+        callTool: (params, options) => client.callTool(params, undefined, options?.signal ? { signal: options.signal } : undefined),
+    };
+}
 export async function openMcpServer(input) {
     if (input.server.type === "stdio") {
         const launch = prepareStdioLaunch(input.server, {
@@ -23,7 +30,7 @@ export async function openMcpServer(input) {
         transport.stderr?.on("data", () => { });
         const client = createClient();
         await client.connect(transport);
-        return { client, close: () => client.close() };
+        return { client: sdkClient(client), close: () => client.close() };
     }
     const authorize = input.authorize;
     if (!authorize)
@@ -42,14 +49,14 @@ export async function openMcpServer(input) {
         : new StreamableHTTPClientTransport(url, { fetch: fetchImpl });
     const client = createClient();
     await client.connect(transport);
-    return { client, close: () => client.close() };
+    return { client: sdkClient(client), close: () => client.close() };
 }
 export async function listMcpTools(client, input) {
     const tools = [];
     const omitted = [];
     let cursor;
     for (let page = 0; page < 100; page += 1) {
-        const listed = await client.listTools(cursor ? { cursor } : undefined);
+        const listed = await client.listTools(cursor ? { cursor } : undefined, input.signal ? { signal: input.signal } : undefined);
         for (const tool of listed.tools) {
             if (typeof tool.name !== "string" || tool.name.length === 0)
                 continue;
@@ -81,13 +88,13 @@ export async function listMcpTools(client, input) {
     }
     return { tools, omitted };
 }
-export async function callMcpTool(client, serverToolName, args) {
+export async function callMcpTool(client, serverToolName, args, options = {}) {
     const result = await client.callTool({
         name: serverToolName,
         arguments: args && typeof args === "object" && !Array.isArray(args)
             ? args
             : {},
-    });
+    }, options);
     if ("isError" in result && result.isError) {
         return {
             kind: "failed",

package/dist/mcp/pool.d.ts

@@ -1,10 +1,17 @@
 import type { AgentManifest, McpServerManifest } from "@nylorun/core/define";
 import type { AuthorizeResult } from "../vault/service.js";
-import { callMcpTool } from "./connect.js";
+import { callMcpTool, openMcpServer, type LiveConnection } from "./connect.js";
 import { type McpDiagnostic, type McpSnapshot, type McpToolRecord } from "./snapshot.js";
+/** A connection unused this long is closed by the sweep; the next call opens it again. */
+export declare const DEFAULT_MCP_IDLE_MS: number;
 export declare class McpPool {
     private readonly options;
     private readonly live;
+    /** Connections being opened by `call`, so concurrent calls share one. */
+    private readonly opening;
+    private readonly idleMs;
+    private readonly now;
+    private readonly open;
     constructor(options: {
         /** Absolute Tenant `plugin-data` directory. */
         readonly pluginData: string;
@@ -13,6 +20,18 @@ export declare class McpPool {
             url: string;
             serverName: string;
         }) => Promise<AuthorizeResult>;
+        /** Default `DEFAULT_MCP_IDLE_MS`. */
+        readonly idleMs?: number;
+        readonly now?: () => number;
+        /** Tests replace how a declared server is opened. */
+        readonly open?: typeof openMcpServer;
+        /**
+         * Opens a remote (`streamable-http` or `sse`) server somewhere else: the gates service
+         * holds the connection and its credential, and the loop never sees either (F4.1).
+         * Absent: remote servers are opened in this process, with `authorize`. Stdio servers
+         * always run here.
+         */
+        readonly openRemote?: (server: McpServerRef) => Promise<LiveConnection>;
     });
     discover(input: {
         sessionId: string;
@@ -40,13 +59,30 @@ export declare class McpPool {
         args: unknown;
         manifest: AgentManifest;
         pluginRoots: Readonly<Record<string, string>>;
+        /** The effect id: a gate runs the call once under it (F4.1). */
+        effectId?: string;
+        signal?: AbortSignal;
     }): Promise<Awaited<ReturnType<typeof callMcpTool>>>;
+    /**
+     * Closes connections unused for the idle timeout (the Tenant sweep). A session that calls
+     * one again reconnects, as after a restart; this bounds the stdio processes a Tenant keeps.
+     */
+    sweep(): Promise<void>;
     close(): Promise<void>;
+    /** Keeps the connection, or closes it when the server is already connected for the session. */
     private remember;
     private liveKey;
     private connectDeclared;
 }
-interface DeclaredServer {
+/** One declared MCP server of a session: what a gate needs to find it in the pinned manifest. */
+export interface McpServerRef {
+    readonly sessionId: string;
+    /** The agent used as a tool that declares the server; absent for the session's root agent. */
+    readonly agentId?: string;
+    readonly capabilityId: string;
+    readonly serverName: string;
+}
+export interface DeclaredServer {
     /** Absent for the session's root agent. */
     readonly agentId?: string;
     /** The manifest of the agent that declares the server. */
@@ -56,4 +92,4 @@ interface DeclaredServer {
 }
 /** Servers of the root agent, then of each agent it uses as a tool. */
 export declare function serversOf(manifest: AgentManifest): DeclaredServer[];
-export {};
+export declare function findServer(manifest: AgentManifest, agentId: string | undefined, capabilityId: string, serverName: string): DeclaredServer | undefined;

package/dist/mcp/pool.js

@@ -2,11 +2,21 @@ import { join } from "node:path";
 import { delegatesOf } from "@nylorun/core/define";
 import { callMcpTool, diagnosticFromError, listMcpTools, openMcpServer, } from "./connect.js";
 import { declaredToolNames, } from "./snapshot.js";
+/** A connection unused this long is closed by the sweep; the next call opens it again. */
+export const DEFAULT_MCP_IDLE_MS = 15 * 60_000;
 export class McpPool {
     options;
     live = new Map();
+    /** Connections being opened by `call`, so concurrent calls share one. */
+    opening = new Map();
+    idleMs;
+    now;
+    open;
     constructor(options) {
         this.options = options;
+        this.idleMs = options.idleMs ?? DEFAULT_MCP_IDLE_MS;
+        this.now = options.now ?? Date.now;
+        this.open = options.open ?? openMcpServer;
     }
     async discover(input) {
         // Each agent names its own tools, so collisions are checked per agent.
@@ -27,6 +37,7 @@ export class McpPool {
                     capabilityId: declared.capabilityId,
                     serverName: declared.server.name,
                     taken: taken.get(declared.agentId),
+                    ...(input.signal ? { signal: input.signal } : {}),
                 });
                 tools.push(...listed.tools.map((tool) => owned(declared, tool)));
                 diagnostics.push({
@@ -62,8 +73,12 @@ export class McpPool {
             if (seen.has(key))
                 continue;
             seen.add(key);
-            if (this.live.has(key))
+            const live = this.live.get(key);
+            if (live) {
+                // The advance is about to use it: not idle.
+                live.lastUsedAt = this.now();
                 continue;
+            }
             input.signal?.throwIfAborted();
             const declared = findServer(input.manifest, tool.agentId, tool.capabilityId, tool.serverName);
             if (!declared) {
@@ -92,34 +107,82 @@ export class McpPool {
             const declared = findServer(input.manifest, input.agentId, input.capabilityId, input.serverName);
             if (!declared)
                 throw new Error(`MCP server '${input.serverName}' is not declared`);
-            const opened = await this.connectDeclared(input, declared);
+            let opening = this.opening.get(key);
+            if (!opening) {
+                opening = this.connectDeclared(input, declared).finally(() => this.opening.delete(key));
+                this.opening.set(key, opening);
+            }
+            const opened = await opening;
             if (!opened.ok)
                 throw new Error(opened.diagnostic.message);
-            this.remember(input.sessionId, declared, opened.connection);
-            live = this.live.get(key);
+            live = this.remember(input.sessionId, declared, opened.connection);
+        }
+        live.active += 1;
+        try {
+            return await callMcpTool(live.connection.client, input.serverToolName, input.args, {
+                ...(input.effectId === undefined ? {} : { key: input.effectId }),
+                ...(input.signal ? { signal: input.signal } : {}),
+            });
+        }
+        finally {
+            live.active -= 1;
+            live.lastUsedAt = this.now();
+        }
+    }
+    /**
+     * Closes connections unused for the idle timeout (the Tenant sweep). A session that calls
+     * one again reconnects, as after a restart; this bounds the stdio processes a Tenant keeps.
+     */
+    async sweep() {
+        const now = this.now();
+        const idle = [];
+        for (const [key, live] of this.live) {
+            if (live.active > 0 || now - live.lastUsedAt < this.idleMs)
+                continue;
+            this.live.delete(key);
+            idle.push(live);
         }
-        if (!live)
-            throw new Error(`MCP server '${input.serverName}' is not connected`);
-        return callMcpTool(live.connection.client, input.serverToolName, input.args);
+        await Promise.all(idle.map((item) => item.connection.close().catch(() => { })));
     }
     async close() {
         const connections = [...this.live.values()];
         this.live.clear();
         await Promise.all(connections.map((item) => item.connection.close().catch(() => { })));
     }
+    /** Keeps the connection, or closes it when the server is already connected for the session. */
     remember(sessionId, declared, connection) {
-        this.live.set(this.liveKey(sessionId, declared.agentId, declared.capabilityId, declared.server.name), {
+        const key = this.liveKey(sessionId, declared.agentId, declared.capabilityId, declared.server.name);
+        const existing = this.live.get(key);
+        if (existing) {
+            if (existing.connection !== connection)
+                void connection.close().catch(() => { });
+            return existing;
+        }
+        const live = {
             capabilityId: declared.capabilityId,
             serverName: declared.server.name,
             connection,
-        });
+            lastUsedAt: this.now(),
+            active: 0,
+        };
+        this.live.set(key, live);
+        return live;
     }
     liveKey(sessionId, agentId, capabilityId, serverName) {
         return JSON.stringify([sessionId, agentId ?? null, capabilityId, serverName]);
     }
     async connectDeclared(input, declared) {
         try {
-            const connection = await openMcpServer({
+            if (declared.server.type !== "stdio" && this.options.openRemote) {
+                const connection = await this.options.openRemote({
+                    sessionId: input.sessionId,
+                    ...ownerOf(declared),
+                    capabilityId: declared.capabilityId,
+                    serverName: declared.server.name,
+                });
+                return { ok: true, connection };
+            }
+            const connection = await this.open({
                 server: declared.server,
                 pluginRoot: input.pluginRoots[pluginKey(declared)],
                 pluginData: join(this.options.pluginData, ...pluginKey(declared).split("/")),
@@ -159,7 +222,7 @@ export function serversOf(manifest) {
         add(child.manifest, child.manifest.id);
     return servers;
 }
-function findServer(manifest, agentId, capabilityId, serverName) {
+export function findServer(manifest, agentId, capabilityId, serverName) {
     return serversOf(manifest).find((item) => item.agentId === agentId &&
         item.capabilityId === capabilityId &&
         item.server.name === serverName);

package/dist/model/catalog.d.ts

@@ -1,12 +1,4 @@
-export type HostModelCatalog = {
-    providers: {
-        id: string;
-        name: string;
-        models: {
-            id: string;
-            name: string;
-        }[];
-    }[];
-};
+import type { HostModelCatalog } from "@nylorun/core/contracts";
+export type { HostModelCatalog };
 /** Public provider and model names. No credentials. */
 export declare function hostModelCatalog(): HostModelCatalog;

package/dist/model/classify.d.ts

@@ -0,0 +1,13 @@
+import { type AssistantMessage } from "@earendil-works/pi-ai";
+import type { ModelFailureCode, ModelFailureOutcome } from "@nylorun/core/define";
+/**
+ * Classify a failed pi-ai response (`stopReason: "error"`) into a failure outcome
+ * (Model Calls §6.1). Context overflow is checked first, with the binding's window so
+ * silent overflow is caught too.
+ */
+export declare function classifyAssistantError(message: AssistantMessage, contextWindow?: number): ModelFailureOutcome;
+/** Classify an error a model provider threw (gateway, fixture, or a setup failure). */
+export declare function classifyThrown(error: unknown, contextWindow?: number): ModelFailureOutcome;
+export declare function failure(code: ModelFailureCode, message: string, retryable: boolean): ModelFailureOutcome;
+/** A pi-ai error message, for classifying failures that did not come from a stream. */
+export declare function errorMessage(text: string): AssistantMessage;

package/dist/model/classify.js

@@ -0,0 +1,61 @@
+import { isContextOverflow, isRetryableAssistantError, } from "@earendil-works/pi-ai";
+const RATE_LIMITED = /\b429\b|rate.?limit|too many requests/i;
+const QUOTA = /insufficient_quota|quota exceeded|out of budget|billing|usage limit/i;
+const OVERLOADED = /overloaded|\b529\b|\b503\b|service.?unavailable|high demand/i;
+const TIMEOUT = /timed? out|timeout/i;
+const CONTENT_POLICY = /content.?(policy|filter|management)|safety|flagged|moderation/i;
+const AUTH = /\b401\b|\b403\b|unauthori[sz]ed|forbidden|invalid.?api.?key|incorrect api key|authentication|not configured/i;
+/**
+ * Classify a failed pi-ai response (`stopReason: "error"`) into a failure outcome
+ * (Model Calls §6.1). Context overflow is checked first, with the binding's window so
+ * silent overflow is caught too.
+ */
+export function classifyAssistantError(message, contextWindow) {
+    const text = message.errorMessage ?? `Provider stopped: ${message.stopReason}`;
+    if (isContextOverflow(message, contextWindow))
+        return failure("context_overflow", text, false);
+    if (RATE_LIMITED.test(text))
+        return failure("rate_limited", text, !QUOTA.test(text));
+    if (QUOTA.test(text))
+        return failure("rate_limited", text, false);
+    if (OVERLOADED.test(text))
+        return failure("overloaded", text, true);
+    if (TIMEOUT.test(text))
+        return failure("timeout", text, true);
+    if (CONTENT_POLICY.test(text))
+        return failure("content_policy", text, false);
+    if (AUTH.test(text))
+        return failure("auth", text, false);
+    if (isRetryableAssistantError(message))
+        return failure("transient", text, true);
+    return failure("invalid_request", text, false);
+}
+/** Classify an error a model provider threw (gateway, fixture, or a setup failure). */
+export function classifyThrown(error, contextWindow) {
+    const text = error instanceof Error ? error.message : String(error);
+    return classifyAssistantError(errorMessage(text), contextWindow);
+}
+export function failure(code, message, retryable) {
+    return { kind: "failed", code, message, retryable };
+}
+/** A pi-ai error message, for classifying failures that did not come from a stream. */
+export function errorMessage(text) {
+    return {
+        role: "assistant",
+        content: [],
+        api: "openai-completions",
+        provider: "unknown",
+        model: "unknown",
+        usage: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: "error",
+        errorMessage: text,
+        timestamp: 0,
+    };
+}

package/dist/model/models.d.ts

@@ -1,15 +1,24 @@
-import { type CredentialStore } from "@earendil-works/pi-ai";
+import { type AuthContext, type CredentialStore } from "@earendil-works/pi-ai";
 export type Selection = Readonly<{
     provider: string;
     model: string;
     custom?: Readonly<{
         baseUrl: string;
+        /** Model Settings for the endpoint (Model Calls §7); defaults are deliberately small. */
+        contextWindow?: number;
+        maxTokens?: number;
+        reasoning?: boolean;
+        compat?: Readonly<Record<string, unknown>>;
     }>;
 }>;
+/** A custom endpoint whose window is unknown is assumed small: an early compaction beats a failed call. */
+export declare const CUSTOM_CONTEXT_WINDOW = 32768;
+export declare const CUSTOM_MAX_TOKENS = 8192;
 /**
  * Build the pi-ai model registry from explicit credentials only.
  * Ambient process environment / provider env auth is never consulted (A7, A10).
  */
 export declare function modelsFor(selection: Selection, credentials: CredentialStore, options?: {
     environment?: boolean;
+    authContext?: AuthContext;
 }): import("@earendil-works/pi-ai").MutableModels;

package/dist/model/models.js

@@ -1,6 +1,9 @@
 import { createProvider, } from "@earendil-works/pi-ai";
 import { stream, streamSimple, } from "@earendil-works/pi-ai/api/openai-completions";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+/** A custom endpoint whose window is unknown is assumed small: an early compaction beats a failed call. */
+export const CUSTOM_CONTEXT_WINDOW = 32_768;
+export const CUSTOM_MAX_TOKENS = 8_192;
 /**
  * Build the pi-ai model registry from explicit credentials only.
  * Ambient process environment / provider env auth is never consulted (A7, A10).
@@ -9,7 +12,10 @@ export function modelsFor(selection, credentials, options = {}) {
     if (options.environment) {
         throw new Error("Ambient model environment is not supported; pass credentials explicitly");
     }
-    const models = builtinModels({ credentials });
+    const models = builtinModels({
+        credentials,
+        ...(options.authContext ? { authContext: options.authContext } : {}),
+    });
     if (!selection.custom)
         return models;
     const model = {
@@ -18,11 +24,14 @@ export function modelsFor(selection, credentials, options = {}) {
         api: "openai-completions",
         provider: "custom",
         baseUrl: selection.custom.baseUrl,
-        reasoning: false,
+        reasoning: selection.custom.reasoning ?? false,
         input: ["text", "image"],
         cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: 128000,
-        maxTokens: 16384,
+        contextWindow: selection.custom.contextWindow ?? CUSTOM_CONTEXT_WINDOW,
+        maxTokens: selection.custom.maxTokens ?? CUSTOM_MAX_TOKENS,
+        ...(selection.custom.compat
+            ? { compat: { ...selection.custom.compat } }
+            : {}),
     };
     models.setProvider(createProvider({
         id: "custom",
@@ -30,8 +39,7 @@ export function modelsFor(selection, credentials, options = {}) {
         baseUrl: selection.custom.baseUrl,
         auth: {
             apiKey: {
-                label: "Custom API key",
-                schemas: [],
+                name: "Custom API key",
                 async resolve() {
                     const credential = await credentials.read("custom");
                     if (!credential || credential.type !== "api_key")

package/dist/model/pi-model.d.ts

@@ -1,4 +1,4 @@
-import type { Credential } from "@earendil-works/pi-ai";
+import { type Credential } from "@earendil-works/pi-ai";
 import type { RuntimeModelAdapter } from "../contracts.js";
 import type { RuntimeMedia } from "../adapters/media.js";
 import type { HostModelSecret } from "../vault/service.js";
@@ -6,12 +6,27 @@ export interface ModelPreview {
     readonly invocationId: string;
     readonly text: string;
 }
+/** Retry, timeout and cache settings for one model call (Model Calls §5, §6). */
+export interface ModelCallSettings {
+    /** Attempts per call, including the first. Default 3. */
+    readonly attempts?: number;
+    /** Base delay between attempts; doubles each time, with jitter. Default 2 s. */
+    readonly retryBaseDelayMs?: number;
+    /** A stream with no event for this long is aborted and retried. Default 300 s. */
+    readonly idleTimeoutMs?: number;
+    /** Whole-request timeout passed to the provider SDK. Default 600 s. */
+    readonly requestTimeoutMs?: number;
+}
 export interface PiModelOptions {
     readonly root?: string;
     readonly onPreview?: (preview: ModelPreview) => void;
     readonly media?: Pick<RuntimeMedia, "dataUrl">;
     readonly readHostModel?: () => HostModelSecret | undefined | Promise<HostModelSecret | undefined>;
     readonly writeHostCredential?: (credential: Credential) => void | Promise<void>;
+    readonly settings?: ModelCallSettings;
 }
-/** Node model adapter. Local provider configuration is read only when invoked. */
+/**
+ * Node model adapter. Local provider configuration is read only when invoked.
+ * A provider failure is returned as a failure outcome; only an abort is thrown.
+ */
 export declare function piModel(options?: PiModelOptions): RuntimeModelAdapter;