melchizedek-agents 1.1.0 → 1.3.0

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

@@ -0,0 +1,98 @@
+/**
+ * lib/tools/credentialUses.ts — every static credential variable a syndicate
+ * YAML sends somewhere, and where (ADR 0122).
+ *
+ * A YAML sends a static credential in three places: an OpenAPI entry's
+ * `auth.bearer_env` or `auth.api_key.env` (to the spec's server, or
+ * `base_url`), and an `oauth2` block's `client_secret_env` (to its
+ * `token_url`; the OpenAPI entry's or the MCP server's `mcp_auth`). The
+ * operator's credential host allowlist (lib/tools/credentialHosts.ts) is
+ * checked against them when a served syndicate loads
+ * (`syndicateCredentialHostProblems`), and the doctor and the server binary
+ * name each variable no allowlist binds (`unboundCredentialEnvs`).
+ *
+ * Names and hosts only: no value is read here.
+ */
+import type { CredentialHostAllowlist } from './credentialHosts.ts';
+/** One credential variable a YAML sends, and to what. */
+export interface CredentialUse {
+    /** The agent that holds the tools ("Parent › Child" inside a nested file). */
+    agent: string;
+    /** `openapi <spec>` or `mcp <url>`. */
+    tools: string;
+    /** The variable's name. */
+    env: string;
+    /** Where the YAML names it. */
+    role: 'bearer_env' | 'api_key' | 'client_secret_env';
+    /**
+     * The URLs its value goes to: the token endpoint for a client secret,
+     * `base_url` for an OpenAPI entry that sets one. Absent for an OpenAPI
+     * entry whose server is in its spec (read only when checked, by
+     * `syndicateCredentialHostProblems`).
+     */
+    destinations?: string[];
+    /** The OpenAPI entry, for its spec's servers. */
+    openapi?: OpenApiEntryLike;
+}
+/** The parts of an `oauth2` block read here. */
+interface OAuth2Like {
+    token_url?: string;
+    client_secret_env?: string;
+}
+/** The parts of an `openapi:` entry read here. */
+interface OpenApiEntryLike {
+    spec?: string;
+    base_url?: string;
+    auth?: {
+        bearer_env?: string;
+        api_key?: {
+            env?: string;
+        };
+        oauth2?: OAuth2Like;
+    };
+}
+interface AgentLike {
+    name?: string;
+    openapi?: OpenApiEntryLike[];
+    mcp_server_url?: string;
+    mcp_auth?: {
+        oauth2?: OAuth2Like;
+    };
+    mcp_servers?: Array<{
+        url?: string;
+        auth?: {
+            oauth2?: OAuth2Like;
+        };
+    }>;
+    yaml_reference?: string;
+}
+/** The parts of a syndicate config read here. */
+export interface SyndicateLike {
+    orchestrator?: AgentLike;
+    subagents?: AgentLike[];
+}
+/** The credential variables one agent's tools send. */
+export declare function agentCredentialUses(agent: AgentLike, prefix?: string): CredentialUse[];
+/**
+ * Every credential variable these syndicates send, orchestrators and
+ * subagents, following a nested `yaml_reference:` through `load` when given
+ * (once per file; agent names then read "Parent › Child").
+ */
+export declare function syndicateCredentialUses(configs: readonly SyndicateLike[], load?: (ref: string) => SyndicateLike): CredentialUse[];
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0122): each credential variable they send, against the operator's
+ * credential host allowlist. With none configured, nothing is refused. The
+ * A2A server checks every syndicate it loads to serve; the compile checks
+ * again, and each call once more.
+ */
+export declare function syndicateCredentialHostProblems(configs: readonly SyndicateLike[], options?: {
+    load?: (ref: string) => SyndicateLike;
+    allowlist?: CredentialHostAllowlist | null;
+}): string[];
+/**
+ * The credential variables these uses send that no allowlist binds, sorted
+ * and once each: every one of them when none is configured. Names only.
+ */
+export declare function unboundCredentialEnvs(uses: readonly CredentialUse[], allowlist: CredentialHostAllowlist | null | undefined): string[];
+export {};

