@nylorun/runtime 0.13.0-beta → 0.14.0-beta

package/dist/host/http.js

@@ -1,3 +1,5 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { jsonResponse } from "../api/http/respond.js";
 import { HOST_PROTOCOL, } from "@nylorun/core/compatibility";
 export const OPAQUE_NOT_FOUND = {
     status: "rejected",
@@ -19,23 +21,25 @@ export class HostListenError extends Error {
 export function sendJson(response, status, body) {
     const payload = JSON.stringify(body);
     // No Access-Control-* headers (D§11).
-    response.writeHead(status, {
-        "content-type": "application/json",
-        "content-length": Buffer.byteLength(payload),
-    });
+    response.writeHead(status, jsonHeaders(payload));
     response.end(payload);
 }
-export function sendRejected(response, status, code, message, details) {
+/** `sendJson` as a Response, byte for byte (with any extra headers): the Host's answers. */
+export { jsonResponse };
+function jsonHeaders(payload) {
+    return {
+        "content-type": "application/json",
+        "content-length": String(Buffer.byteLength(payload)),
+    };
+}
+function rejection(code, message, details) {
     const body = { status: "rejected", code, message };
     if (details !== undefined)
         body.details = details;
-    sendJson(response, status, body);
+    return body;
 }
-export function sendOpaqueNotFound(response) {
-    sendJson(response, 404, OPAQUE_NOT_FOUND);
-}
-export function sendProtocolRejected(response, protocol = HOST_PROTOCOL) {
-    sendJson(response, 426, {
+function protocolRejection(protocol) {
+    return {
         status: "rejected",
         code: "protocol_unsupported",
         protocol: {
@@ -43,7 +47,19 @@ export function sendProtocolRejected(response, protocol = HOST_PROTOCOL) {
             max: protocol.max,
             features: [...protocol.features],
         },
-    });
+    };
+}
+export function sendRejected(response, status, code, message, details) {
+    sendJson(response, status, rejection(code, message, details));
+}
+export function rejectedResponse(status, code, message, details) {
+    return jsonResponse(status, rejection(code, message, details));
+}
+export function opaqueNotFoundResponse() {
+    return jsonResponse(404, OPAQUE_NOT_FOUND);
+}
+export function protocolRejectedResponse(protocol = HOST_PROTOCOL) {
+    return jsonResponse(426, protocolRejection(protocol));
 }
 /**
  * D§11 Host allowlist: loopback forms with the listening port, plus the
@@ -95,6 +111,13 @@ export function requestHasBody(request) {
     const n = Number(raw);
     return Number.isFinite(n) && n > 0;
 }
+/** `/health` and `/ready` are polled; the request log leaves them out. */
+export function pathnameIsLogged(rawUrl) {
+    if (!rawUrl)
+        return true;
+    const pathname = new URL(rawUrl, "http://runtime.local").pathname;
+    return pathname !== "/health" && pathname !== "/ready";
+}
 /** Redact path parameters after `/v1/sessions/` for Host logs. */
 export function redactRoutePath(pathname) {
     const parts = pathname.split("/");
@@ -104,34 +127,52 @@ export function redactRoutePath(pathname) {
     }
     return pathname;
 }
+/** Constant-time comparison of SHA-256 digests of the presented and stored admin keys. */
+export function adminKeyMatches(presented, adminKey) {
+    if (presented === undefined)
+        return false;
+    const a = createHash("sha256").update(presented, "utf8").digest();
+    const b = createHash("sha256").update(adminKey, "utf8").digest();
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** A request header's first value. */
+export function headerValue(incoming, name) {
+    const raw = incoming.headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0];
+    return raw;
+}
 export function readBearer(authorization) {
     if (!authorization)
         return undefined;
     const match = /^Bearer\s+(\S+)/i.exec(authorization.trim());
     return match?.[1];
 }
+/** A JSON request body, capped at `limit` bytes (413); `undefined` when there is none. */
 export async function readJsonBody(request, limit = 1024 * 1024) {
+    if (request.body === null)
+        return undefined;
     const chunks = [];
     let size = 0;
-    for await (const chunk of request) {
-        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buf.length;
+    const reader = request.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
         if (size > limit) {
-            const error = new Error("Request too large");
-            error.status = 413;
-            throw error;
+            await reader.cancel();
+            throw Object.assign(new Error("Request too large"), { status: 413 });
         }
-        chunks.push(buf);
+        chunks.push(value);
     }
-    if (chunks.length === 0)
+    if (size === 0)
         return undefined;
     try {
         return JSON.parse(Buffer.concat(chunks).toString("utf8"));
     }
     catch {
-        const error = new Error("Invalid JSON");
-        error.status = 400;
-        throw error;
+        throw Object.assign(new Error("Invalid JSON"), { status: 400 });
     }
 }
 export function isLoopbackHost(host) {

package/dist/host/main.js

@@ -8,8 +8,11 @@
  * Composition: `createInfra` builds the Postgres pool, Durable Session
  * Execution and Durable Streams from the endpoints; `createHostExecution`
  * shares one execution across the Tenants; the Tenant store is Postgres
- * (`NYLORUN_DATABASE_URL`, required); `/ready` reports the infrastructure
- * checks. See the startup order in `main()`. Tests compose a Host without this
+ * (`NYLORUN_DATABASE_URL`, required), with the shared record of session events
+ * (`nylorun_streams`, migrated here); with S2, an `api` or `all` process runs
+ * the stream relay, which feeds every Tenant's streams from the record over
+ * logical replication (one process at a time holds the slot); `/ready` reports
+ * the infrastructure checks. See the startup order in `main()`. Tests compose a Host without this
  * entry, with `createHost` and an injected Tenant module.
  */
 import { readFileSync, mkdirSync, existsSync } from "node:fs";
@@ -21,6 +24,10 @@ import { createTenantModule } from "../tenant/module.js";
 import { createPostgresTenantStore } from "../tenant/store-pg.js";
 import { openTenantRuntime } from "../tenant/runtime.js";
 import { createTenantStreams, deleteTenantStreams } from "../tenant/streams.js";
+import { createPgoutputSource } from "../adapters/replication/pgoutput.js";
+import { assertLogicalReplication, migrateStreamsSchema, } from "../store/postgres/migrations/shared/index.js";
+import { createPostgresRecordReader } from "../store/postgres/record.js";
+import { createStreamRelay } from "../streams/relay/core.js";
 import { configForFactory } from "./config-for.js";
 import { createHost } from "./create-host.js";
 import { createHostExecution } from "./execution.js";
@@ -46,6 +53,11 @@ function resolveHostRoot() {
     const root = fromEnv && fromEnv.length > 0 ? fromEnv : resolve(homedir(), ".nylorun");
     return resolve(root);
 }
+/** The slot's lag in WAL bytes, when the source can tell. */
+async function lagOf(source) {
+    const lagBytes = await source.lag?.().catch(() => undefined);
+    return lagBytes === undefined ? {} : { lagBytes };
+}
 export async function main() {
     const stack = parseStackConfig(process.env, process.argv.slice(2));
     const hostRoot = resolveHostRoot();
@@ -89,6 +101,7 @@ export async function main() {
         hostConfig: config,
         logger,
         baseline,
+        ...(stack.delivery ? { delivery: stack.delivery } : {}),
     });
     // One Durable Session Execution for every Tenant this process opens: Restate
     // when its endpoints are set, else the in-process memory execution. An
@@ -103,6 +116,28 @@ export async function main() {
     // them (a local Host only) each Tenant keeps in-process streams, whose history
     // does not survive a restart.
     const streams = infra.streams;
+    let relayLag;
+    // The record of session events is shared by every Tenant; it exists before any opens.
+    await migrateStreamsSchema(database);
+    // With S2, the stream relay feeds every Tenant's streams from the record. Every api or all
+    // process runs one; the replication slot lets exactly one be active. Without S2, each
+    // Tenant relays its own commits to its in-process streams.
+    let relay;
+    if (streams && stack.role !== "worker") {
+        await assertLogicalReplication(database);
+        const source = createPgoutputSource({
+            connectionString: stack.endpoints.databaseUrl,
+            log: (message, fields) => logger.info(message, fields),
+        });
+        relay = createStreamRelay({
+            source,
+            record: createPostgresRecordReader(database),
+            streams,
+            log: (message, fields) => logger.info(message, fields),
+        });
+        const status = relay.status;
+        relayLag = async () => ({ ...status(), ...(await lagOf(source)) });
+    }
     const store = createPostgresTenantStore({
         hostRoot,
         sql: database,
@@ -110,13 +145,14 @@ export async function main() {
         logger,
         openRuntime: (tenantConfig, opened) => openTenantRuntime(tenantConfig, {
             execution: hostExecution.tenantExecution,
-            ...(streams ? { streams } : {}),
+            ...(streams ? { streams, hostRelay: true } : {}),
             ...opened,
         }),
     });
     const module = createTenantModule({
         store,
         logger,
+        ...(relayLag ? { relayStatus: relayLag } : {}),
         // A new Tenant's basin is created with it (opening it repairs a failure);
         // a deleted Tenant's sweep stops re-arming and its basin goes.
         ...(streams
@@ -140,11 +176,24 @@ export async function main() {
         coreVersion: coreVersion(),
         ...(stack.listen ? { listen: stack.listen } : {}),
         ...(stack.publicUrl ? { publicUrl: stack.publicUrl } : {}),
+        // Container mode (the local stack) allows browsers unless told not to; a Host started
+        // from host.json only when it says so. Without publishable keys nothing is reachable.
+        browserAccess: stack.browserAccess ?? (stack.listen ? true : config.browserAccess === true),
+        // The Admin API on its own listener: from the container environment, or from host.json
+        // (loopback, on the same host) when the Host runs outside a container.
+        ...(stack.operator
+            ? { operator: stack.operator }
+            : !stack.listen && typeof config.adminPort === "number"
+                ? { operator: { host: config.host, port: config.adminPort } }
+                : {}),
         ...(infra.readiness ? { readiness: infra.readiness } : {}),
         // SIGTERM and POST /v1/admin/host/shutdown both close the Host this way:
         // stop the Worker, close the Tenants, then end the infrastructure clients.
         shutdown: {
-            beforeTenants: () => hostExecution.stop(),
+            beforeTenants: async () => {
+                await hostExecution.stop();
+                await relay?.stop();
+            },
             afterTenants: () => infra.close(),
         },
     };
@@ -159,10 +208,12 @@ export async function main() {
     // sweep is re-armed, which recovers wakes lost with Restate's state (§14.8).
     try {
         await hostExecution.start();
+        relay?.start();
         await host.listen();
     }
     catch (error) {
         await hostExecution.stop().catch(() => undefined);
+        await relay?.stop().catch(() => undefined);
         await infra.close();
         if (error instanceof HostListenError) {
             logger.error("listen_failed", {

package/dist/host/stack-config.d.ts

@@ -54,6 +54,26 @@ export interface StackConfig {
      * means nothing outside the container.
      */
     publicUrl?: string;
+    /**
+     * `NYLORUN_BROWSER_ACCESS` (`on` or `off`): whether browser requests may reach Tenant
+     * routes. Absent means the Host's default (on in container mode).
+     */
+    browserAccess?: boolean;
+    /**
+     * The operator listener in container mode (`NYLORUN_ADMIN_LISTEN_PORT`, `…_HOST`,
+     * `…_ALLOWED_HOSTS`). Absent: one listener serves the Admin API and the Tenant API.
+     */
+    operator?: ContainerListen;
+    /**
+     * How the Runtime may call Action endpoints: `NYLORUN_ENDPOINT_LOOPBACK=docker-host` (the local
+     * stack: `localhost` means the machine that runs Docker), `NYLORUN_ENDPOINT_PRIVATE`
+     * (`allow` or `refuse`) and `NYLORUN_ENDPOINT_HTTP` (`allow` or `refuse`).
+     */
+    delivery?: {
+        loopback?: "docker-host";
+        privateAddresses?: "allow" | "refuse";
+        allowHttp?: boolean;
+    };
 }
 export declare class StackConfigError extends Error {
     constructor(message: string);

package/dist/host/stack-config.js

@@ -124,6 +124,30 @@ function parseListen(env) {
     const allowedHosts = [...new Set([...explicit, ...loopbackForms(port)])];
     return { host, port, allowedHosts };
 }
+function parseAdminListen(env) {
+    const rawPort = read(env, "NYLORUN_ADMIN_LISTEN_PORT");
+    const rawHost = read(env, "NYLORUN_ADMIN_LISTEN_HOST");
+    const rawAllowed = read(env, "NYLORUN_ADMIN_ALLOWED_HOSTS");
+    if (rawPort === undefined) {
+        if (rawHost !== undefined || rawAllowed !== undefined)
+            throw new StackConfigError("NYLORUN_ADMIN_LISTEN_PORT is required with NYLORUN_ADMIN_LISTEN_HOST or NYLORUN_ADMIN_ALLOWED_HOSTS");
+        return undefined;
+    }
+    const host = rawHost ?? DEFAULT_CONTAINER_LISTEN_HOST;
+    if (/\s|\//.test(host))
+        throw new StackConfigError(`NYLORUN_ADMIN_LISTEN_HOST is not an address: ${host}`);
+    const port = parsePort("NYLORUN_ADMIN_LISTEN_PORT", rawPort);
+    const explicit = rawAllowed === undefined
+        ? []
+        : rawAllowed
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== "")
+            .map((entry) => normalizeAllowedHost("NYLORUN_ADMIN_ALLOWED_HOSTS", entry));
+    if (explicit.length === 0 && !isLoopbackAddress(host))
+        throw new StackConfigError(`NYLORUN_ADMIN_ALLOWED_HOSTS is required when NYLORUN_ADMIN_LISTEN_HOST is ${host}: list the Host headers operators send, e.g. runtime:${port},localhost:<published port>`);
+    return { host, port, allowedHosts: [...new Set([...explicit, ...loopbackForms(port)])] };
+}
 const IDENTITY_KEY = /^publickeyv1_[1-9A-HJ-NP-Za-km-z]{32,64}$/;
 function parseIdentityKeys(env) {
     const raw = read(env, "NYLORUN_RESTATE_IDENTITY_KEY");
@@ -142,6 +166,9 @@ function parseIdentityKeys(env) {
 export function parseStackConfig(env, argv) {
     const role = parseRole(argv);
     const listen = parseListen(env);
+    const operator = parseAdminListen(env);
+    if (operator && listen && operator.port === listen.port)
+        throw new StackConfigError("NYLORUN_ADMIN_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT");
     const http = ["http:", "https:"];
     const endpoints = {};
     const databaseUrl = parseUrl(env, "NYLORUN_DATABASE_URL", [
@@ -177,11 +204,39 @@ export function parseStackConfig(env, argv) {
     if (restateIdentityKeys)
         endpoints.restateIdentityKeys = restateIdentityKeys;
     const publicUrl = parseUrl(env, "NYLORUN_PUBLIC_URL", http)?.replace(/\/+$/, "");
+    const rawBrowser = read(env, "NYLORUN_BROWSER_ACCESS");
+    if (rawBrowser !== undefined && rawBrowser !== "on" && rawBrowser !== "off")
+        throw new StackConfigError(`NYLORUN_BROWSER_ACCESS must be on or off, not ${rawBrowser}`);
+    const delivery = parseDelivery(env);
     return {
         role,
         ...(listen ? { listen } : {}),
         endpoints,
         ...(publicUrl ? { publicUrl } : {}),
+        ...(rawBrowser === undefined ? {} : { browserAccess: rawBrowser === "on" }),
+        ...(operator ? { operator } : {}),
+        ...(delivery ? { delivery } : {}),
+    };
+}
+/** `StackConfig.delivery` from `NYLORUN_ENDPOINT_*`, or `undefined` when none is set. */
+function parseDelivery(env) {
+    const loopback = read(env, "NYLORUN_ENDPOINT_LOOPBACK");
+    if (loopback !== undefined && loopback !== "docker-host")
+        throw new StackConfigError(`NYLORUN_ENDPOINT_LOOPBACK must be docker-host, not ${loopback}`);
+    const choice = (name) => {
+        const value = read(env, name);
+        if (value !== undefined && value !== "allow" && value !== "refuse")
+            throw new StackConfigError(`${name} must be allow or refuse, not ${value}`);
+        return value;
+    };
+    const privateAddresses = choice("NYLORUN_ENDPOINT_PRIVATE");
+    const http = choice("NYLORUN_ENDPOINT_HTTP");
+    if (!loopback && !privateAddresses && !http)
+        return undefined;
+    return {
+        ...(loopback ? { loopback } : {}),
+        ...(privateAddresses ? { privateAddresses } : {}),
+        ...(http ? { allowHttp: http === "allow" } : {}),
     };
 }
 /** Endpoint summary for logs: which endpoints are set, never their values. */

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 } 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,11 @@ 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;
     });
     discover(input: {
         sessionId: string;
@@ -41,7 +53,13 @@ export declare class McpPool {
         manifest: AgentManifest;
         pluginRoots: Readonly<Record<string, string>>;
     }): 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;

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.
@@ -62,8 +72,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 +106,70 @@ 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);
         }
-        if (!live)
-            throw new Error(`MCP server '${input.serverName}' is not connected`);
-        return callMcpTool(live.connection.client, input.serverToolName, input.args);
+        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);
+        }
+        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({
+            const connection = await this.open({
                 server: declared.server,
                 pluginRoot: input.pluginRoots[pluginKey(declared)],
                 pluginData: join(this.options.pluginData, ...pluginKey(declared).split("/")),

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;