melchizedek-agents 1.1.0 → 1.3.0

package/dist/lib/syndicateSchema.js

@@ -26,6 +26,7 @@ import { DEFAULT_ROUTE_KEY, NODE_KINDS, ROUTE_STEP_SUFFIX, START_NAME, elementNa
 import { isSecretShapedEnvName } from './tools/skills/env.js';
 import { OAUTH_SCOPE, PROVIDER_NAME } from './tools/auth.js';
 import { V2_AGENT_KEYS, conflictMessage, conflictsOf, toEngineAgent } from './agentDialect.js';
+import { MCP_TRANSPORTS } from './tools/mcpTransports.js';
 // ── Leaf rules ───────────────────────────────────────────────────────────────
 /**
  * ADK's agent-name rule (validateAgentName in ADK's base_agent), kept: checked here
@@ -45,7 +46,7 @@ const thinkingConfig = z
     includeThoughts: z.boolean().optional().describe('Stream the thinking trace in the response.'),
 })
     .describe('Older spelling of `reasoning` for Gemini and Claude (thinkingLevel or thinkingBudget). Cannot be combined with `reasoning`.');
-export const REASONING_LEVELS = ['none', 'low', 'medium', 'high'];
+export const REASONING_LEVELS = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
 /**
  * The provider-neutral reasoning key (ADR 0047): a level, or a token budget.
  * The compiler maps it per provider (lib/compile.ts reasoningConfig).
@@ -62,7 +63,7 @@ const reasoningSchema = z
         return `must be one of ${REASONING_LEVELS.join(' | ')}, or { budget_tokens: <integer ≥ 0> } (got ${describeValue(iss.input)}${hint ? ` — did you mean "${hint}"?` : ''})`;
     },
 })
-    .describe('How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047).');
+    .describe('How hard this agent reasons, on any provider: none | low | medium | high | xhigh | max, or { budget_tokens: <int> }. xhigh and max reach the models that take them; elsewhere they go as the model\'s highest setting (ADR 0117). Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047).');
 /**
  * Loose on purpose: provider-specific fields (e.g. `toolConfig`) pass through
  * to the SDK. Only the documented fields are typed, so `temperature: hot`
@@ -89,7 +90,7 @@ const generateContentConfig = z
         .optional()
         .describe('Older spelling of `reasoning` for the chat-completions and Responses providers. Cannot be combined with `reasoning`.'),
 })
-    .describe('Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType) and `reasoning` (thinkingConfig, reasoningEffort) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.')
+    .describe('Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType), `reasoning` (thinkingConfig, reasoningEffort) and `tool_choice` (toolConfig.functionCallingConfig) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.')
     .meta({ deprecated: true });
 // ── YAML v2 agent keys (ADR 0115) ────────────────────────────────────────────
 /** `sampling` and `output` must say something: an empty block is a leftover. */
@@ -116,6 +117,20 @@ const outputSchemaV2 = z
 })
     .refine(nonEmpty, { message: 'must set schema or mime', when: quiet })
     .describe('What this agent\'s final reply is (ADR 0115). Replaces outputSchema and generateContentConfig.responseMimeType; cannot be combined with them.');