package/dist/lib/tools/credentialUses.js

@@ -0,0 +1,120 @@
+/**
+ * lib/tools/credentialUses.ts — every static credential variable a syndicate
+ * YAML sends somewhere, and where (ADR 0122).
+ *
+ * A YAML sends a static credential in three places: an OpenAPI entry's
+ * `auth.bearer_env` or `auth.api_key.env` (to the spec's server, or
+ * `base_url`), and an `oauth2` block's `client_secret_env` (to its
+ * `token_url`; the OpenAPI entry's or the MCP server's `mcp_auth`). The
+ * operator's credential host allowlist (lib/tools/credentialHosts.ts) is
+ * checked against them when a served syndicate loads
+ * (`syndicateCredentialHostProblems`), and the doctor and the server binary
+ * name each variable no allowlist binds (`unboundCredentialEnvs`).
+ *
+ * Names and hosts only: no value is read here.
+ */
+import { resolve } from 'node:path';
+import { credentialHostProblem, credentialHosts } from './credentialHosts.js';
+import { openApiServers } from './openapiTools.js';
+/** The token endpoint a client secret goes to; none named yet for a grant whose endpoints are discovered (ADR 0124). */
+const tokenUrlOf = (o) => (o.token_url ? [o.token_url] : []);
+/** The credential variables one agent's tools send. */
+export function agentCredentialUses(agent, prefix = '') {
+    const name = `${prefix}${agent.name ?? ''}`;
+    const out = [];
+    for (const entry of agent.openapi ?? []) {
+        const tools = `openapi ${entry?.spec ?? ''}`;
+        const auth = entry?.auth;
+        if (!auth)
+            continue;
+        const servers = entry.base_url ? { destinations: [entry.base_url] } : {};
+        if (auth.bearer_env)
+            out.push({ agent: name, tools, env: auth.bearer_env, role: 'bearer_env', ...servers, openapi: entry });
+        if (auth.api_key?.env)
+            out.push({ agent: name, tools, env: auth.api_key.env, role: 'api_key', ...servers, openapi: entry });
+        if (auth.oauth2?.client_secret_env)
+            out.push({ agent: name, tools, env: auth.oauth2.client_secret_env, role: 'client_secret_env', destinations: tokenUrlOf(auth.oauth2) });
+    }
+    const mcp = agent.mcp_auth?.oauth2;
+    if (mcp?.client_secret_env)
+        out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, env: mcp.client_secret_env, role: 'client_secret_env', destinations: tokenUrlOf(mcp) });
+    // Each mcp_servers entry's grant (ADR 0124), as the single server's.
+    for (const server of agent.mcp_servers ?? []) {
+        const o = server?.auth?.oauth2;
+        if (o?.client_secret_env)
+            out.push({ agent: name, tools: `mcp ${server.url ?? ''}`, env: o.client_secret_env, role: 'client_secret_env', destinations: tokenUrlOf(o) });
+    }
+    return out;
+}
+/**
+ * Every credential variable these syndicates send, orchestrators and
+ * subagents, following a nested `yaml_reference:` through `load` when given
+ * (once per file; agent names then read "Parent › Child").
+ */
+export function syndicateCredentialUses(configs, load) {
+    const out = [];
+    const seen = new Set();
+    const visit = (config, prefix) => {
+        const agents = [config.orchestrator, ...(config.subagents ?? [])].filter((a) => !!a);
+        for (const agent of agents) {
+            if (agent.yaml_reference) {
+                if (!load || seen.has(agent.yaml_reference))
+                    continue;
+                seen.add(agent.yaml_reference);
+                visit(load(agent.yaml_reference), `${prefix}${agent.name ?? agent.yaml_reference} › `);
+                continue;
+            }
+            out.push(...agentCredentialUses(agent, prefix));
+        }
+    };
+    for (const config of configs)
+        visit(config, '');
+    return out;
+}
+/** The URLs a use's value goes to; an OpenAPI spec that cannot be read gives none (its compile fails on its own). */
+function destinationsOf(use) {
+    if (use.destinations)
+        return use.destinations;
+    if (!use.openapi?.spec)
+        return [];
+    try {
+        return openApiServers(use.openapi, resolve(process.cwd()));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0122): each credential variable they send, against the operator's
+ * credential host allowlist. With none configured, nothing is refused. The
+ * A2A server checks every syndicate it loads to serve; the compile checks
+ * again, and each call once more.
+ */
+export function syndicateCredentialHostProblems(configs, options = {}) {
+    const allowlist = options.allowlist === undefined ? credentialHosts() ?? null : options.allowlist;
+    if (!allowlist)
+        return [];
+    const out = new Set();
+    for (const use of syndicateCredentialUses(configs, options.load)) {
+        const role = use.role === 'client_secret_env' ? 'token_url' : 'server';
+        const where = `${use.agent} · ${use.tools} · ${use.role}`;
+        if (!Object.hasOwn(allowlist, use.env)) {
+            out.add(`${where}: ${credentialHostProblem(use.env, '', role, allowlist)}`);
+            continue;
+        }
+        for (const url of destinationsOf(use)) {
+            const problem = credentialHostProblem(use.env, url, role, allowlist);
+            if (problem)
+                out.add(`${where}: ${problem}`);
+        }
+    }
+    return [...out];
+}
+/**
+ * The credential variables these uses send that no allowlist binds, sorted
+ * and once each: every one of them when none is configured. Names only.
+ */
+export function unboundCredentialEnvs(uses, allowlist) {
+    return [...new Set(uses.map((u) => u.env))].filter((name) => !allowlist || !Object.hasOwn(allowlist, name)).sort();
+}

package/dist/lib/tools/generateImageTool.js

@@ -38,7 +38,8 @@ export const generateImageContract = defineTool({
             console.error(`[ImageTool ERROR] Initialization failed: ${err.message}`);
             throw err;
         }
-        console.log(`[ImageTool] Parameters - Prompt: "${prompt}", Style: "${style ?? 'none'}", Aspect Ratio: "${aspect_ratio ?? 'none'}", Color Palette: "${color_palette ?? 'none'}"`);
+        // Sizes and which options are set, never their values: the prompt carries the person's words.
+        console.log(`[ImageTool] Parameters - prompt ${prompt.length} chars; set: ${[style && 'style', aspect_ratio && 'aspect_ratio', color_palette && 'color_palette'].filter(Boolean).join(', ') || 'none'}`);
         const ai = new GoogleGenAI({ apiKey });
         // Build a rich prompt that bakes in the structured parameters.
         const parts = [prompt];

package/dist/lib/tools/inspectImageTool.js

@@ -46,7 +46,7 @@ export const inspectImageContract = defineTool({
         image_path: z.string().describe('Path to the saved image, e.g. "outputs/image_1234.png".'),
     }),
     execute: async ({ image_path }) => {
-        console.log(`[InspectTool] Blind inventory requested for: ${image_path}`);
+        console.log(`[InspectTool] Blind inventory requested (path ${image_path.length} chars).`);
         // Confine reads to the outputs/ directory — this tool inventories
         // generated artifacts, not the filesystem. OUTPUTS_DIR env overrides
         // the cwd default (must match generateImageTool's).

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

@@ -1,6 +1,8 @@
 import type { ToolDeclaration } from '../models/contract.ts';
 import type { RedirectPolicy } from '../net/redirects.ts';
 import type { OAuth2AuthConfig } from './oauthTools.ts';
+import { MCP_TRANSPORTS } from './mcpTransports.ts';
+import type { McpTransportKind } from './mcpTransports.ts';
 import type { Tool } from './tool.ts';
 export declare function assertSafeMcpUrl(raw: string, env?: NodeJS.ProcessEnv): Promise<URL>;
 export declare function mcpAuthHeaders(url: URL, env?: NodeJS.ProcessEnv): Record<string, string>;
@@ -23,6 +25,15 @@ export declare const mcpFetch: (input: string | URL | Request, init?: RequestIni
 export declare const MAX_MCP_DESCRIPTION_CHARS = 1000;
 /** Every tool's shared result limit (lib/tools/tool.ts). */
 export declare const MAX_MCP_RESULT_CHARS = 20000;
+export { MCP_TRANSPORTS };
+export type { McpTransportKind };
+/**
+ * True when a failed Streamable HTTP connect is the spec's signal that the
+ * server speaks only the older HTTP+SSE transport: the initialize POST
+ * answered with a 4xx (404, 405, 400 …). A 401 or 403 is the server refusing
+ * the credential, which another transport would not change.
+ */
+export declare function isSseFallbackSignal(error: unknown): boolean;
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
  * the process (its tools are called for the life of the compiled agent), and
@@ -44,10 +55,27 @@ export declare function mcpToolParameters(inputSchema: {
 } | undefined): ToolDeclaration['parameters'];
 /** How an agent reaches its MCP server: which tools it may use, and the OAuth grant the server takes. */
 export interface McpToolOptions {
-    /** `mcp_tools`: the names this agent may use. Required with an authorization_code grant. */
+    /** `mcp_tools` (or an `mcp_servers` entry's `tools`): the names this agent may use. Required with an authorization_code grant. */
     tools?: string[];
     /** `mcp_auth.oauth2` (ADR 0112). Without it, MCP_BEARER_TOKENS applies. */
     oauth2?: OAuth2AuthConfig;
+    /** `mcp_transport` (or an entry's `transport`): default `auto` (ADR 0124). */
+    transport?: McpTransportKind;
+}
+/**
+ * One entry of an agent's `mcp_servers:` list (ADR 0124): a server, the
+ * tools of it the agent may use, the grant it takes and its transport.
+ */
+export interface McpServerConfig {
+    /** A short name for the server, unique on the agent: logs and errors name it. */
+    name: string;
+    url: string;
+    /** The server's tools this agent may use, by name. Required: names across servers are refused on collision at load. */
+    tools: string[];
+    auth?: {
+        oauth2: OAuth2AuthConfig;
+    };
+    transport?: McpTransportKind;
 }
 /** Per-user connections at most per authorization-code server; the least recently used is closed first. */
 export declare const MAX_MCP_USER_CONNECTIONS = 64;

package/dist/lib/tools/mcpToolFactory.js

@@ -2,8 +2,11 @@
  * lib/tools/mcpToolFactory.ts — a remote MCP server's tools, as the
  * engine's own Tools (lib/tools/tool.ts, ADR 0062).
  *
- * An agent's `mcp_server_url:` connects here over SSE; every tool the
- * server lists becomes an own Tool whose declaration is the server's
+ * An agent's `mcp_server_url:` (or each entry of `mcp_servers:`, ADR 0124)
+ * connects here over Streamable HTTP, falling back to the legacy SSE
+ * transport when the server answers the initialize POST with the spec's
+ * fallback signal (a 4xx other than 401/403), or over the transport the YAML
+ * names. Every tool the server lists becomes an own Tool whose declaration is the server's
  * description (bounded) and input schema, and whose execute calls the
  * server and returns its text (bounded). loadMcpTools returns them;
  * createMcpTools is the name the compiler calls.
@@ -20,11 +23,13 @@
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { toContractJsonSchema } from '../models/schemaNormalize.js';
 import { checkHost } from '../net/addressGuard.js';
 import { fetchWithRedirectPolicy } from '../net/redirects.js';
 import { ToolCredentialError } from './auth.js';
 import { oauthCallProblem, oauthTokenSource } from './oauthTools.js';
+import { MCP_TRANSPORTS } from './mcpTransports.js';
 import { MAX_RESULT_CHARS } from './tool.js';
 import { toGeminiSchema } from './toolContract.js';
 // Security (SSRF): mcp_server_url can arrive from a registry-stored syndicate
@@ -116,6 +121,54 @@ export const MAX_MCP_RESULT_CHARS = MAX_RESULT_CHARS;
 const bounded = (text, max, what) => text.length <= max ? text : `${text.slice(0, max)}… [${what} cut at ${max} characters]`;
 /** Every MCP connection opened and still in use, so a shutdown can close them. */
 const openTransports = new Set();
+export { MCP_TRANSPORTS };
+/**
+ * True when a failed Streamable HTTP connect is the spec's signal that the
+ * server speaks only the older HTTP+SSE transport: the initialize POST
+ * answered with a 4xx (404, 405, 400 …). A 401 or 403 is the server refusing
+ * the credential, which another transport would not change.
+ */
+export function isSseFallbackSignal(error) {
+    if (!(error instanceof StreamableHTTPError))
+        return false;
+    const code = error.code;
+    return typeof code === 'number' && code >= 400 && code < 500 && code !== 401 && code !== 403;
+}
+/**
+ * A client connected to `url` over `kind`, every request through `fetchFn`
+ * (the redirect rule, and the credential when there is one). A transport
+ * that fails to connect is closed before the error leaves, so nothing keeps
+ * reconnecting; with `auto`, a failed Streamable HTTP attempt carrying the
+ * fallback signal is closed and the SSE transport tried once.
+ */
+async function connectMcp(url, kind, fetchFn, headers = {}) {
+    const attempt = async (which) => {
+        const requestInit = Object.keys(headers).length ? { requestInit: { headers } } : {};
+        const transport = which === 'sse' ? new SSEClientTransport(url, { ...requestInit, fetch: fetchFn }) : new StreamableHTTPClientTransport(url, { ...requestInit, fetch: fetchFn });
+        const client = new Client({ name: 'melchizedek-a2a-client', version: '1.0.0' }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            await transport.close().catch(() => { });
+            throw error;
+        }
+        openTransports.add(transport);
+        return { client, transport, kind: which };
+    };
+    if (kind === 'sse')
+        return attempt('sse');
+    if (kind === 'streamable_http')
+        return attempt('streamable_http');
+    try {
+        return await attempt('streamable_http');
+    }
+    catch (error) {
+        if (!isSseFallbackSignal(error))
+            throw error;
+        return attempt('sse');
+    }
+}
 /**
  * Close every open MCP connection. A connection otherwise lives as long as
  * the process (its tools are called for the life of the compiled agent), and
@@ -174,7 +227,7 @@ function bearerFetch(oauth2, token) {
         // message endpoint the server names), before a token is attached (ADR 0114).
         const destination = input instanceof Request ? input.url : String(input);
         if (oauthCallProblem(oauth2, destination))
-            throw new ToolCredentialError('host_refused', oauth2.provider);
+            throw new ToolCredentialError('host_refused', oauth2.provider, 'oauth');
         const headers = new Headers(init?.headers);
         headers.set('Authorization', `Bearer ${await token(destination)}`);
         return mcpFetch(input, { ...init, headers });
@@ -204,23 +257,17 @@ const userPools = new Set();
  */
 export async function loadMcpTools(mcpServerUrl, options = {}) {
     const oauth2 = options.oauth2;
+    const kind = options.transport ?? 'auto';
     if (oauth2?.grant === 'authorization_code')
-        return userGrantMcpTools(mcpServerUrl, oauth2, options.tools);
+        return userGrantMcpTools(mcpServerUrl, oauth2, options.tools, kind);
     const tokenSource = oauth2 ? oauthTokenSource(oauth2, `mcp ${mcpServerUrl}`, mcpServerUrl, { allowPrivate: process.env.ALLOW_PRIVATE_MCP === 'true' }) : undefined;
-    let transport;
+    let conn;
     try {
         const url = await assertSafeMcpUrl(mcpServerUrl);
-        transport = new SSEClientTransport(url, tokenSource
-            ? { fetch: bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)) }
-            : { requestInit: { headers: mcpAuthHeaders(url) }, fetch: mcpFetch });
-        const client = new Client({
-            name: 'melchizedek-a2a-client',
-            version: '1.0.0'
-        }, {
-            capabilities: {}
-        });
-        await client.connect(transport);
-        openTransports.add(transport);
+        conn = tokenSource
+            ? await connectMcp(url, kind, bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)))
+            : await connectMcp(url, kind, mcpFetch, mcpAuthHeaders(url));
+        const client = conn.client;
         // Fetch available tools from the MCP server
         const toolsResponse = await client.listTools();
         return toolsResponse.tools.map((tool) => {
@@ -244,16 +291,18 @@ export async function loadMcpTools(mcpServerUrl, options = {}) {
     catch (error) {
         // A token that cannot be had is reported by kind; the rest as before.
         console.warn(`[MCP] Failed to connect or load tools from ${mcpServerUrl}`, error instanceof ToolCredentialError ? error.message : error);
-        // A failed connect leaves the SSE stream's reconnect timer running; close
-        // it, or every unreachable server keeps retrying for the process's life.
-        if (transport)
-            openTransports.delete(transport);
-        await transport?.close().catch(() => { });
+        // A failed connect closed its own transport (connectMcp); a failed
+        // listing closes this one, or its stream keeps reconnecting for the
+        // process's life.
+        if (conn) {
+            openTransports.delete(conn.transport);
+            await conn.transport.close().catch(() => { });
+        }
         return [];
     }
 }
 /** The tools of a server whose calls carry each user's own OAuth token (authorization_code). */
-function userGrantMcpTools(mcpServerUrl, oauth2, names) {
+function userGrantMcpTools(mcpServerUrl, oauth2, names, kind) {
     const where = `mcp ${mcpServerUrl}`;
     if (!names?.length)
         throw new Error(`${where}: an authorization_code mcp_auth needs mcp_tools, the names this agent may use (no user's grant exists to list them at startup)`);
@@ -286,11 +335,8 @@ function userGrantMcpTools(mcpServerUrl, oauth2, names) {
         conn.holder = holder;
         conn.ready = (async () => {
             const url = await assertSafeMcpUrl(mcpServerUrl);
-            const transport = new SSEClientTransport(url, { fetch: bearerFetch(oauth2, async () => holder.token) });
+            const { client, transport } = await connectMcp(url, kind, bearerFetch(oauth2, async () => holder.token));
             conn.transport = transport;
-            const client = new Client({ name: 'melchizedek-a2a-client', version: '1.0.0' }, { capabilities: {} });
-            await client.connect(transport);
-            openTransports.add(transport);
             if (!listed) {
                 const offered = await client.listTools();
                 for (const tool of offered.tools)

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

@@ -0,0 +1,12 @@
+/**
+ * lib/tools/mcpTransports.ts — the transports an agent may name for an MCP
+ * server (ADR 0124), in a module light enough for the YAML schema to import
+ * without loading the MCP SDK.
+ *
+ * `auto` (the default) posts the initialize request over Streamable HTTP, the
+ * spec's current transport, and falls back to the legacy HTTP+SSE transport
+ * on the spec's signal (lib/tools/mcpToolFactory.ts isSseFallbackSignal);
+ * `streamable_http` and `sse` use that one transport only.
+ */
+export declare const MCP_TRANSPORTS: readonly ['auto', 'streamable_http', 'sse'];
+export type McpTransportKind = (typeof MCP_TRANSPORTS)[number];

package/dist/lib/tools/mcpTransports.js

@@ -0,0 +1,11 @@
+/**
+ * lib/tools/mcpTransports.ts — the transports an agent may name for an MCP
+ * server (ADR 0124), in a module light enough for the YAML schema to import
+ * without loading the MCP SDK.
+ *
+ * `auto` (the default) posts the initialize request over Streamable HTTP, the
+ * spec's current transport, and falls back to the legacy HTTP+SSE transport
+ * on the spec's signal (lib/tools/mcpToolFactory.ts isSseFallbackSignal);
+ * `streamable_http` and `sse` use that one transport only.
+ */
+export const MCP_TRANSPORTS = ['auto', 'streamable_http', 'sse'];

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

@@ -50,10 +50,23 @@ export interface OAuthClientConfig {
     scopes?: string[];
     /** Extra authorization parameters the provider needs (`access_type=offline`, say). Never `state`, `redirect_uri` or the PKCE pair. */
     authorizationParams?: Record<string, string>;
+    /**
+     * The protected resource the token is for (RFC 8707): sent as `resource`
+     * on the authorization request, the code exchange and each refresh. An MCP
+     * server's canonical URI, for a client registered by discovery (ADR 0124).
+     */
+    resource?: string;
 }
+/**
+ * A client found when first needed rather than configured at boot: an MCP
+ * server's authorization server, discovered and registered at
+ * (lib/tools/oauthDiscovery.ts dynamicOAuthClient, ADR 0124). Throws when
+ * it cannot be had; the next call tries again.
+ */
+export type OAuthClientSource = () => Promise<OAuthClientConfig>;
 export interface OAuthConsentOptions {
-    /** Each provider's client, by provider name (lowercase, as the credential store names it). */
-    providers: Record<string, OAuthClientConfig>;
+    /** Each provider's client, by provider name (lowercase, as the credential store names it): configured, or found when first needed. */
+    providers: Record<string, OAuthClientConfig | OAuthClientSource>;
     /**
      * The server's callback URL, exactly as registered at every provider
      * (`https://agents.example.com/oauth/callback`). The A2A server mounts the
@@ -122,7 +135,9 @@ export type ConsentErrorCode =
 /** The grant could not be stored. */
  | 'store_failed'
 /** The provider has no client configured. */
- | 'unknown_provider';
+ | 'unknown_provider'
+/** A discovered client could not be found or registered (ADR 0124). */
+ | 'registration_failed';
 /** A consent step that cannot proceed. The message names the reason, never a value. */
 export declare class ConsentError extends Error {
     readonly code: ConsentErrorCode;

package/dist/lib/tools/oauthConsent.js

@@ -38,6 +38,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { scopeHashOf } from '../observability/audit.js';
 import { PROVIDER_NAME } from './auth.js';
+import { clientSecretEnvOf, credentialCallProblem } from './credentialHosts.js';
 /**
  * Flows in this process's memory, at most `max` of them: the oldest is
  * dropped first, and an expired one whenever another is put.
@@ -84,7 +85,9 @@ export class ConsentError extends Error {
                                 ? `The authorization at ${p} could not be completed.`
                                 : code === 'store_failed'
                                     ? `The authorization at ${p} could not be saved.`
-                                    : `No OAuth client is configured for ${p}.`);
+                                    : code === 'registration_failed'
+                                        ? `The authorization at ${p} could not be set up.`
+                                        : `No OAuth client is configured for ${p}.`);
         this.name = 'ConsentError';
         this.code = code;
         if (provider !== undefined)
@@ -119,7 +122,21 @@ function checkEndpoint(value, what) {
         throw new Error(`${what} must not carry credentials.`);
     return url;
 }
-const RESERVED_PARAMS = new Set(['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope']);
+const RESERVED_PARAMS = new Set(['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope', 'resource']);
+/** A client's configuration, checked: the endpoints, the client id, the parameters. Throws, naming the provider. */
+function checkClient(name, client) {
+    checkEndpoint(client.authorizationUrl, `${name}: authorizationUrl`);
+    checkEndpoint(client.tokenUrl, `${name}: tokenUrl`);
+    if (typeof client.clientId !== 'string' || !client.clientId)
+        throw new Error(`${name}: clientId is required.`);
+    for (const key of Object.keys(client.authorizationParams ?? {})) {
+        if (RESERVED_PARAMS.has(key))
+            throw new Error(`${name}: authorizationParams may not set "${key}".`);
+    }
+    if (client.resource !== undefined)
+        checkEndpoint(client.resource, `${name}: resource`);
+    return { ...client, scopes: [...(client.scopes ?? [])] };
+}
 /** The consent manager over a credential store. Validates the configuration at once: a bad URL throws here, at boot. */
 export function oauthConsent(options) {
     const redirect = checkEndpoint(options.redirectUri, 'The OAuth redirect URI');
@@ -129,16 +146,23 @@ export function oauthConsent(options) {
     for (const [name, client] of Object.entries(options.providers)) {
         if (!PROVIDER_NAME.test(name))
             throw new Error(`OAuth provider "${name.slice(0, 64)}" must match ${PROVIDER_NAME}.`);
-        checkEndpoint(client.authorizationUrl, `${name}: authorizationUrl`);
-        checkEndpoint(client.tokenUrl, `${name}: tokenUrl`);
-        if (typeof client.clientId !== 'string' || !client.clientId)
-            throw new Error(`${name}: clientId is required.`);
-        for (const key of Object.keys(client.authorizationParams ?? {})) {
-            if (RESERVED_PARAMS.has(key))
-                throw new Error(`${name}: authorizationParams may not set "${key}".`);
-        }
-        providers.set(name, { ...client, scopes: [...(client.scopes ?? [])] });
+        // A source is checked each time it answers; a configured client here, at boot.
+        providers.set(name, typeof client === 'function' ? client : checkClient(name, client));
     }
+    /** The provider's client now, or undefined; a source that fails is a ConsentError('registration_failed'). */
+    const clientOf = async (name) => {
+        const entry = providers.get(name);
+        if (typeof entry !== 'function')
+            return entry;
+        try {
+            return checkClient(name, await entry());
+        }
+        catch (err) {
+            // A discovery refusal names roles and hosts, never a value (lib/tools/oauthDiscovery.ts); anything else is named by kind only.
+            console.warn(`[OAuth] ${name}: the client could not be set up: ${err instanceof Error && err.name === 'OAuthDiscoveryError' ? err.message : err instanceof Error ? err.name : 'unknown error'}`);
+            throw new ConsentError('registration_failed', name);
+        }
+    };
     const states = options.states ?? memoryConsentStates({ ...(options.now ? { now: options.now } : {}) });
     const ttlMs = options.ttlMs ?? 10 * 60_000;
     const now = options.now ?? Date.now;
@@ -192,8 +216,16 @@ export function oauthConsent(options) {
             client_id: client.clientId,
             code_verifier: flow.codeVerifier,
         });
-        if (client.clientSecret)
+        if (client.resource)
+            body.set('resource', client.resource);
+        if (client.clientSecret) {
+            // The secret goes only to a host the operator binds its variable to (ADR 0122), checked now:
+            // the allowlist can change after boot. Refused, nothing is sent.
+            const secretEnv = clientSecretEnvOf(client);
+            if (secretEnv && credentialCallProblem(secretEnv, client.tokenUrl))
+                throw new ConsentError('exchange_failed', flow.provider);
             body.set('client_secret', client.clientSecret);
+        }
         let json;
         try {
             const res = await doFetch(client.tokenUrl, {
@@ -231,9 +263,9 @@ export function oauthConsent(options) {
         redirectUri: options.redirectUri,
         has: (provider) => typeof provider === 'string' && providers.has(provider),
         async begin(binding) {
-            const client = providers.get(binding.provider);
-            if (!client)
+            if (!providers.has(binding.provider))
                 throw new ConsentError('unknown_provider', PROVIDER_NAME.test(binding.provider) ? binding.provider : undefined);
+            const client = (await clientOf(binding.provider));
             for (const field of ['appName', 'userId', 'sessionId', 'functionCallId']) {
                 if (typeof binding[field] !== 'string' || !binding[field])
                     throw new Error(`A consent flow needs the paused call's ${field}.`);
@@ -262,6 +294,8 @@ export function oauthConsent(options) {
             url.searchParams.set('state', state);
             url.searchParams.set('code_challenge', s256Challenge(codeVerifier));
             url.searchParams.set('code_challenge_method', 'S256');
+            if (client.resource)
+                url.searchParams.set('resource', client.resource);
             const authUri = url.toString();
             const authConfig = {
                 credentialKey: binding.provider,
@@ -307,7 +341,15 @@ export function oauthConsent(options) {
             const code = input.code;
             if (typeof code !== 'string' || !CODE_FORMAT.test(code))
                 fail('invalid_request');
-            const client = providers.get(flow.provider);
+            if (!providers.has(flow.provider))
+                fail('unknown_provider');
+            let client;
+            try {
+                client = await clientOf(flow.provider);
+            }
+            catch {
+                return fail('registration_failed');
+            }
             if (!client)
                 fail('unknown_provider');
             let tokens;