melchizedek-agents 1.1.0 → 1.2.0

package/dist/lib/compile.js

@@ -264,31 +264,44 @@ function nestedOptions(ref, opts) {
     return { ...opts, [NESTING]: [...chain, ref] };
 }
 /**
- * A nested `yaml_reference:` syndicate, loaded, with the approval gates that
- * cannot pause where it runs refused by name (ADR 0110, ADR 0111):
- *   - a nested delegate syndicate's gates pause the turn through the open
- *     call, wherever it runs;
- *   - a nested dispatch syndicate runs its classifier alone (compileSpec
- *     lists no route on it), so its orchestrator may gate, and a gate on a
- *     route, which never runs nested, is refused;
- *   - a nested workflow's gates pause the walk, which reaches the caller
- *     only through a delegated call's open call (`delegated`): as a
- *     dispatch route or a workflow node, its pause cannot reach the turn
- *     yet, so they are refused there.
+ * A nested `yaml_reference:` syndicate, loaded. Every pause inside one
+ * reaches the turn wherever it runs (ADR 0110, ADR 0111, ADR 0119,
+ * ADR 0120): a nested delegate syndicate's through the open call, a nested
+ * workflow's through its walk, a nested dispatch syndicate's through its
+ * own turn, whose routes run as they run at the top. Nothing is refused
+ * here any more.
  */