+export const TOOL_CHOICE_MODES = ['auto', 'none', 'required'];
+const toolChoiceSchema = z
+    .union([
+    z.enum(TOOL_CHOICE_MODES),
+    z.strictObject({
+        name: z.string().min(1).describe('The one tool the model must call: a name from this agent\'s tools, subagents or MCP tools.'),
+    }),
+], {
+    error: (iss) => {
+        const hint = typeof iss.input === 'string' ? suggest(iss.input, TOOL_CHOICE_MODES) : undefined;
+        return `must be one of ${TOOL_CHOICE_MODES.join(' | ')}, or { name: <tool> } (got ${describeValue(iss.input)}${hint ? ` — did you mean "${hint}"?` : ''})`;
+    },
+})
+    .describe('Which tools the model may call, on any provider (ADR 0117): auto (the default), none, required (some tool), or { name: <tool> } (that tool). A provider that rejects forcing sends a weaker choice and marks the span llm.tool_choice.weakened. Replaces generateContentConfig.toolConfig.functionCallingConfig; cannot be combined with it.');
 const modelOverrideEntry = z
     .strictObject({
     instruction: z.string().min(1).optional().describe('Replaces the agent\'s instruction on this provider.'),
@@ -203,8 +218,12 @@ const oauth2Auth = z
     grant: z
         .enum(['authorization_code', 'client_credentials'])
         .describe('authorization_code: each user\'s own token, granted through the consent pause (ADR 0085). client_credentials: the server\'s own token, from the token endpoint.'),
-    authorization_url: z.string().url().optional().describe('The provider\'s authorization endpoint (https). authorization_code only.'),
-    token_url: z.string().url().describe('The provider\'s token endpoint (https).'),
+    client_registration: z
+        .literal('dynamic')
+        .optional()
+        .describe('"dynamic": an MCP server\'s authorization_code grant with no pre-issued client. The authorization server is discovered from the MCP server (RFC 9728, RFC 8414) and this deployment registers itself as a public PKCE client (RFC 7591), once per server and redirect URI, sealed in the credential store (ADR 0124). Every discovered host must be on the operator\'s OAuth host allowlist. MCP servers only; no client id, client secret or endpoint URL beside it.'),
+    authorization_url: z.string().url().optional().describe('The provider\'s authorization endpoint (https). authorization_code only; discovered with client_registration: dynamic.'),
+    token_url: z.string().url().optional().describe('The provider\'s token endpoint (https). Required, except with client_registration: dynamic, which discovers it.'),
     client_id: z.string().min(1).max(512).optional().describe('The OAuth client id, written out (it is not a secret). Or client_id_env.'),
     client_id_env: envName.optional().describe('Environment variable holding the client id. Or client_id.'),
     client_secret_env: envName
@@ -214,13 +233,25 @@ const oauth2Auth = z
     authorization_params: z
         .record(z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/), z.string().max(512))
         .optional()
-        .describe('Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.'),
+        .describe('Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id, resource or the PKCE pair.'),
 })
     .superRefine((o, ctx) => {
-    if (!!o.client_id === !!o.client_id_env)
-        ctx.addIssue({ code: 'custom', path: ['client_id'], message: 'exactly one of client_id or client_id_env' });
-    if (o.grant === 'authorization_code' && !o.authorization_url) {
-        ctx.addIssue({ code: 'custom', path: ['authorization_url'], message: 'an authorization_code grant needs authorization_url' });
+    if (o.client_registration === 'dynamic') {
+        if (o.grant !== 'authorization_code')
+            ctx.addIssue({ code: 'custom', path: ['client_registration'], message: 'client_registration: dynamic is for an authorization_code grant' });
+        for (const key of ['client_id', 'client_id_env', 'client_secret_env', 'authorization_url', 'token_url']) {
+            if (o[key] !== undefined)
+                ctx.addIssue({ code: 'custom', path: [key], message: `${key} cannot be combined with client_registration: dynamic, which discovers the endpoints and registers the client (ADR 0124)` });
+        }
+    }
+    else {
+        if (!!o.client_id === !!o.client_id_env)
+            ctx.addIssue({ code: 'custom', path: ['client_id'], message: 'exactly one of client_id or client_id_env' });
+        if (o.token_url === undefined)
+            ctx.addIssue({ code: 'custom', path: ['token_url'], message: 'token_url is required (on an MCP server, client_registration: dynamic discovers it)' });
+        if (o.grant === 'authorization_code' && !o.authorization_url) {
+            ctx.addIssue({ code: 'custom', path: ['authorization_url'], message: 'an authorization_code grant needs authorization_url' });
+        }
     }
     if (o.grant === 'client_credentials') {
         if (!o.client_secret_env)
@@ -230,13 +261,37 @@ const oauth2Auth = z
                 ctx.addIssue({ code: 'custom', path: [key], message: `${key} is for authorization_code only` });
         }
     }
-    const reserved = ['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope'];
+    const reserved = ['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope', 'resource'];
     for (const key of Object.keys(o.authorization_params ?? {})) {
         if (reserved.includes(key))
             ctx.addIssue({ code: 'custom', path: ['authorization_params', key], message: `authorization_params may not set "${key}"` });
     }
 })
     .describe('An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values.');
