melchizedek-agents 1.1.0 → 1.3.0

package/dist/lib/tools/oauthTools.d.ts

@@ -51,10 +51,18 @@
  *   (`oauthCallProblem`). The client-credentials token endpoint passes the
  *   same SSRF guard as the server it serves (ALLOW_PRIVATE_OPENAPI or
  *   ALLOW_PRIVATE_MCP), and no redirect from it is followed.
+ *
+ * WHERE A CLIENT SECRET MAY GO: to the token endpoint, and, when the
+ *   operator configures a credential host allowlist
+ *   (lib/tools/credentialHosts.ts, ADR 0122), only to a host it binds the
+ *   `client_secret_env` variable to: checked at compile, when the consent
+ *   clients are built, and before each client-credentials token request,
+ *   code exchange (lib/tools/oauthConsent.ts) and refresh.
  */
 import type { OAuthProvider } from './auth.ts';
 import type { OAuthHostAllowlist } from './oauthHosts.ts';
-import type { OAuthClientConfig } from './oauthConsent.ts';
+import type { OAuthClientConfig, OAuthClientSource } from './oauthConsent.ts';
+import type { DynamicOAuthGrant } from './oauthDiscovery.ts';
 import type { ToolContext } from './tool.ts';
 /** The `oauth2` block of an `auth` (OpenAPI) or an `mcp_auth` (MCP). */
 export interface OAuth2AuthConfig {
@@ -63,8 +71,14 @@ export interface OAuth2AuthConfig {
     grant: 'authorization_code' | 'client_credentials';
     /** The provider's authorization endpoint (authorization_code only). */
     authorization_url?: string;
-    /** The provider's token endpoint. */
-    token_url: string;
+    /** The provider's token endpoint. Absent only with `client_registration: 'dynamic'`, which discovers it. */
+    token_url?: string;
+    /**
+     * `'dynamic'` (MCP servers, authorization_code only, ADR 0124): no
+     * pre-issued client. The authorization server is discovered from the MCP
+     * server and the deployment registers itself (lib/tools/oauthDiscovery.ts).
+     */
+    client_registration?: 'dynamic';
     /** The client id, written out (it is not a secret) … */
     client_id?: string;
     /** … or the environment variable holding it. */
@@ -87,7 +101,7 @@ export interface OAuthGrantUse {
     tools: string;
     oauth2: OAuth2AuthConfig;
 }
-/** An agent's declared OAuth grants, OpenAPI entries first, then its MCP server. */
+/** An agent's declared OAuth grants, OpenAPI entries first, then its MCP server, then each of its `mcp_servers` (ADR 0124). */
 export declare function agentOAuthGrants(agent: {
     name?: string;
     openapi?: Array<{
@@ -100,6 +114,12 @@ export declare function agentOAuthGrants(agent: {
     mcp_auth?: {
         oauth2?: OAuth2AuthConfig;
     };
+    mcp_servers?: Array<{
+        url?: string;
+        auth?: {
+            oauth2?: OAuth2AuthConfig;
+        };
+    }>;
 }, prefix?: string): OAuthGrantUse[];
 /** The environment variables a grant reads, by role. */
 export declare function oauthEnvNames(oauth2: OAuth2AuthConfig): string[];
@@ -149,7 +169,9 @@ export declare function clientCredentialsGrant(options: ClientCredentialsOptions
 /**
  * What a tool calls for the token of one call, naming where that call goes.
  * Throws ToolCredentialError, whose message names no value: `host_refused`
- * when the destination is not one of the provider's hosts.
+ * when the destination is not one of the provider's hosts (`allowlist`
+ * `'oauth'`), or when a client secret's token endpoint is not bound to its
+ * variable (`allowlist` `'credential'`).
  */
 export type OAuthTokenSource = (ctx: ToolContext | undefined, destination: string) => Promise<string>;
 /**
@@ -178,12 +200,24 @@ interface AgentLike {
     mcp_auth?: {
         oauth2?: OAuth2AuthConfig;
     };
+    mcp_servers?: Array<{
+        url?: string;
+        auth?: {
+            oauth2?: OAuth2AuthConfig;
+        };
+    }>;
     yaml_reference?: string;
 }
 interface SyndicateLike {
     orchestrator?: AgentLike;
     subagents?: AgentLike[];
 }
+/** The options oauthClientsFor and dynamicOAuthGrantsFor share. */
+interface ClientsForOptions {
+    env?: NodeJS.ProcessEnv;
+    load?: (ref: string) => SyndicateLike;
+    allowlist?: OAuthHostAllowlist | null;
+}
 /**
  * The OAuth clients the consent step needs for these syndicates' declared
  * authorization-code grants, by provider: pass them as
@@ -191,13 +225,19 @@ interface SyndicateLike {
  * secrets are read from the variables the YAML names. Two declarations of
  * one provider must agree on its endpoints, client and scopes, or this
  * throws: a provider's grant is one grant, whichever tool asks for it.
- * `load` reads a nested `yaml_reference:` file, when given.
+ * `load` reads a nested `yaml_reference:` file, when given. A grant with
+ * `client_registration: dynamic` has no client until it is registered: it
+ * is in `dynamicOAuthGrantsFor`, not here.
  */
-export declare function oauthClientsFor(configs: readonly SyndicateLike[], options?: {
-    env?: NodeJS.ProcessEnv;
-    load?: (ref: string) => SyndicateLike;
-    allowlist?: OAuthHostAllowlist | null;
-}): Record<string, OAuthClientConfig>;
+export declare function oauthClientsFor(configs: readonly SyndicateLike[], options?: ClientsForOptions): Record<string, OAuthClientConfig>;
+/**
+ * The dynamic grants these syndicates declare (`client_registration:
+ * dynamic`, ADR 0124), by provider, checked as oauthClientsFor checks the
+ * others (one grant per provider, the MCP server on the allowlist): each
+ * becomes a consent client through `dynamicOAuthClient`
+ * (lib/tools/oauthDiscovery.ts).
+ */
+export declare function dynamicOAuthGrantsFor(configs: readonly SyndicateLike[], options?: ClientsForOptions): Record<string, DynamicOAuthGrant>;
 /**
  * Every OAuth grant these syndicates declare, orchestrators and subagents,
  * following a nested `yaml_reference:` through `load` when given (once per
@@ -221,10 +261,11 @@ export declare function syndicateOAuthHostProblems(configs: readonly SyndicateLi
  * (`credentialStore({ providers })`, lib/tools/credentialStore.ts): an
  * expired user token is renewed at the provider's token endpoint with its
  * refresh token (RFC 6749 6) instead of asking the person again. Built from
- * `oauthClientsFor`'s clients; `allowPrivate` lets a private or loopback
+ * `oauthClientsFor`'s clients, and from `dynamicOAuthClient`'s sources (a
+ * discovered client, ADR 0124); `allowPrivate` lets a private or loopback
  * token endpoint through the guard (development).
  */
-export declare function oauthRefreshProviders(clients: Record<string, OAuthClientConfig>, options?: {
+export declare function oauthRefreshProviders(clients: Record<string, OAuthClientConfig | OAuthClientSource>, options?: {
     allowPrivate?: boolean;
     fetch?: typeof fetch;
     timeoutMs?: number;

package/dist/lib/tools/oauthTools.js

@@ -51,12 +51,20 @@
  *   (`oauthCallProblem`). The client-credentials token endpoint passes the
  *   same SSRF guard as the server it serves (ALLOW_PRIVATE_OPENAPI or
  *   ALLOW_PRIVATE_MCP), and no redirect from it is followed.
+ *
+ * WHERE A CLIENT SECRET MAY GO: to the token endpoint, and, when the
+ *   operator configures a credential host allowlist
+ *   (lib/tools/credentialHosts.ts, ADR 0122), only to a host it binds the
+ *   `client_secret_env` variable to: checked at compile, when the consent
+ *   clients are built, and before each client-credentials token request,
+ *   code exchange (lib/tools/oauthConsent.ts) and refresh.
  */
 import { blockedHostReason, checkHost } from '../net/addressGuard.js';
 import { PROVIDER_NAME, ToolCredentialError } from './auth.js';
 import { readCredentialEnv } from './credentialEnv.js';
+import { CLIENT_SECRET_ENV, clientSecretEnvOf, credentialCallProblem, credentialHostProblem } from './credentialHosts.js';
 import { oauthHostProblem, oauthHosts } from './oauthHosts.js';
-/** An agent's declared OAuth grants, OpenAPI entries first, then its MCP server. */
+/** An agent's declared OAuth grants, OpenAPI entries first, then its MCP server, then each of its `mcp_servers` (ADR 0124). */
 export function agentOAuthGrants(agent, prefix = '') {
     const name = `${prefix}${agent.name ?? ''}`;
     const out = [];
@@ -66,6 +74,10 @@ export function agentOAuthGrants(agent, prefix = '') {
     }
     if (agent.mcp_auth?.oauth2)
         out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, oauth2: agent.mcp_auth.oauth2 });
+    for (const server of agent.mcp_servers ?? []) {
+        if (server?.auth?.oauth2)
+            out.push({ agent: name, tools: `mcp ${server.url ?? ''}`, oauth2: server.auth.oauth2 });
+    }
     return out;
 }
 /** The environment variables a grant reads, by role. */
@@ -102,7 +114,9 @@ export function tokenTransportProblem(raw) {
 export function oauthGrantHostProblems(oauth2, servers, allowlist) {
     const list = allowlist === undefined ? oauthHosts() ?? null : allowlist;
     const urls = servers.map((s) => ['server', s]);
-    urls.push(['token_url', oauth2.token_url]);
+    // A dynamic grant names no endpoint: discovery checks each one it finds (lib/tools/oauthDiscovery.ts).
+    if (oauth2.token_url)
+        urls.push(['token_url', oauth2.token_url]);
     if (oauth2.authorization_url)
         urls.push(['authorization_url', oauth2.authorization_url]);
     const out = new Set();
@@ -264,7 +278,7 @@ export function oauthTokenSource(oauth2, where, server, options = {}) {
     /** The call-time check (ADR 0114): before any token is read or fetched. */
     const refuse = (destination) => {
         if (oauthCallProblem(oauth2, destination))
-            throw new ToolCredentialError('host_refused', provider);
+            throw new ToolCredentialError('host_refused', provider, 'oauth');
     };
     if (oauth2.grant === 'authorization_code') {
         return async (ctx, destination) => {
@@ -277,17 +291,25 @@ export function oauthTokenSource(oauth2, where, server, options = {}) {
     const env = options.env ?? process.env;
     if (!oauth2.client_secret_env)
         throw new Error(`${where}: a client_credentials grant needs client_secret_env`);
-    const transport = tokenTransportProblem(oauth2.token_url);
+    const tokenUrl = oauth2.token_url;
+    if (!tokenUrl)
+        throw new Error(`${where}: a client_credentials grant needs token_url`);
+    const transport = tokenTransportProblem(tokenUrl);
     if (transport)
         throw new Error(`${where}: token_url: ${transport}`);
     if (options.allowPrivate !== true) {
-        const blocked = blockedHostReason(new URL(oauth2.token_url).hostname);
+        const blocked = blockedHostReason(new URL(tokenUrl).hostname);
         if (blocked)
-            throw new Error(`${where}: refusing token endpoint ${new URL(oauth2.token_url).hostname}: ${blocked}`);
+            throw new Error(`${where}: refusing token endpoint ${new URL(tokenUrl).hostname}: ${blocked}`);
     }
+    // The client secret goes only to a host the operator binds its variable to (ADR 0122).
+    const secretEnv = oauth2.client_secret_env;
+    const unbound = credentialHostProblem(secretEnv, tokenUrl, 'token_url');
+    if (unbound)
+        throw new Error(`${where}: ${unbound}`);
     const grant = clientCredentialsGrant({
         provider,
-        tokenUrl: oauth2.token_url,
+        tokenUrl,
         clientId: oauth2.client_id ?? readCredentialEnv(oauth2.client_id_env ?? '', where, env),
         clientSecret: readCredentialEnv(oauth2.client_secret_env, where, env),
         ...(oauth2.scopes?.length ? { scopes: [...oauth2.scopes] } : {}),
@@ -296,36 +318,57 @@ export function oauthTokenSource(oauth2, where, server, options = {}) {
     });
     return async (ctx, destination) => {
         refuse(destination);
-        // The client secret goes to the token endpoint: held to the same rule.
-        refuse(oauth2.token_url);
+        // The client secret goes to the token endpoint: held to the same rule,
+        // and to the credential host allowlist (ADR 0122).
+        refuse(tokenUrl);
+        if (credentialCallProblem(secretEnv, tokenUrl))
+            throw new ToolCredentialError('host_refused', provider, 'credential');
         return grant.token(ctx?.signal);
     };
 }
-/**
- * The OAuth clients the consent step needs for these syndicates' declared
- * authorization-code grants, by provider: pass them as
- * `oauthConsent({ providers })` (lib/tools/oauthConsent.ts). Client ids and
- * secrets are read from the variables the YAML names. Two declarations of
- * one provider must agree on its endpoints, client and scopes, or this
- * throws: a provider's grant is one grant, whichever tool asks for it.
- * `load` reads a nested `yaml_reference:` file, when given.
- */
-export function oauthClientsFor(configs, options = {}) {
+/** Every declared authorization-code grant, by provider: configured clients and dynamic grants, one grant per provider. */
+function collectOAuthClients(configs, options) {
     const env = options.env ?? process.env;
     const allowlist = options.allowlist === undefined ? oauthHosts(env) ?? null : options.allowlist;
     const clients = {};
+    const dynamic = {};
     const signature = new Map();
     for (const use of syndicateOAuthGrants(configs, options.load)) {
         const o = use.oauth2;
         if (o.grant !== 'authorization_code')
             continue;
         const where = `${use.agent} · ${use.tools} · oauth2`;
+        if (o.client_registration === 'dynamic') {
+            // Discovered and registered when first needed (ADR 0124): the MCP server is all the YAML names.
+            const server = use.tools.startsWith('mcp ') && use.tools.length > 4 ? use.tools.slice(4) : '';
+            if (!server)
+                throw new Error(`${where}: client_registration: dynamic is for an MCP server's grant`);
+            const hostProblems = oauthGrantHostProblems(o, [server], allowlist);
+            if (hostProblems.length)
+                throw new Error(`${where}: ${hostProblems.join('; ')}`);
+            const sig = JSON.stringify(['dynamic', server, [...(o.scopes ?? [])].sort(), o.authorization_params ?? {}]);
+            const before = signature.get(o.provider);
+            if (before !== undefined) {
+                if (before !== sig)
+                    throw new Error(`${where}: provider "${o.provider}" is declared twice with different endpoints, client or scopes`);
+                continue;
+            }
+            signature.set(o.provider, sig);
+            dynamic[o.provider] = { provider: o.provider, server, scopes: [...(o.scopes ?? [])], ...(o.authorization_params ? { authorizationParams: { ...o.authorization_params } } : {}) };
+            continue;
+        }
         if (!o.authorization_url)
             throw new Error(`${where}: an authorization_code grant needs authorization_url`);
+        if (!o.token_url)
+            throw new Error(`${where}: an authorization_code grant needs token_url`);
         // The consent step sends the client secret, the code and later the refresh token to these endpoints (ADR 0114).
         const hostProblems = oauthGrantHostProblems(o, [], allowlist);
         if (hostProblems.length)
             throw new Error(`${where}: ${hostProblems.join('; ')}`);
+        // The client secret goes to the token endpoint: a host the operator binds its variable to (ADR 0122).
+        const secretProblem = o.client_secret_env ? credentialHostProblem(o.client_secret_env, o.token_url, 'token_url') : null;
+        if (secretProblem)
+            throw new Error(`${where}: ${secretProblem}`);
         const sig = JSON.stringify([o.authorization_url, o.token_url, o.client_id ?? null, o.client_id_env ?? null, o.client_secret_env ?? null, [...(o.scopes ?? [])].sort(), o.authorization_params ?? {}]);
         const before = signature.get(o.provider);
         if (before !== undefined) {
@@ -341,9 +384,35 @@ export function oauthClientsFor(configs, options = {}) {
             ...(o.client_secret_env ? { clientSecret: readCredentialEnv(o.client_secret_env, where, env) } : {}),
             scopes: [...(o.scopes ?? [])],
             ...(o.authorization_params ? { authorizationParams: { ...o.authorization_params } } : {}),
+            // The variable the secret came from, so the exchange and the refresh check its host at call time.
+            ...(o.client_secret_env ? { [CLIENT_SECRET_ENV]: o.client_secret_env } : {}),
         };
     }
-    return clients;
+    return { clients, dynamic };
+}
+/**
+ * The OAuth clients the consent step needs for these syndicates' declared
+ * authorization-code grants, by provider: pass them as
+ * `oauthConsent({ providers })` (lib/tools/oauthConsent.ts). Client ids and
+ * secrets are read from the variables the YAML names. Two declarations of
+ * one provider must agree on its endpoints, client and scopes, or this
+ * throws: a provider's grant is one grant, whichever tool asks for it.
+ * `load` reads a nested `yaml_reference:` file, when given. A grant with
+ * `client_registration: dynamic` has no client until it is registered: it
+ * is in `dynamicOAuthGrantsFor`, not here.
+ */
+export function oauthClientsFor(configs, options = {}) {
+    return collectOAuthClients(configs, options).clients;
+}
+/**
+ * The dynamic grants these syndicates declare (`client_registration:
+ * dynamic`, ADR 0124), by provider, checked as oauthClientsFor checks the
+ * others (one grant per provider, the MCP server on the allowlist): each
+ * becomes a consent client through `dynamicOAuthClient`
+ * (lib/tools/oauthDiscovery.ts).
+ */
+export function dynamicOAuthGrantsFor(configs, options = {}) {
+    return collectOAuthClients(configs, options).dynamic;
 }
 /**
  * Every OAuth grant these syndicates declare, orchestrators and subagents,
@@ -393,20 +462,34 @@ export function syndicateOAuthHostProblems(configs, options = {}) {
  * (`credentialStore({ providers })`, lib/tools/credentialStore.ts): an
  * expired user token is renewed at the provider's token endpoint with its
  * refresh token (RFC 6749 6) instead of asking the person again. Built from
- * `oauthClientsFor`'s clients; `allowPrivate` lets a private or loopback
+ * `oauthClientsFor`'s clients, and from `dynamicOAuthClient`'s sources (a
+ * discovered client, ADR 0124); `allowPrivate` lets a private or loopback
  * token endpoint through the guard (development).
  */
 export function oauthRefreshProviders(clients, options = {}) {
     const providers = {};
-    for (const [name, client] of Object.entries(clients)) {
+    for (const [name, entry] of Object.entries(clients)) {
         providers[name] = {
             refresh: async (refreshToken, context) => {
+                let client;
+                try {
+                    client = typeof entry === 'function' ? await entry() : entry;
+                }
+                catch {
+                    throw new ToolCredentialError('refresh_failed', name);
+                }
                 // A refresh token goes only to a token endpoint the allowlist binds to its provider (ADR 0114).
                 if (oauthCallProblem({ provider: name, grant: 'authorization_code' }, client.tokenUrl))
-                    throw new ToolCredentialError('host_refused', name);
+                    throw new ToolCredentialError('host_refused', name, 'oauth');
+                // The client secret too: only to a host the operator binds its variable to (ADR 0122).
+                const secretEnv = clientSecretEnvOf(client);
+                if (client.clientSecret && secretEnv && credentialCallProblem(secretEnv, client.tokenUrl))
+                    throw new ToolCredentialError('host_refused', name, 'credential');
                 const body = new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: client.clientId });
                 if (client.clientSecret)
                     body.set('client_secret', client.clientSecret);
+                if (client.resource)
+                    body.set('resource', client.resource);
                 return tokenRequest(client.tokenUrl, body, name, {
                     allowPrivate: options.allowPrivate === true,
                     doFetch: options.fetch ?? fetch,

package/dist/lib/tools/openapiTools.d.ts

@@ -45,6 +45,13 @@ export declare function boundResult(result: unknown): unknown;
  * an operation the spec does not have, or a server the guard refuses.
  */
 export declare function buildOpenApiOwnTools(entry: OpenApiConfig, baseDir?: string): Promise<Tool[]>;
+/**
+ * The server URLs one `openapi:` entry calls: its `base_url`, else its
+ * spec's server. Reads and parses the spec (bounded); throws as the compile
+ * would on a spec that cannot be read. For the load-time credential host
+ * check (lib/tools/credentialUses.ts, ADR 0122).
+ */
+export declare function openApiServers(entry: OpenApiConfig, baseDir?: string): string[];
 /**
  * The tools one `openapi:` entry gives an agent: buildOpenApiOwnTools' own
  * Tools, each marked so require_approval can name it by its operationId.

package/dist/lib/tools/openapiTools.js

@@ -36,6 +36,12 @@
  *     instead, fetched per call: the run's user's own (authorization_code,
  *     through `ctx.accessToken` and the consent pause) or the server's own
  *     (client_credentials), lib/tools/oauthTools.ts, ADR 0112.
+ *   - STATIC CREDENTIALS ONLY TO THEIR HOSTS. When the operator configures a
+ *     credential host allowlist (MELCHIZEDEK_CREDENTIAL_HOSTS, or
+ *     createA2AApp's credentialHosts; lib/tools/credentialHosts.ts,
+ *     ADR 0122), a `bearer_env` or `api_key` variable is sent only to a host
+ *     it binds that variable to: checked at compile (every server), and
+ *     again before each call, which is refused with nothing sent.
  *   - THE SSRF GUARD. Every server URL the tools will call must be http(s)
  *     and pass lib/net/addressGuard.ts: its literal rules at compile time
  *     (offline), and the full check with DNS before each call (a name can
@@ -67,6 +73,7 @@ import { callOperation, hostProblem } from './openapi/call.js';
 import { MAX_SPEC_BYTES, operationNamed, parseOpenApiSpec } from './openapi/parse.js';
 import { ToolCredentialError } from './auth.js';
 import { readCredentialEnv } from './credentialEnv.js';
+import { credentialCallProblem, credentialHostProblem } from './credentialHosts.js';
 import { oauthTokenSource, tokenTransportProblem } from './oauthTools.js';
 export { credentialEnvProblem } from './credentialEnv.js';
 export { namesTool, toSnake } from './openapi/parse.js';
@@ -89,11 +96,15 @@ function credentialFor(auth, spec) {
         return undefined;
     const read = (env) => readCredentialEnv(env, `openapi ${spec}`);
     if (auth.bearer_env)
-        return { kind: 'bearer', token: read(auth.bearer_env) };
+        return { credential: { kind: 'bearer', token: read(auth.bearer_env) }, env: auth.bearer_env };
     if (auth.api_key)
-        return { kind: 'api_key', in: auth.api_key.in, name: auth.api_key.name, value: read(auth.api_key.env) };
+        return { credential: { kind: 'api_key', in: auth.api_key.in, name: auth.api_key.name, value: read(auth.api_key.env) }, env: auth.api_key.env };
     return undefined;
 }
+/** The variable a static `auth` sends (bearer_env or api_key.env), or undefined. */
+function staticCredentialEnv(auth) {
+    return auth?.bearer_env ?? auth?.api_key?.env;
+}
 /**
  * Cut an API result to MAX_RESULT_CHARS, saying so. Kept for consumers of
  * this module; the tools cut with capResult (lib/tools/tool.ts).
@@ -138,11 +149,25 @@ function readSpec(specPath, source) {
  * provider and what to do, never a value (and, for a user who has not
  * granted it, the run's consent step has already asked).
  */
-function operationTool(op, credential, oauth) {
+function operationTool(op, held, oauth) {
+    const credential = held?.credential;
     const tool = {
         name: op.name,
         declaration: () => op.declaration,
         async execute(args, ctx) {
+            // The operator's credential host allowlist, again at each call (ADR 0122): the
+            // compile checked it, and it can change. Refused, nothing is sent; the
+            // message names the host, never the value.
+            if (held && credentialCallProblem(held.env, op.baseUrl)) {
+                let host = op.baseUrl;
+                try {
+                    host = new URL(op.baseUrl).hostname;
+                }
+                catch {
+                    // A server that is not a URL is named as written.
+                }
+                return { error: `${op.name} was not called: the operator's credential host allowlist does not let this API's credential be sent to ${host}` };
+            }
             let sent = credential;
             if (oauth) {
                 try {
@@ -186,12 +211,17 @@ export async function buildOpenApiOwnTools(entry, baseDir = process.cwd()) {
         picked = all.filter((o) => o.method === 'get');
     }
     const chosen = entry.base_url ? picked.map((o) => ({ ...o, baseUrl: entry.base_url })) : picked;
+    const credentialEnv = staticCredentialEnv(entry.auth);
     for (const baseUrl of new Set(chosen.map((o) => o.baseUrl))) {
         if (!baseUrl)
             throw new Error(`openapi ${entry.spec}: the spec names no server; set base_url`);
         const problem = await hostProblem(baseUrl, false);
         if (problem)
             throw new Error(`openapi ${entry.spec}: ${problem}`);
+        // A static credential goes only to a host the operator binds its variable to (ADR 0122).
+        const bound = credentialEnv ? credentialHostProblem(credentialEnv, baseUrl) : null;
+        if (bound)
+            throw new Error(`openapi ${entry.spec}: ${bound}`);
     }
     let oauth;
     if (entry.auth?.oauth2 && chosen.length) {
@@ -205,6 +235,22 @@ export async function buildOpenApiOwnTools(entry, baseDir = process.cwd()) {
     }
     return chosen.map((o) => operationTool(o, credential, oauth));
 }
+/**
+ * The server URLs one `openapi:` entry calls: its `base_url`, else its
+ * spec's server. Reads and parses the spec (bounded); throws as the compile
+ * would on a spec that cannot be read. For the load-time credential host
+ * check (lib/tools/credentialUses.ts, ADR 0122).
+ */
+export function openApiServers(entry, baseDir = process.cwd()) {
+    if (entry.base_url)
+        return [entry.base_url];
+    const specPath = resolve(baseDir, entry.spec);
+    const ext = extname(specPath).toLowerCase();
+    if (!['.yaml', '.yml', '.json'].includes(ext))
+        throw new Error(`openapi ${entry.spec}: a spec is .yaml, .yml or .json`);
+    const all = parseOpenApiSpec(readSpec(specPath, entry.spec), ext === '.json' ? 'json' : 'yaml', { source: entry.spec });
+    return [...new Set(all.map((o) => o.baseUrl).filter((u) => u !== ''))];
+}
 /**
  * The tools one `openapi:` entry gives an agent: buildOpenApiOwnTools' own
  * Tools, each marked so require_approval can name it by its operationId.

package/dist/lib/tools/taskTools.d.ts

@@ -33,7 +33,10 @@
  *     read-modify-write, not a lock. A running job's step checkpoints
  *     (ADR 0113) sit in a sidecar, <store>.checkpoints.json, keyed by id;
  *     every write of the store drops those of jobs no longer running or
- *     queued.
+ *     queued. A checkpoint above the cap (TaskBackendOptions.
+ *     checkpointMaxBytes, default 5 MiB of JSON) is not saved, on either
+ *     store: the job keeps its previous one and one line names the job id
+ *     and the sizes.
  *   - With Postgres (postgresStorage().taskQueue, migration 0009) each
  *     caller has its own list, scoped by the caller the tool call carries
  *     (the A2A server's scope key), and any number of workers claim jobs
@@ -129,6 +132,31 @@ export interface TaskBackend {
     /** The checkpoint a re-queued job left, or null. */
     loadCheckpoint?(job: OwnedTask): Promise<object | null>;
 }
+/**
+ * The largest checkpoint a backend stores by default: 5 MiB of serialized
+ * JSON (ADR 0113). A save above the cap is skipped and the job's previous
+ * checkpoint kept, so a huge run resumes from an older step boundary instead
+ * of failing or bloating the table.
+ */
+export declare const DEFAULT_CHECKPOINT_MAX_BYTES: number;
+/** The worker's variable that moves the cap, in bytes (scripts/assistant_worker.ts). */
+export declare const CHECKPOINT_MAX_BYTES_ENV = "MELCHIZEDEK_CHECKPOINT_MAX_BYTES";
+/** How a backend stores checkpoints (fileTaskBackendWith, postgresTaskBackend). */
+export interface TaskBackendOptions {
+    /** The largest checkpoint stored, in bytes of serialized JSON. Default DEFAULT_CHECKPOINT_MAX_BYTES; a value that is not a positive integer is the default. */
+    checkpointMaxBytes?: number;
+    /** Where a skipped save is reported: one line naming the job id and the sizes, never the checkpoint. Default console.warn. */
+    log?: (line: string) => void;
+}
+/** The cap a variable's value sets: a positive whole number of bytes, else the default. */
+export declare function checkpointMaxBytesSetting(raw: string | undefined): number;
+/**
+ * The checkpoint serialized once, as the backend stores it, or null when it
+ * is above the cap: then one line is logged with the job id and the sizes
+ * only (the checkpoint carries the user's text and tool results), and the
+ * caller keeps the previous checkpoint.
+ */
+export declare function checkpointJson(job: Pick<OwnedTask, 'id'>, checkpoint: object, options?: TaskBackendOptions): string | null;
 /** Records kept at most; finished ones are pruned oldest-first to make room. */
 export declare const MAX_TASKS = 500;
 /** A worker result is stored up to this length, then cut with a marker. */
@@ -154,7 +182,9 @@ export declare function finishJob(id: string, outcome: JobOutcome): void;
 export declare function applyFinish(store: TaskStore, id: string, outcome: JobOutcome): void;
 /** The interrupted-job rule for one record: back to the queue, or failed. */
 export declare function applyInterrupted(t: TaskRecord): 'requeued' | 'failed';
-/** The single-user JSON file (the default backend). */
+/** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */
+export declare function fileTaskBackendWith(options?: TaskBackendOptions): TaskBackend;
+/** The single-user JSON file (the default backend), checkpoints capped at DEFAULT_CHECKPOINT_MAX_BYTES. */
 export declare const fileTaskBackend: TaskBackend;
 /** Plugs in where tasks live (postgresStorage().taskQueue); default the JSON file. */
 export declare function setTaskBackend(backend: TaskBackend): void;