-function loadNestedSyndicate(ref, opts, delegated = false) {
+function loadNestedSyndicate(ref, opts) {
     opts.log?.(`Loading nested syndicate: ${ref}`);
-    const nested = (opts.loadNested ?? loadSyndicate)(ref);
-    if (isDispatchSyndicate(nested)) {
-        const gated = (nested.subagents ?? []).find((s) => agentGates(s));
-        if (gated) {
-            throw new Error(`${ref}: approval gates (require_approval, or skill scripts) on the route '${gated.name}' never run: a nested dispatch syndicate runs its classifier alone. Gate the classifier, or run the syndicate as its own.`);
+    return (opts.loadNested ?? loadSyndicate)(ref);
+}
+/**
+ * A nested dispatch syndicate as its entry runs it (ADR 0120). Its routes
+ * compile when its turn routes to one, as at the top, so a route that
+ * cannot compile fails that turn; the references below it are followed
+ * here (loaded, not compiled: no tool is resolved and no MCP server is
+ * reached), so a reference cycle or a depth past the limit is refused at
+ * load, by name, before any model call. A route may not carry the entry's
+ * name: the pause walk tells the nested syndicate from its routes by name.
+ */
+function compileDispatchEntry(subCfg, nested, nestedOpts) {
+    const ref = subCfg.yaml_reference;
+    for (const route of nested.subagents ?? []) {
+        if (route.name === subCfg.name) {
+            throw new Error(`${ref}: the route '${route.name}' has the name its caller gives the nested syndicate; rename the route or the entry.`);
         }
     }
-    else if (isWorkflowSyndicate(nested) && !delegated && declaresApprovals(nested)) {
-        throw new Error(`${ref}: approval gates (require_approval, or skill scripts) in a workflow run as a dispatch route or a workflow node cannot pause the turn yet; delegate to the workflow as a subagent, or run it as its own syndicate.`);
+    followReferences(nested, nestedOpts);
+    return { name: subCfg.name, description: subCfg.description ?? '', config: nested, ref, compile: nestedOpts };
+}
+/** Loads every `yaml_reference` below `config`, depth first, through nestedOptions: a cycle or a chain past the limit throws by name. */
+function followReferences(config, opts) {
+    for (const entry of config.subagents ?? []) {
+        if (!entry.yaml_reference || entry.a2a_agent_url)
+            continue;
+        const below = nestedOptions(entry.yaml_reference, opts);
+        followReferences(loadNestedSyndicate(entry.yaml_reference, below), below);
     }
-    return nested;
 }
 /**
  * The spec of a workflow syndicate: every agent through compileSubagentSpec
@@ -296,35 +309,34 @@ function loadNestedSyndicate(ref, opts, delegated = false) {
  * lookup for its tool nodes. `name` and `description` name a nested one
  * after its subagent entry (ADR 0098); `ref` is the file it came from.
  *
- * A nested workflow delegated to as a subagent (`delegated`) pauses through
- * its caller's open call (ADR 0111). Run as a dispatch route or a workflow
- * node, its pause cannot reach the turn yet: an `ask_user` node is refused
- * by name there.
+ * A nested workflow's pauses (an `ask_user` node, a gate) reach the turn
+ * wherever it runs (ADR 0111, ADR 0119). `delegated` is accepted for the
+ * callers that pass it and no longer changes what compiles.
  */
 export async function compileWorkflowSpec(config, opts = {}, name, description, ref, delegated = false) {
     if (!isWorkflowSyndicate(config))
         throw new Error(`${config.syndicate_name}: no workflow block`);
-    if (name && !delegated) {
-        const asking = Object.entries(config.workflow.nodes ?? {}).find(([, node]) => nodeKind(node) === 'ask_user');
-        if (asking) {
-            throw new Error(`${ref ?? config.syndicate_name}: the ask_user node '${asking[0]}' pauses for a person, which a workflow run as a dispatch route or a workflow node (${name}) cannot carry to the turn yet; delegate to the workflow as a subagent, run it as its own syndicate, or remove the node.`);
-        }
-    }
     const workflowName = name || config.syndicate_name;
     const agents = [];
     const workflows = [];
+    const dispatches = [];
     for (const yaml of [{ description: '', ...config.orchestrator }, ...(config.subagents ?? [])]) {
         const entry = await compileEntrySpec(yaml, opts);
         if (entry.kind === 'workflow')
             workflows.push({ yaml, workflow: entry.workflow });
+        else if (entry.kind === 'dispatch')
+            dispatches.push({ yaml, dispatch: entry.dispatch });
         else
             agents.push({ yaml, spec: entry.spec });
     }
-    // A map runs one agent per item; a nested graph is not an agent a map item can be (ADR 0106).
+    // A map runs one agent per item; a nested graph or a nested dispatch syndicate is not an agent a map item can be (ADR 0106, ADR 0120).
     for (const [node, entry] of Object.entries(config.workflow.nodes ?? {})) {
-        const mapped = nodeKind(entry) === 'map' ? workflows.find((w) => w.yaml.name === entry.map) : undefined;
+        if (nodeKind(entry) !== 'map')
+            continue;
+        const mapped = workflows.find((w) => w.yaml.name === entry.map) ?? dispatches.find((d) => d.yaml.name === entry.map);
         if (mapped) {
-            throw new Error(`${ref ?? config.syndicate_name}: the map node '${node}' runs '${mapped.yaml.name}', a workflow syndicate (${mapped.yaml.yaml_reference}); a map runs one agent per item, so make the workflow a node of its own.`);
+            const what = 'workflow' in mapped ? 'a workflow syndicate' : 'a dispatch syndicate';
+            throw new Error(`${ref ?? config.syndicate_name}: the map node '${node}' runs '${mapped.yaml.name}', ${what} (${mapped.yaml.yaml_reference}); a map runs one agent per item, so make it a node of its own.`);
         }
     }
     return {
@@ -333,6 +345,7 @@ export async function compileWorkflowSpec(config, opts = {}, name, description,
         config: { ...config, syndicate_name: workflowName },
         agents,
         workflows,
+        dispatches,
         resolveTool: (tool) => resolveNamedTools([tool], opts.onUnknownTool)[0],
     };
 }
@@ -346,16 +359,20 @@ export function workflowAgentSpecs(spec) {
  * as its whole graph under the entry's name and description. A delegated
  * subagent, a dispatch route and a workflow node all compile through here,
  * so the graph a file describes is the graph that runs (ADR 0106).
- * `delegated` marks a delegated subagent's entry, whose nested workflow may
- * pause (ADR 0111).
+ * A nested workflow pauses wherever it runs (ADR 0111, ADR 0119);
+ * `delegated` is accepted for the callers that pass it and no longer
+ * changes what compiles.
  */
 export async function compileEntrySpec(subCfg, opts = {}, delegated = false) {
     if (subCfg.yaml_reference && !subCfg.a2a_agent_url) {
         const nestedOpts = nestedOptions(subCfg.yaml_reference, opts);
-        const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts, delegated);
+        const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts);
         if (isWorkflowSyndicate(nested)) {
             return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference, delegated) };
         }
+        // A nested dispatch syndicate classifies and routes as at the top (ADR 0120), wherever it runs.
+        if (isDispatchSyndicate(nested))
+            return { kind: 'dispatch', dispatch: compileDispatchEntry(subCfg, nested, nestedOpts) };
         return { kind: 'agent', spec: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
     }
     return { kind: 'agent', spec: await compileSubagentSpec(subCfg, opts) };
@@ -389,6 +406,9 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
         if (isWorkflowSyndicate(nested)) {
             throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a workflow syndicate, which runs as its whole graph, not as one agent; compile the entry with compileEntrySpec (ADR 0106).`);
         }
+        if (isDispatchSyndicate(nested)) {
+            throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a dispatch syndicate, which runs as its own turn (its classifier, then a route), not as one agent; compile the entry with compileEntrySpec (ADR 0120).`);
+        }
         return compileSpec(nested, nestedOpts, subCfg.name, subCfg.description);
     }
     // YAML v2 (ADR 0115): the engine form, for a config built in code (a loaded one already is).
@@ -427,7 +447,7 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
             }
             // A delegated subagent: a pause inside it, a nested workflow's included, reaches the caller (ADR 0110, ADR 0111).
             const entry = await compileEntrySpec(subCfg, opts, true);
-            return entry.kind === 'workflow' ? entry : { kind: 'agent', agent: entry.spec };
+            return entry.kind === 'agent' ? { kind: 'agent', agent: entry.spec } : entry;
         }));
     const orchestrator = toEngineAgent(config.orchestrator); // YAML v2 (ADR 0115), for a config built in code
     const name = overrideName || orchestrator.name;