+// ── MCP (ADR 0124) ───────────────────────────────────────────────────────────
+const mcpTransport = z
+    .enum(MCP_TRANSPORTS)
+    .describe('How the MCP server is reached: auto (the default) tries Streamable HTTP and falls back to the legacy SSE transport on the spec\'s signal; streamable_http or sse use that one only (ADR 0124).');
+/** An `mcp_servers` entry's name: lowercase, bounded, one character class (no backtracking). */
+export const MCP_SERVER_NAME = /^[a-z][a-z0-9_-]{0,63}$/;
+const mcpServerEntry = z
+    .strictObject({
+    name: z
+        .string()
+        .regex(MCP_SERVER_NAME, 'lowercase letters, digits, _ and -, starting with a letter (at most 64)')
+        .describe('A short name for the server, unique on this agent: logs and errors name it.'),
+    url: z.string().url().describe('The MCP server\'s URL: its Streamable HTTP endpoint, or a legacy SSE endpoint. Checked by the SSRF guard.'),
+    tools: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('The server\'s tools this agent may use, by name; any other tool it lists is not exposed. A name may appear on one server only, and never among the agent\'s own tools. require_approval may name these.'),
+    auth: z
+        .strictObject({ oauth2: oauth2Auth })
+        .optional()
+        .describe('The OAuth grant this server takes (ADR 0112, ADR 0124). Without it, MCP_BEARER_TOKENS applies.'),
+    transport: mcpTransport.optional(),
+})
+    .describe('One MCP server among several (ADR 0124).');
 // ── OpenAPI ──────────────────────────────────────────────────────────────────
 const openapiEntry = z
     .strictObject({
@@ -302,6 +357,7 @@ const agentFields = {
     reasoning: reasoningSchema.optional(),
     sampling: samplingSchema.optional(),
     output: outputSchemaV2.optional(),
+    tool_choice: toolChoiceSchema.optional(),
     model_overrides: modelOverridesSchema.optional(),
     outputSchema: z
         .record(z.string(), z.unknown())
@@ -311,7 +367,7 @@ const agentFields = {
     mcp_server_url: z
         .string()
         .optional()
-        .describe('MCP server (SSE) whose tools are discovered at runtime and merged with `tools`.'),
+        .describe('MCP server (Streamable HTTP, or legacy SSE) whose tools are discovered at runtime and merged with `tools`. For more than one server, use mcp_servers.'),
     mcp_tools: z
         .array(z.string().min(1))
         .min(1)
@@ -321,6 +377,13 @@ const agentFields = {
         .strictObject({ oauth2: oauth2Auth })
         .optional()
         .describe('The OAuth grant the MCP server takes (ADR 0112). With authorization_code, each user\'s own token on their own connection, and mcp_tools is required. Needs mcp_server_url; replaces MCP_BEARER_TOKENS for this server.'),
+    mcp_transport: mcpTransport.optional().describe('How mcp_server_url is reached: auto (the default), streamable_http or sse (ADR 0124). Needs mcp_server_url.'),
+    mcp_servers: z
+        .array(mcpServerEntry)
+        .min(1)
+        .max(16)
+        .optional()
+        .describe('Several MCP servers, each with the tools this agent may use from it, its grant and its transport (ADR 0124). Cannot be combined with mcp_server_url.'),
     skills: skillsSchema.optional(),
     openapi: z.array(openapiEntry).min(1).optional(),
     code_execution: z
@@ -374,7 +437,7 @@ export const subagentSchema = z
         .string()
         .min(1)
         .optional()
-        .describe('A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate\'s gates anywhere, a dispatch syndicate\'s on its classifier (its routes never run nested), and a workflow\'s ask_user nodes and gates when it is delegated to as a subagent.'),
+        .describe('A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate\'s gates anywhere, a dispatch syndicate\'s on its routes, which it classifies and runs as at the top, its route\'s answer being its own (ADR 0120), and a workflow\'s ask_user nodes and gates, wherever each runs: delegated to as a subagent, as a dispatch route or as a workflow node (ADR 0119).'),
     a2a_agent_url: z
         .string()
         .min(1)
@@ -663,6 +726,61 @@ export const REASONING_OLDER_SPELLING = ['thinkingConfig', 'reasoningEffort'];
 const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 /** Same normalisation lib/dispatch.ts uses to match a route to a subagent. */
 const routeNorm = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
+/** Every tool name an agent's `mcp_servers` entries list. */
+function mcpServerTools(agent) {
+    return (Array.isArray(agent.mcp_servers) ? agent.mcp_servers : []).flatMap((e) => (isObj(e) && Array.isArray(e.tools) ? e.tools.filter((t) => typeof t === 'string') : []));
+}
+/**
+ * An agent's `mcp_servers` against itself and its other keys (ADR 0124):
+ * not beside `mcp_server_url`; names unique; a tool name on one server only
+ * and never among the agent's own `tools` or OpenAPI `operations`, so no
+ * server can shadow another's tool or the agent's own; and dynamic client
+ * registration only here or under `mcp_auth`, never on an OpenAPI entry.
+ */
+function mcpServersProblems(agent, path) {
+    const out = [];
+    (Array.isArray(agent.openapi) ? agent.openapi : []).forEach((e, i) => {
+        if (isObj(e) && isObj(e.auth) && isObj(e.auth.oauth2) && e.auth.oauth2.client_registration !== undefined) {
+            out.push({ path: [...path, 'openapi', i, 'auth', 'oauth2', 'client_registration'], message: 'client_registration: dynamic discovers its endpoints from an MCP server; an OpenAPI entry names its own (ADR 0124)' });
+        }
+    });
+    if (!Array.isArray(agent.mcp_servers))
+        return out;
+    if (agent.mcp_server_url !== undefined) {
+        out.push({ path: [...path, 'mcp_servers'], message: 'cannot be combined with mcp_server_url: list that server as one more mcp_servers entry (ADR 0124)' });
+    }
+    const own = new Set([
+        ...(Array.isArray(agent.tools) ? agent.tools.filter((t) => typeof t === 'string') : []),
+        ...(Array.isArray(agent.openapi) ? agent.openapi : []).flatMap((e) => (isObj(e) && Array.isArray(e.operations) ? e.operations.filter((t) => typeof t === 'string') : [])),
+    ]);
+    const names = new Map();
+    const owner = new Map();
+    agent.mcp_servers.forEach((entry, i) => {
+        if (!isObj(entry))
+            return;
+        const name = typeof entry.name === 'string' ? entry.name : `#${i}`;
+        if (typeof entry.name === 'string') {
+            if (names.has(entry.name))
+                out.push({ path: [...path, 'mcp_servers', i, 'name'], message: `'${entry.name}' names mcp_servers entry ${names.get(entry.name)} too; each server's name is unique on the agent` });
+            else
+                names.set(entry.name, i);
+        }
+        (Array.isArray(entry.tools) ? entry.tools : []).forEach((tool, j) => {
+            if (typeof tool !== 'string')
+                return;
+            if (own.has(tool)) {
+                out.push({ path: [...path, 'mcp_servers', i, 'tools', j], message: `'${tool}' is also one of this agent's own tools; an MCP server's tool may not share a name with it (ADR 0124)` });
+            }
+            else if (owner.has(tool) && owner.get(tool) !== name) {
+                out.push({ path: [...path, 'mcp_servers', i, 'tools', j], message: `'${tool}' is also listed on MCP server '${owner.get(tool)}'; a tool name may come from one server only (ADR 0124)` });
+            }
+            else {
+                owner.set(tool, name);
+            }
+        });
+    });
+    return out;
+}
 /**
  * Rules that span fields, which a JSON Schema an editor reads cannot express
  * cleanly. Defensive about shape: runs on raw input alongside zod, so a file
@@ -698,25 +816,19 @@ function crossFieldProblems(raw) {
         // An OpenAPI operation can be gated once it is named under `operations`,
         // and an MCP tool once it is named under `mcp_tools`.
         const operations = (Array.isArray(agent.openapi) ? agent.openapi : []).flatMap((e) => (isObj(e) && Array.isArray(e.operations) ? e.operations : []));
-        const mcpTools = Array.isArray(agent.mcp_tools) ? agent.mcp_tools : [];
+        const mcpTools = [...(Array.isArray(agent.mcp_tools) ? agent.mcp_tools : []), ...mcpServerTools(agent)];
         (Array.isArray(agent.require_approval) ? agent.require_approval : []).forEach((name, j) => {
             if (typeof name === 'string' && !tools.includes(name) && !operations.includes(name) && !mcpTools.includes(name)) {
-                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools, its openapi operations or its mcp_tools` });
+                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools, its openapi operations or its mcp_tools (or an mcp_servers entry's tools)` });
             }
         });
     };
     // A skill script run pauses for approval the same way, so it is allowed in
-    // the same places; `skills.tools` may only unlock tools the agent does not
-    // already carry outright.
-    const skillProblems = (agent, path, allowed) => {
+    // the same places, a delegated subagent included (ADR 0118); `skills.tools`
+    // may only unlock tools the agent does not already carry outright.
+    const skillProblems = (agent, path) => {
         if (!isObj(agent.skills))
             return;
-        if (agent.skills.scripts === 'local' && !allowed) {
-            out.push({
-                path: [...path, 'skills', 'scripts'],
-                message: 'skill scripts on a delegated subagent are not supported yet; run them on the orchestrator or a plan-dispatch route (ADR 0110)',
-            });
-        }
         const tools = Array.isArray(agent.tools) ? agent.tools : [];
         (Array.isArray(agent.skills.tools) ? agent.skills.tools : []).forEach((name, j) => {
             if (typeof name === 'string' && tools.includes(name)) {
@@ -763,6 +875,10 @@ function crossFieldProblems(raw) {
         if (isObj(agent.mcp_auth) && isObj(agent.mcp_auth.oauth2) && agent.mcp_auth.oauth2.grant === 'authorization_code' && agent.mcp_tools === undefined) {
             out.push({ path: [...path, 'mcp_auth'], message: 'an authorization_code mcp_auth needs mcp_tools: no user\'s grant exists at startup to list the server\'s tools' });
         }
+        if (agent.mcp_transport !== undefined && typeof agent.mcp_server_url !== 'string') {
+            out.push({ path: [...path, 'mcp_transport'], message: 'mcp_transport is how mcp_server_url is reached; it needs mcp_server_url (an mcp_servers entry names its own transport)' });
+        }
+        out.push(...mcpServersProblems(agent, path));
     };
     if (isObj(raw.orchestrator))
         executionProblems(raw.orchestrator, ['orchestrator'], true);
@@ -823,19 +939,17 @@ function crossFieldProblems(raw) {
             v2Problems(sub, ['subagents', i]);
     if (isObj(raw.orchestrator)) {
         gateProblems(raw.orchestrator, ['orchestrator'], true);
-        skillProblems(raw.orchestrator, ['orchestrator'], true);
+        skillProblems(raw.orchestrator, ['orchestrator']);
         questionProblems(raw.orchestrator, ['orchestrator'], true);
     }
-    const dispatching = isObj(raw.dispatch);
     // A workflow's subagents are its nodes, not delegated tools: a gated call pauses its node, and
     // the walk resumes it (ADR 0098); a skill script run pauses on the same approval (ADR 0106). A map item cannot (workflowProblems).
-    const pausing = dispatching || isObj(raw.workflow);
     subs.forEach((sub, i) => {
         if (!isObj(sub))
             return;
-        // A delegated subagent's gate and question pause the turn through the open call (ADR 0110); its skill scripts stay refused.
+        // A delegated subagent's gate, question and skill script run pause the turn through the open call (ADR 0110, ADR 0118).
         gateProblems(sub, ['subagents', i], true);
-        skillProblems(sub, ['subagents', i], pausing);
+        skillProblems(sub, ['subagents', i]);
         questionProblems(sub, ['subagents', i], true);
         const hasRef = typeof sub.yaml_reference === 'string';
         const hasRemote = typeof sub.a2a_agent_url === 'string';

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

@@ -93,14 +93,26 @@ export interface CredentialStore {
 /** What the ToolContext member gives a tool: a valid access token for a provider, for this run's user only. */
 export type ToolAccessToken = (provider: string) => Promise<string>;
 export type ToolCredentialErrorCode = 'not_connected' | 'expired' | 'refresh_failed' | 'unreadable' | 'no_user' | 'invalid' | 'unavailable' | 'grant_failed' | 'host_refused';
+/**
+ * Which operator allowlist refused a `host_refused` call: the OAuth host
+ * allowlist, which binds a provider's tokens to its hosts
+ * (`MELCHIZEDEK_OAUTH_HOSTS`, ADR 0114), or the credential host allowlist,
+ * which binds a static credential variable such as a client secret to its
+ * hosts (`MELCHIZEDEK_CREDENTIAL_HOSTS`, ADR 0122).
+ */
+export type HostAllowlist = 'oauth' | 'credential';
 /**
  * A credential that cannot be used. The message names the provider and what
  * to do, never a token, a user or a key, so a tool may return it to the model.
+ * A `host_refused` error names the allowlist that refused (`allowlist`,
+ * `'oauth'` when not given).
  */
 export declare class ToolCredentialError extends Error {
     readonly code: ToolCredentialErrorCode;
     readonly provider?: string;
-    constructor(code: ToolCredentialErrorCode, provider?: string);
+    /** For `host_refused`: the allowlist that refused the host. */
+    readonly allowlist?: HostAllowlist;
+    constructor(code: ToolCredentialErrorCode, provider?: string, allowlist?: HostAllowlist);
 }
 /** A provider name: lowercase letters, digits, and . _ - inside; at most 64 characters. */
 export declare const PROVIDER_NAME: RegExp;

package/dist/lib/tools/auth.js

@@ -32,11 +32,15 @@
 /**
  * A credential that cannot be used. The message names the provider and what
  * to do, never a token, a user or a key, so a tool may return it to the model.
+ * A `host_refused` error names the allowlist that refused (`allowlist`,
+ * `'oauth'` when not given).
  */
 export class ToolCredentialError extends Error {
     code;
     provider;
-    constructor(code, provider) {
+    /** For `host_refused`: the allowlist that refused the host. */
+    allowlist;
+    constructor(code, provider, allowlist) {
         const p = provider ? `"${provider}"` : 'this provider';
         super(code === 'not_connected'
             ? `No ${p} account is connected for this user; ask them to connect it.`
@@ -53,11 +57,15 @@ export class ToolCredentialError extends Error {
                                 : code === 'grant_failed'
                                     ? `The server's own ${p} authorization could not be obtained from the provider's token endpoint.`
                                     : code === 'host_refused'
-                                        ? `The ${p} authorization may not be sent to this host: the operator's OAuth host allowlist does not include it.`
+                                        ? allowlist === 'credential'
+                                            ? `The ${p} client secret may not be sent to this host: the operator's credential host allowlist (MELCHIZEDEK_CREDENTIAL_HOSTS) does not bind it there.`
+                                            : `The ${p} authorization may not be sent to this host: the operator's OAuth host allowlist (MELCHIZEDEK_OAUTH_HOSTS) does not include it.`
                                         : `Invalid credential request for ${p}.`);
         this.name = 'ToolCredentialError';
         this.code = code;
         this.provider = provider;
+        if (code === 'host_refused')
+            this.allowlist = allowlist ?? 'oauth';
     }
 }
 /** A provider name: lowercase letters, digits, and . _ - inside; at most 64 characters. */

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

@@ -0,0 +1,88 @@
+/**
+ * lib/tools/credentialHosts.ts — the operator's credential host allowlist:
+ * which hosts the value of each static credential variable may be sent to
+ * (ADR 0122).
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names a credential variable
+ *   and, beside it, the host its value goes to: an OpenAPI `auth` sends
+ *   `bearer_env` or `api_key.env` to the spec's server (or `base_url`), and
+ *   an `oauth2` block sends `client_secret_env` to its `token_url`.
+ *   credentialEnvProblem (lib/tools/credentialEnv.ts) keeps the framework's
+ *   own secrets out of reach, and the OAuth host allowlist (ADR 0114) binds
+ *   a provider's tokens, but nothing bound a static secret to its API: a
+ *   YAML that names TRACKER_TOKEN could aim it at a host of its own. The
+ *   binding is the operator's, never the YAML's: an environment variable or
+ *   `createA2AApp({ credentialHosts })`.
+ *
+ * THE RULE (ADR 0122):
+ *   - With no allowlist configured, nothing changes: a credential goes to
+ *     the host the YAML names, as before. The doctor and the server binary
+ *     name every credential variable a served YAML sends, as unbound.
+ *   - With an allowlist configured, it is the whole list: every credential
+ *     variable a YAML sends must be on it, and every host its value goes to
+ *     must be one of that variable's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends the value.
+ *
+ * WHAT IT COVERS: `bearer_env`, `api_key.env` and `client_secret_env` (both
+ *   grants: the client-credentials token request, the consent step's code
+ *   exchange and its refresh). Not `client_id_env`: a client id is not a
+ *   secret. Not MCP_BEARER_TOKENS: it maps each token to its host already,
+ *   and the operator writes both.
+ *
+ * THE FORMAT: `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;WEATHER_KEY=api.weather.example.com,*.weather.example.com"`.
+ *   Entries are separated by `;` (or a newline), a variable from its hosts by
+ *   `=`, hosts by `,`. A host is what the OAuth host allowlist takes
+ *   (lib/tools/oauthHosts.ts): a hostname, `*.example.com`, IPv4 or
+ *   `[IPv6]`, with no scheme, port or path.
+ *
+ * Nothing here reads or prints a credential's value: variable names and
+ * hosts only. No regular expression here can backtrack: the separators are
+ * single characters, and a variable name is one bounded character class.
+ */
+/** The environment variable the allowlist is read from when no option sets it. */
+export declare const CREDENTIAL_HOSTS_ENV = "MELCHIZEDEK_CREDENTIAL_HOSTS";
+/** Credential variable name → the hosts its value may be sent to. */
+export type CredentialHostAllowlist = Readonly<Record<string, readonly string[]>>;
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the variable and the host, on anything malformed.
+ */
+export declare function checkCredentialHosts(allowlist: Record<string, readonly string[]>, source?: string): Record<string, string[]>;
+/** The allowlist from its text form (MELCHIZEDEK_CREDENTIAL_HOSTS). Throws on a malformed entry. */
+export declare function parseCredentialHosts(text: string): Record<string, string[]>;
+/**
+ * Sets this process's allowlist (createA2AApp's `credentialHosts` does),
+ * which wins over the environment variable. `undefined` returns to the
+ * variable.
+ */
+export declare function setCredentialHosts(allowlist: Record<string, readonly string[]> | undefined): void;
+/**
+ * The allowlist in force: the one set by `setCredentialHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export declare function credentialHosts(env?: NodeJS.ProcessEnv): CredentialHostAllowlist | undefined;
+/**
+ * Why the value of credential variable `name` may not be sent to `url`, or
+ * null. `role` names the URL in the message (`server`, `token_url`).
+ * `allowlist` defaults to the one in force; `null` means none is
+ * configured, which allows (the behaviour before ADR 0122).
+ */
+export declare function credentialHostProblem(name: string, url: string, role?: string, allowlist?: CredentialHostAllowlist | null | undefined): string | null;
+/**
+ * The call-time check: why the value of `name` may not be sent to
+ * `destination` now, or null. A malformed allowlist refuses.
+ */
+export declare function credentialCallProblem(name: string, destination: string): string | null;
+/**
+ * Marks an OAuth client config (lib/tools/oauthConsent.ts) with the
+ * variable its client secret came from, so the consent step's code exchange
+ * and the refresh hook can check the token endpoint at call time. Set by
+ * oauthClientsFor (lib/tools/oauthTools.ts); a client built by hand carries
+ * none and is not checked.
+ */
+export declare const CLIENT_SECRET_ENV: unique symbol;
+/** The variable a client config's secret came from, when oauthClientsFor marked it. */
+export declare function clientSecretEnvOf(client: object): string | undefined;

package/dist/lib/tools/credentialHosts.js

@@ -0,0 +1,165 @@
+/**
+ * lib/tools/credentialHosts.ts — the operator's credential host allowlist:
+ * which hosts the value of each static credential variable may be sent to
+ * (ADR 0122).
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names a credential variable
+ *   and, beside it, the host its value goes to: an OpenAPI `auth` sends
+ *   `bearer_env` or `api_key.env` to the spec's server (or `base_url`), and
+ *   an `oauth2` block sends `client_secret_env` to its `token_url`.
+ *   credentialEnvProblem (lib/tools/credentialEnv.ts) keeps the framework's
+ *   own secrets out of reach, and the OAuth host allowlist (ADR 0114) binds
+ *   a provider's tokens, but nothing bound a static secret to its API: a
+ *   YAML that names TRACKER_TOKEN could aim it at a host of its own. The
+ *   binding is the operator's, never the YAML's: an environment variable or
+ *   `createA2AApp({ credentialHosts })`.
+ *
+ * THE RULE (ADR 0122):
+ *   - With no allowlist configured, nothing changes: a credential goes to
+ *     the host the YAML names, as before. The doctor and the server binary
+ *     name every credential variable a served YAML sends, as unbound.
+ *   - With an allowlist configured, it is the whole list: every credential
+ *     variable a YAML sends must be on it, and every host its value goes to
+ *     must be one of that variable's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends the value.
+ *
+ * WHAT IT COVERS: `bearer_env`, `api_key.env` and `client_secret_env` (both
+ *   grants: the client-credentials token request, the consent step's code
+ *   exchange and its refresh). Not `client_id_env`: a client id is not a
+ *   secret. Not MCP_BEARER_TOKENS: it maps each token to its host already,
+ *   and the operator writes both.
+ *
+ * THE FORMAT: `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;WEATHER_KEY=api.weather.example.com,*.weather.example.com"`.
+ *   Entries are separated by `;` (or a newline), a variable from its hosts by
+ *   `=`, hosts by `,`. A host is what the OAuth host allowlist takes
+ *   (lib/tools/oauthHosts.ts): a hostname, `*.example.com`, IPv4 or
+ *   `[IPv6]`, with no scheme, port or path.
+ *
+ * Nothing here reads or prints a credential's value: variable names and
+ * hosts only. No regular expression here can backtrack: the separators are
+ * single characters, and a variable name is one bounded character class.
+ */
+import { hostAllowed, hostPatternProblem } from './oauthHosts.js';
+/** The environment variable the allowlist is read from when no option sets it. */
+export const CREDENTIAL_HOSTS_ENV = 'MELCHIZEDEK_CREDENTIAL_HOSTS';
+/** A credential variable's name, as a YAML may write it (lib/syndicateSchema.ts), bounded. */
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the variable and the host, on anything malformed.
+ */
+export function checkCredentialHosts(allowlist, source = 'credentialHosts') {
+    if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist))
+        throw new Error(`${source} must map each credential variable to its hosts.`);
+    const out = {};
+    for (const [name, hosts] of Object.entries(allowlist)) {
+        if (!ENV_NAME.test(name))
+            throw new Error(`${source}: "${name.slice(0, 64)}" is not an environment variable name (A–Z, 0–9, _).`);
+        if (!Array.isArray(hosts) || hosts.length === 0)
+            throw new Error(`${source}: ${name} needs at least one host.`);
+        const seen = new Set();
+        for (const raw of hosts) {
+            const host = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+            const problem = host ? hostPatternProblem(host) : 'is empty';
+            if (problem)
+                throw new Error(`${source}: ${name}: host "${String(raw).slice(0, 80)}" ${problem}.`);
+            seen.add(host);
+        }
+        out[name] = [...seen];
+    }
+    return out;
+}
+/** The allowlist from its text form (MELCHIZEDEK_CREDENTIAL_HOSTS). Throws on a malformed entry. */
+export function parseCredentialHosts(text) {
+    const parsed = {};
+    for (const entry of text.split(/[;\n]/)) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            throw new Error(`${CREDENTIAL_HOSTS_ENV}: each entry is VARIABLE=host,host (got "${trimmed.slice(0, 80)}").`);
+        const name = trimmed.slice(0, eq).trim();
+        if (Object.hasOwn(parsed, name))
+            throw new Error(`${CREDENTIAL_HOSTS_ENV}: ${name.slice(0, 64)} is listed twice.`);
+        parsed[name] = trimmed.slice(eq + 1).split(',').map((h) => h.trim()).filter((h) => h !== '');
+    }
+    return checkCredentialHosts(parsed, CREDENTIAL_HOSTS_ENV);
+}
+let configured;
+let envCache;
+/**
+ * Sets this process's allowlist (createA2AApp's `credentialHosts` does),
+ * which wins over the environment variable. `undefined` returns to the
+ * variable.
+ */
+export function setCredentialHosts(allowlist) {
+    configured = allowlist === undefined ? undefined : checkCredentialHosts(allowlist);
+}
+/**
+ * The allowlist in force: the one set by `setCredentialHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export function credentialHosts(env = process.env) {
+    if (configured)
+        return configured;
+    const raw = env[CREDENTIAL_HOSTS_ENV];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    if (envCache?.raw !== raw)
+        envCache = { raw, value: parseCredentialHosts(raw) };
+    return envCache.value;
+}
+/**
+ * Why the value of credential variable `name` may not be sent to `url`, or
+ * null. `role` names the URL in the message (`server`, `token_url`).
+ * `allowlist` defaults to the one in force; `null` means none is
+ * configured, which allows (the behaviour before ADR 0122).
+ */
+export function credentialHostProblem(name, url, role = 'server', allowlist = credentialHosts()) {
+    const list = allowlist ?? undefined;
+    if (!list)
+        return null;
+    if (!Object.hasOwn(list, name)) {
+        return `${name} is not on the operator's credential host allowlist (${CREDENTIAL_HOSTS_ENV} or createA2AApp's credentialHosts), so it is sent nowhere`;
+    }
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return `${role} '${url.slice(0, 200)}' is not a URL`;
+    }
+    const hosts = list[name];
+    if (hostAllowed(hosts, hostname))
+        return null;
+    return `${name} may be sent only to ${hosts.join(', ')}; ${hostname} (${role}) is not one of them`;
+}
+/**
+ * The call-time check: why the value of `name` may not be sent to
+ * `destination` now, or null. A malformed allowlist refuses.
+ */
+export function credentialCallProblem(name, destination) {
+    try {
+        return credentialHostProblem(name, destination, 'server', credentialHosts() ?? null);
+    }
+    catch {
+        return `the credential host allowlist (${CREDENTIAL_HOSTS_ENV}) is malformed`;
+    }
+}
+/**
+ * Marks an OAuth client config (lib/tools/oauthConsent.ts) with the
+ * variable its client secret came from, so the consent step's code exchange
+ * and the refresh hook can check the token endpoint at call time. Set by
+ * oauthClientsFor (lib/tools/oauthTools.ts); a client built by hand carries
+ * none and is not checked.
+ */
+export const CLIENT_SECRET_ENV = Symbol.for('melchizedek.clientSecretEnv');
+/** The variable a client config's secret came from, when oauthClientsFor marked it. */
+export function clientSecretEnvOf(client) {
+    const name = client[CLIENT_SECRET_ENV];
+    return typeof name === 'string' ? name : undefined;
+}