package/dist/lib/compileNative.d.ts

@@ -32,13 +32,14 @@
  * caller's. ADK classes are told apart by ADK's own Symbol.for marks, so
  * this file imports nothing from ADK.
  */
-import type { AgentSpec, CompileOptions, WorkflowSpec } from './compile.ts';
+import type { AgentSpec, CompileOptions, DispatchSpec, WorkflowSpec } from './compile.ts';
 import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
 import type { ModelAdapter } from './models/contract.ts';
 import type { WorkflowSubagent } from './runtime/native/delegate.ts';
 import type { NativeAgent } from './runtime/native/request.ts';
 export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.ts';
 import type { WorkflowGraph } from './workflow/graph.ts';
+import type { NestedRun } from './workflow/turn.ts';
 /**
  * The class name of an ADK model the runtime cannot run, else undefined:
  * any ADK BaseLlm (ADR 0107; the ADK runtime that ran one left in 1.0.0).
@@ -67,8 +68,8 @@ export interface NativeWorkflow {
     graph: WorkflowGraph;
     agents: Map<string, NativeAgent>;
     resolveTool: (name: string) => unknown;
-    /** The nodes that are a nested workflow syndicate, each compiled the same way, by YAML name (ADR 0106). */
-    workflows: Map<string, NativeWorkflow>;
+    /** The nodes that are a nested workflow syndicate, each compiled the same way (ADR 0106), or a nested dispatch syndicate, its own turn (ADR 0120), by YAML name. */
+    workflows: Map<string, NativeWorkflow | NestedRun>;
 }
 /**
  * A workflow spec for the walk: the graph, every agent compiled from its
@@ -82,6 +83,13 @@ export declare function compileNativeWorkflow(spec: WorkflowSpec): NativeWorkflo
  * session lib/runtime/native/delegate.ts opened.
  */
 export declare function workflowSubagentOf(workflow: NativeWorkflow): WorkflowSubagent;
+/**
+ * A nested dispatch syndicate as the delegated subagent the native loop
+ * calls, or the node a walk runs (ADR 0120): one call runs it as its own
+ * turn (nestedDispatchWalk) on the child session lib/runtime/native/delegate.ts
+ * (or lib/workflow/turn.ts) opened.
+ */
+export declare function dispatchSubagentOf(dispatch: DispatchSpec): WorkflowSubagent & NestedRun;
 /** One subagent entry (a dispatch route) for the native loop: compileSubagentSpec, then compileNative. */
 export declare function compileNativeSubagent(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<NativeAgent>;
 /** What nativeAdapterFor reads from a spec: its model resolution, the other ids it calls, and its delegated subagents. */

package/dist/lib/compileNative.js

@@ -35,7 +35,7 @@
 import { remoteAgentOwnTool } from './a2a/remoteAgent.js';
 import { compileSpec, compileSubagentSpec, workflowAgentSpecs } from './compile.js';
 import { resolveAdapter } from './models/registry.js';
-import { subagentTool, workflowSubagentTool } from './runtime/native/delegate.js';
+import { nestedDispatchWalk, subagentTool, workflowSubagentTool } from './runtime/native/delegate.js';
 import { unsupportedOnNative } from './runtime/runtimeFlag.js';
 export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.js';
 import { instructionToolOf, toolOf, toolsetOf } from './tools/tool.js';
@@ -108,6 +108,8 @@ export function compileNative(spec) {
             tools.push(subagentTool(compileNative(entry.agent)));
         else if (entry.kind === 'workflow')
             tools.push(workflowSubagentTool(workflowSubagentOf(compileNativeWorkflow(entry.workflow))));
+        else if (entry.kind === 'dispatch')
+            tools.push(workflowSubagentTool(dispatchSubagentOf(entry.dispatch)));
         else if (entry.kind === 'remote')
             tools.push(remoteAgentOwnTool({ name: entry.name, description: entry.description, url: entry.url }));
         else
@@ -182,6 +184,8 @@ export function compileNativeWorkflow(spec) {
     const workflows = new Map();
     for (const { yaml, workflow } of spec.workflows)
         workflows.set(yaml.name, compileNativeWorkflow(workflow));
+    for (const { yaml, dispatch } of spec.dispatches ?? [])
+        workflows.set(yaml.name, dispatchSubagentOf(dispatch));
     refuseUnrunnableNodes(graph, spec.resolveTool);
     return { name: spec.name, description: spec.description, graph, agents, resolveTool: spec.resolveTool, workflows };
 }
@@ -214,6 +218,19 @@ export function workflowSubagentOf(workflow) {
         }),
     };
 }
+/**
+ * A nested dispatch syndicate as the delegated subagent the native loop
+ * calls, or the node a walk runs (ADR 0120): one call runs it as its own
+ * turn (nestedDispatchWalk) on the child session lib/runtime/native/delegate.ts
+ * (or lib/workflow/turn.ts) opened.
+ */
+export function dispatchSubagentOf(dispatch) {
+    return {
+        name: dispatch.name,
+        ...(dispatch.description ? { description: dispatch.description } : {}),
+        walk: (run) => nestedDispatchWalk({ name: dispatch.name, config: dispatch.config, compile: dispatch.compile }, run),
+    };
+}
 /** One subagent entry (a dispatch route) for the native loop: compileSubagentSpec, then compileNative. */
 export async function compileNativeSubagent(subCfg, opts = {}) {
     return compileNative(await compileSubagentSpec(subCfg, opts));

package/dist/lib/doctor.d.ts

@@ -75,6 +75,21 @@ export interface DoctorOAuth {
     set: Record<string, boolean>;
     problems: string[];
 }
+/**
+ * The static credential variables the syndicates send, under the operator's
+ * credential host allowlist (ADR 0122). Present when any syndicate sends one
+ * or MELCHIZEDEK_CREDENTIAL_HOSTS is set. Names and hosts only.
+ */
+export interface DoctorCredentials {
+    /** Whether MELCHIZEDEK_CREDENTIAL_HOSTS is set. */
+    set: boolean;
+    /** Every variable the syndicates send (bearer_env, api_key.env, client_secret_env), sorted. */
+    envs: string[];
+    /** With no allowlist: the variables sent wherever the YAML says, named. Not a --check failure. */
+    warning?: string;
+    /** A malformed allowlist, and each use it refuses (`file: agent · tools · role: why`). A --check failure. */
+    problems: string[];
+}
 export interface DoctorSyndicate {
     /** Path relative to the agents dir, e.g. "examples/council.yaml". */
     file: string;
@@ -106,6 +121,11 @@ export interface DoctorSyndicate {
     };
     /** The tools that need an OAuth grant (ADR 0112), when any do. */
     grants?: DoctorGrant[];
+    /** The static credential variables its tools send (ADR 0122), and what the allowlist refuses; when it sends any. */
+    credentials?: {
+        envs: string[];
+        problems: string[];
+    };
 }
 export interface Unlock {
     env: string;
@@ -141,6 +161,45 @@ export interface DoctorResult {
     counts: Record<VerdictState, number>;
     /** The OAuth setup, when any syndicate declares a grant or its variables are set. */
     oauth?: DoctorOAuth;
+    /** The credential host allowlist (ADR 0122), when any syndicate sends a static credential or it is set. */
+    credentials?: DoctorCredentials;
+    /** How each provider would be reached here: the providers line, as data. */
+    providers: ProviderPath[];
+    /** How the A2A server would authenticate and bill, when any of its variables is set. */
+    serving?: DoctorServing;
+}
+/**
+ * How one provider would be reached under this environment (the doctor's
+ * providers line): funded or not, directly or through the gateway, and on
+ * which platform. `melchizedek-setup --auto` reads its levels from this.
+ */
+export interface ProviderPath {
+    provider: ProviderId;
+    label: string;
+    funded: boolean;
+    transport: 'direct' | 'gateway';
+    /** The gateway id when transport is 'gateway'. */
+    gateway?: string;
+    /** `local` for Ollama; a cloud platform (vertex, bedrock, azure) or `direct` otherwise. */
+    platform: Platform | 'local';
+    keyEnv: string | null;
+}
+/**
+ * The A2A server's identity and billing settings (scripts/a2a_server.ts),
+ * names and presence only: which `A2A_AUTH` mode, whether the secret and the
+ * mode's own variables are set, and who pays (`A2A_KEY_MODE`).
+ */
+export interface DoctorServing {
+    /** A2A_AUTH as set, or `secret` (the server's default). */
+    auth: string;
+    /** True when A2A_AUTH is set explicitly. */
+    authDeclared: boolean;
+    /** A2A_KEY_MODE as set, or `server`. */
+    keyMode: string;
+    /** Which of the serving variables are set (never their values). */
+    set: Record<string, boolean>;
+    /** What the server would refuse to start on, by variable name. */
+    problems: string[];
 }
 export interface DoctorEndpoint {
     provider: ProviderId;
@@ -166,6 +225,16 @@ export interface DoctorEndpoint {
 export declare function runtimeReport(env?: NodeJS.ProcessEnv): DoctorRuntime;
 /** One row per provider that is not on its vendor's public API with an env key. */
 export declare function endpointRows(): DoctorEndpoint[];
+/** One status per provider, probed with an id of its own prefix (the providers line). */
+export declare function providerPaths(): ProviderPath[];
+/** The serving variables the doctor reports by presence. */
+export declare const SERVING_ENV: readonly ['A2A_AUTH', 'A2A_SERVER_SECRET', 'A2A_CALLERS', 'A2A_JWT_ISSUER', 'A2A_JWT_AUDIENCE', 'A2A_JWT_JWKS_URL', 'A2A_JWT_SECRET', 'A2A_TRUSTED_USER_HEADER', 'A2A_KEY_MODE', 'PUBLIC_URL'];
+/**
+ * How the A2A server would authenticate callers and who would pay, from the
+ * environment; undefined when none of its variables is set. The checks are
+ * the ones scripts/a2a_server.ts stops on, reported by name.
+ */
+export declare function servingReport(env?: NodeJS.ProcessEnv): DoctorServing | undefined;
 export declare const CONSOLE_URLS: Record<ProviderId, string>;
 /**
  * Every syndicate file the loader can see: the root (this deployment's
@@ -194,6 +263,13 @@ export declare function runDoctor(options?: {
     agentsDir?: string;
     scripts?: Record<string, string>;
 }): DoctorResult;
+/**
+ * Why `melchizedek-doctor --check` exits non-zero, one line each; empty when
+ * it passes. A blocked syndicate, a runtime problem, the OAuth setup's and
+ * the credential allowlist's problems, and each grant whose hosts the OAuth
+ * host allowlist refuses (ADR 0114). Names and hosts only, never a value.
+ */
+export declare function checkProblems(result: DoctorResult): string[];
 export declare function renderDoctor(result: DoctorResult, opts?: {
     color?: boolean;
 }): string;

package/dist/lib/doctor.js

@@ -38,6 +38,9 @@ import { agentOAuthGrants, oauthEnvNames } from './tools/oauthTools.js';
 import { grantHostProblems, OAUTH_REDIRECT_URI_ENV, oauthEnvProblems } from './a2a/oauthSetup.js';
 import { CREDENTIAL_KEY_ENV } from './tools/credentialCipher.js';
 import { OAUTH_HOSTS_ENV } from './tools/oauthHosts.js';
+import { CREDENTIAL_HOSTS_ENV, credentialHosts } from './tools/credentialHosts.js';
+import { syndicateCredentialUses } from './tools/credentialUses.js';
+import { credentialHostEnvProblems, unboundCredentialWarning } from './a2a/oauthSetup.js';
 function resolvable(module) {
     try {
         createRequire(import.meta.url).resolve(module);
@@ -100,6 +103,69 @@ export function endpointRows() {
     }
     return rows;
 }
+/** One status per provider, probed with an id of its own prefix (the providers line). */
+export function providerPaths() {
+    return Object.keys(PROVIDERS).map((p) => {
+        const r = describeCapabilities(PROBE_ID[p]);
+        return {
+            provider: p,
+            label: PROVIDERS[p].label,
+            funded: r.funded,
+            transport: r.transport,
+            ...(r.gateway ? { gateway: r.gateway } : {}),
+            platform: p === 'ollama' ? 'local' : (r.platform ?? 'direct'),
+            keyEnv: r.keyEnv,
+        };
+    });
+}
+/** The serving variables the doctor reports by presence. */
+export const SERVING_ENV = [
+    'A2A_AUTH',
+    'A2A_SERVER_SECRET',
+    'A2A_CALLERS',
+    'A2A_JWT_ISSUER',
+    'A2A_JWT_AUDIENCE',
+    'A2A_JWT_JWKS_URL',
+    'A2A_JWT_SECRET',
+    'A2A_TRUSTED_USER_HEADER',
+    'A2A_KEY_MODE',
+    'PUBLIC_URL',
+];
+/**
+ * How the A2A server would authenticate callers and who would pay, from the
+ * environment; undefined when none of its variables is set. The checks are
+ * the ones scripts/a2a_server.ts stops on, reported by name.
+ */
+export function servingReport(env = process.env) {
+    const has = (name) => !!env[name]?.trim();
+    const set = Object.fromEntries(SERVING_ENV.map((name) => [name, has(name)]));
+    if (!Object.values(set).some(Boolean))
+        return undefined;
+    // A value outside the known modes is reported as `invalid`, never echoed:
+    // a secret pasted into the wrong variable must not reach the terminal.
+    const rawAuth = (env.A2A_AUTH ?? '').trim().toLowerCase() || 'secret';
+    const rawKeyMode = (env.A2A_KEY_MODE ?? '').trim().toLowerCase() || 'server';
+    const auth = ['secret', 'callers', 'jwt', 'header'].includes(rawAuth) ? rawAuth : 'invalid';
+    const keyMode = rawKeyMode === 'server' || rawKeyMode === 'byok' ? rawKeyMode : 'invalid';
+    const problems = [];
+    if (auth === 'invalid')
+        problems.push('A2A_AUTH must be secret, callers, jwt or header');
+    if (auth === 'callers' && !has('A2A_CALLERS'))
+        problems.push('A2A_AUTH=callers needs A2A_CALLERS');
+    if (auth === 'jwt' && (!has('A2A_JWT_ISSUER') || !has('A2A_JWT_AUDIENCE')))
+        problems.push('A2A_AUTH=jwt needs A2A_JWT_ISSUER and A2A_JWT_AUDIENCE');
+    if (auth === 'jwt' && !has('A2A_JWT_JWKS_URL') && !has('A2A_JWT_SECRET'))
+        problems.push('A2A_AUTH=jwt needs A2A_JWT_JWKS_URL or A2A_JWT_SECRET');
+    if (auth === 'header' && (!has('A2A_TRUSTED_USER_HEADER') || !has('A2A_SERVER_SECRET')))
+        problems.push('A2A_AUTH=header needs A2A_TRUSTED_USER_HEADER and A2A_SERVER_SECRET');
+    if (keyMode !== 'server' && keyMode !== 'byok')
+        problems.push("A2A_KEY_MODE must be 'server' or 'byok'");
+    if (has('PUBLIC_URL') && !has('A2A_AUTH'))
+        problems.push('PUBLIC_URL is set, so A2A_AUTH must be set explicitly (with A2A_SERVED_AGENTS and A2A_TRUST_PROXY)');
+    if (auth === 'secret' && !has('A2A_SERVER_SECRET') && keyMode === 'byok')
+        problems.push('A2A_KEY_MODE=byok without A2A_SERVER_SECRET (or caller tokens) serves unauthenticated, loopback only');
+    return { auth, authDeclared: has('A2A_AUTH'), keyMode, set, problems };
+}
 // ── Where to get a key ───────────────────────────────────────────────────────
 export const CONSOLE_URLS = {
     gemini: 'https://aistudio.google.com',
@@ -305,6 +371,17 @@ export function diagnoseSyndicate(file, agentsDir, scripts) {
         const nestedErrors = [];
         const grants = [];
         walk(config, '', { load, seen: new Set([file, path.basename(file)]), nestedErrors, grants }, rows);
+        // Static credentials and the credential host allowlist (ADR 0122); a nested file that cannot load is reported above.
+        const loadQuiet = (ref) => {
+            try {
+                return load(ref);
+            }
+            catch {
+                return {};
+            }
+        };
+        const credentialEnvs = [...new Set(syndicateCredentialUses([config], loadQuiet).map((u) => u.env))].sort();
+        const credentials = credentialEnvs.length ? { envs: credentialEnvs, problems: credentialHostEnvProblems([config], process.env, loadQuiet) } : undefined;
         const memory = config.memory_system === 'long-term'
             ? {
                 namespace: config.memory_namespace ?? LEGACY_MEMORY_APP_NAME,
@@ -324,6 +401,7 @@ export function diagnoseSyndicate(file, agentsDir, scripts) {
             ...(nestedErrors.length ? { error: nestedErrors.join('\n') } : {}),
             ...(memory ? { memory } : {}),
             ...(grants.length ? { grants } : {}),
+            ...(credentials ? { credentials } : {}),
         };
     }
     catch (err) {
@@ -405,8 +483,9 @@ export function runDoctor(options = {}) {
     const rawGateway = (process.env[GATEWAY_ENV] ?? '').trim();
     const gateway = rawGateway
         ? {
-            id: cfg?.gateway.id ?? rawGateway,
-            label: cfg?.gateway.label ?? rawGateway,
+            // An unrecognised value is never echoed: it may be a key pasted into the wrong variable.
+            id: cfg?.gateway.id ?? 'unrecognised',
+            label: cfg?.gateway.label ?? 'an unrecognised gateway',
             usable: gatewayUsable(),
             ...(gatewayProblem() ? { problem: gatewayProblem() } : {}),
         }
@@ -424,7 +503,39 @@ export function runDoctor(options = {}) {
     const grants = syndicates.flatMap((s) => s.grants ?? []).map((g) => ({ agent: g.agent, tools: g.tools, oauth2: { provider: g.provider, grant: g.grant, token_url: '' } }));
     const set = Object.fromEntries([CREDENTIAL_KEY_ENV, OAUTH_REDIRECT_URI_ENV, OAUTH_HOSTS_ENV].map((name) => [name, !!process.env[name]?.trim()]));
     const oauth = grants.length || Object.values(set).some(Boolean) ? { set, problems: oauthEnvProblems(grants) } : undefined;
-    return { agentsDir, runtime: runtimeReport(), syndicates, unlocks, gateway, endpoints: endpointRows(), counts, ...(oauth ? { oauth } : {}) };
+    // The credential host allowlist (ADR 0122): unbound variables named, refusals listed, names and hosts only.
+    const credentialSet = !!process.env[CREDENTIAL_HOSTS_ENV]?.trim();
+    const envs = [...new Set(syndicates.flatMap((s) => s.credentials?.envs ?? []))].sort();
+    let credentials;
+    if (envs.length || credentialSet) {
+        const problems = [];
+        try {
+            credentialHosts();
+        }
+        catch (err) {
+            problems.push(err instanceof Error ? err.message : `${CREDENTIAL_HOSTS_ENV} is malformed`);
+        }
+        if (!problems.length)
+            for (const s of syndicates)
+                for (const p of s.credentials?.problems ?? [])
+                    problems.push(`${s.file}: ${p}`);
+        const warning = unboundCredentialWarning(envs);
+        credentials = { set: credentialSet, envs, ...(warning ? { warning } : {}), problems };
+    }
+    const serving = servingReport();
+    return {
+        agentsDir,
+        runtime: runtimeReport(),
+        syndicates,
+        unlocks,
+        gateway,
+        endpoints: endpointRows(),
+        counts,
+        ...(oauth ? { oauth } : {}),
+        ...(credentials ? { credentials } : {}),
+        providers: providerPaths(),
+        ...(serving ? { serving } : {}),
+    };
 }
 // ── Rendering ────────────────────────────────────────────────────────────────
 const ANSI = {
@@ -445,6 +556,29 @@ const PROBE_ID = {
     moonshot: 'kimi-x',
     ollama: 'ollama/x',
 };
+/**
+ * Why `melchizedek-doctor --check` exits non-zero, one line each; empty when
+ * it passes. A blocked syndicate, a runtime problem, the OAuth setup's and
+ * the credential allowlist's problems, and each grant whose hosts the OAuth
+ * host allowlist refuses (ADR 0114). Names and hosts only, never a value.
+ */
+export function checkProblems(result) {
+    const problems = [];
+    if (result.counts.blocked > 0)
+        problems.push(`${result.counts.blocked} syndicate(s) blocked`);
+    if (result.runtime.problem)
+        problems.push(result.runtime.problem);
+    for (const p of result.oauth?.problems ?? [])
+        problems.push(`oauth: ${p}`);
+    for (const p of result.credentials?.problems ?? [])
+        problems.push(`credentials: ${p}`);
+    for (const s of result.syndicates) {
+        for (const g of s.grants ?? [])
+            for (const p of g.hostProblems ?? [])
+                problems.push(`${s.file}: ${g.agent} · ${g.provider}: ${p}`);
+    }
+    return problems;
+}
 function pad(s, n) {
     return s.length >= n ? s.slice(0, n - 1) + '…' : s.padEnd(n);
 }
@@ -471,11 +605,10 @@ export function renderDoctor(result, opts = {}) {
     // Provider line: what is funded, and how. Each provider is probed with an
     // id of its own prefix, so the line names ITS key (a fallthrough once put
     // xAI's key beside Moonshot).
-    const providerBits = Object.keys(PROVIDERS).map((p) => {
-        const r = describeCapabilities(PROBE_ID[p]);
+    const providerBits = (result.providers ?? providerPaths()).map((r) => {
         const mark = !r.funded ? `${c.red}✗${c.reset}` : r.transport === 'gateway' ? `${c.yellow}◇${c.reset}` : `${c.green}✓${c.reset}`;
-        const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : p === 'ollama' ? `${c.dim}local${c.reset}` : `${c.dim}${r.platform ?? 'direct'}${c.reset}`;
-        return `${mark} ${PROVIDERS[p].label} ${how}`;
+        const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : r.platform === 'local' ? `${c.dim}local${c.reset}` : `${c.dim}${r.platform}${c.reset}`;
+        return `${mark} ${r.label} ${how}`;
     });
     lines.push('providers   ' + providerBits.join('   '));
     for (const e of result.endpoints ?? []) {
@@ -490,6 +623,15 @@ export function renderDoctor(result, opts = {}) {
             ? `gateway     ${c.red}✗${c.reset} ${result.gateway.problem}`
             : `gateway     ${c.yellow}◇${c.reset} ${result.gateway.label} fills in for any provider whose direct key is absent ${c.dim}(native search is lost on that path)${c.reset}`);
     }
+    if (result.serving) {
+        // Names only: the A2A identity mode, who pays, and what the server would refuse.
+        const sv = result.serving;
+        const mark = sv.problems.length ? `${c.red}✗${c.reset}` : `${c.green}✓${c.reset}`;
+        const set = Object.entries(sv.set).filter(([, on]) => on).map(([name]) => name).join(', ');
+        lines.push(`serving     ${mark} A2A_AUTH=${sv.auth}${sv.authDeclared ? '' : ' (default)'} · A2A_KEY_MODE=${sv.keyMode} ${c.dim}· set: ${set || 'none'}${c.reset}`);
+        for (const p of sv.problems)
+            lines.push(`            ${c.red}✗ ${p}${c.reset}`);
+    }
     if (result.oauth) {
         // Names only: which variables are set, never their values (ADR 0114).
         const set = Object.entries(result.oauth.set).map(([name, on]) => `${name} ${on ? 'set' : 'unset'}`).join(' · ');
@@ -498,6 +640,16 @@ export function renderDoctor(result, opts = {}) {
         for (const p of result.oauth.problems)
             lines.push(`            ${c.red}✗ ${p}${c.reset}`);
     }
+    if (result.credentials) {
+        // Names only: which variables are sent, never their values (ADR 0122).
+        const cr = result.credentials;
+        const mark = cr.problems.length ? `${c.red}✗${c.reset}` : cr.warning ? `${c.yellow}⚠${c.reset}` : `${c.green}✓${c.reset}`;
+        lines.push(`credentials ${mark} ${c.dim}${CREDENTIAL_HOSTS_ENV} ${cr.set ? 'set' : 'unset'}${cr.envs.length ? ` · sent: ${cr.envs.join(', ')}` : ''}${c.reset}`);
+        if (cr.warning)
+            lines.push(`            ${c.yellow}⚠ ${cr.warning}${c.reset}`);
+        for (const p of cr.problems)
+            lines.push(`            ${c.red}✗ ${p}${c.reset}`);
+    }
     lines.push('');
     // The table: one line per syndicate (name, verdict, run command), then
     // one indented line per agent.

package/dist/lib/loadSyndicate.d.ts

@@ -129,6 +129,15 @@ export interface AgentYamlConfig {
         schema?: Record<string, unknown>;
         mime?: 'application/json' | 'text/plain';
     };
+    /**
+     * Which tools the model may call (v2, ADR 0117): `auto`, `none`,
+     * `required`, or `{ name }` for one tool. Replaces
+     * generateContentConfig.toolConfig.functionCallingConfig; folded into it
+     * by the loader (lib/agentDialect.ts toEngineAgent).
+     */
+    tool_choice?: 'auto' | 'none' | 'required' | {
+        name: string;
+    };
     /**
      * Per-provider instruction (v2), keyed by provider id (lib/models/providerMap.ts):
      * `instruction` replaces the agent's instruction, `instruction_append` is

package/dist/lib/models/capabilities.d.ts

@@ -74,6 +74,15 @@ export declare function capabilityOf(model: string, capability: Capability, opts
 }): CapabilityCell & {
     row: MatrixRow;
 };
+/**
+ * The reasoning levels above `high` (ADR 0117), per row: what `reasoning:
+ * xhigh` and `reasoning: max` reach the provider as. A level a model lacks
+ * goes as its highest setting, and the request's `llm.request` span carries
+ * `llm.reasoning.weakened` with the level asked for. Asserted against the
+ * request bodies in tests/toolChoiceEffort.test.ts; the direct adapters read
+ * lib/models/reasoning.ts effortCeiling.
+ */
+export declare const REASONING_ABOVE_HIGH: Readonly<Record<MatrixRow, string>>;
 /**
  * Whether an outputSchema goes in the same request as the agent's tools, as
  * the provider's own structured-output field, on the path `model` takes