melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/compile.js

@@ -40,6 +40,7 @@ import { isWorkflowSyndicate, nodeKind } from './workflowConfig.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
 import { REASONING_OLDER_SPELLING } from './syndicateSchema.js';
 import { reasoningConfig } from './models/reasoning.js';
+import { instructionFor, toEngineAgent } from './agentDialect.js';
 import { resolveTools as resolveNamedTools } from './toolRegistry.js';
 import { createMcpTools } from './tools/mcpToolFactory.js';
 import { requireApproval, toolOf } from './tools/tool.js';
@@ -144,7 +145,7 @@ export function examplesTool(examples) {
     const tool = examplesInstructionTool(examples);
     return tool ? [tool] : [];
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
+async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed, mcpAuth) {
     const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
     // OpenAPI operations become tools here, so require_approval can name them.
     for (const entry of openapi ?? []) {
@@ -158,7 +159,8 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, example
     }
     if (mcpServerUrl) {
         opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        const offered = await createMcpTools(mcpServerUrl);
+        // An authorization_code server lists nothing at startup: its tools are the mcp_tools names, each on its user's own connection (ADR 0112).
+        const offered = await createMcpTools(mcpServerUrl, { ...(mcpAllowed ? { tools: mcpAllowed } : {}), ...(mcpAuth?.oauth2 ? { oauth2: mcpAuth.oauth2 } : {}) });
         // mcp_tools: only the named tools are exposed (a server's list is its
         // own to change); a name the server does not offer is reported, and a
         // gate on it fails the compile in gateTools.
@@ -201,9 +203,11 @@ async function withSkills(instruction, tools, skills, agentName, opts) {
 export function agentGates(agent) {
     return !!agent?.require_approval?.length || agent?.skills?.scripts === 'local';
 }
-function specOf(yaml, name, description, instruction, tools, opts) {
-    const resolvedModel = (opts.resolveModel ?? ((m) => m))(yaml.model);
-    const modelId = modelIdOf(yaml.model, resolvedModel);
+function resolveAgentModel(model, opts) {
+    const resolvedModel = (opts.resolveModel ?? ((m) => m))(model);
+    return { resolvedModel, modelId: modelIdOf(model, resolvedModel) };
+}
+function specOf(yaml, name, description, instruction, tools, { resolvedModel, modelId }) {
     const spec = {
         name,
         instruction,
@@ -240,12 +244,6 @@ function specOf(yaml, name, description, instruction, tools, opts) {
     return spec;
 }
 const asTools = (tools) => tools.map((tool) => ({ kind: 'tool', tool }));
-/**
- * A nested `yaml_reference:` syndicate, loaded. A nested syndicate runs
- * inside a tool call (or as a route whose own subagents do): a pause there
- * cannot reach the caller (ADR 0028), so one that declares approval gates is
- * refused.
- */
 /** Where the yaml_reference chain a compile is inside is kept: an own symbol on the options, so a spread copy keeps it. */
 const NESTING = Symbol('melchizedek.compile.nesting');
 /** The deepest a yaml_reference chain may go: well past any syndicate the engine ships, short of the stack. */
@@ -265,13 +263,45 @@ function nestedOptions(ref, opts) {
         throw new Error(`${ref}: nested syndicates go deeper than ${MAX_NESTING_DEPTH} levels (${[...chain, ref].join(' → ')}).`);
     return { ...opts, [NESTING]: [...chain, ref] };
 }
+/**
+ * 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) {
     opts.log?.(`Loading nested syndicate: ${ref}`);
-    const nested = (opts.loadNested ?? loadSyndicate)(ref);
-    if (declaresApprovals(nested)) {
-        throw new Error(`${ref}: approval gates (require_approval) are not supported inside a nested syndicate.`);
+    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.`);
+        }
+    }
+    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
@@ -279,34 +309,34 @@ function loadNestedSyndicate(ref, opts) {
  * 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 runs inside its caller's tool call, so a pause inside it
- * could not reach the caller (ADR 0028, as for any nested syndicate): an
- * `ask_user` node is refused by name here.
+ * 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) {
+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) {
-        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 nested in another syndicate (${name}) cannot carry to its caller; run the workflow 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 {
@@ -315,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],
     };
 }
@@ -328,14 +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).
+ * 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 = {}) {
+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);
         if (isWorkflowSyndicate(nested)) {
-            return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference) };
+            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) };
@@ -369,12 +406,19 @@ 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);
     }
-    const gated = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts, subCfg.openapi, subCfg.examples, subCfg.mcp_tools), subCfg.require_approval, subCfg.name);
-    const { instruction, tools } = await withSkills(subCfg.instruction ?? '', gated, subCfg.skills, subCfg.name, opts);
-    logCapabilities(opts, subCfg.name, subCfg.model, subCfg.tools);
-    return specOf(subCfg, subCfg.name, subCfg.description, instruction, asTools(tools), opts);
+    // YAML v2 (ADR 0115): the engine form, for a config built in code (a loaded one already is).
+    const agent = toEngineAgent(subCfg);
+    const gated = gateTools(await resolveAgentTools(agent.tools, agent.mcp_server_url, opts, agent.openapi, agent.examples, agent.mcp_tools, agent.mcp_auth), agent.require_approval, agent.name);
+    const model = resolveAgentModel(agent.model, opts);
+    // model_overrides for the provider the agent runs on, before the skills index is appended.
+    const { instruction, tools } = await withSkills(instructionFor(agent, model.modelId), gated, agent.skills, agent.name, opts);
+    logCapabilities(opts, agent.name, agent.model, agent.tools);
+    return specOf(agent, agent.name, agent.description, instruction, asTools(tools), model);
 }
 /**
  * The spec of a syndicate's orchestrator. In DELEGATE mode its subagents
@@ -401,16 +445,24 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
                 opts.log?.(`Remote A2A agent: ${subCfg.name} → ${subCfg.a2a_agent_url}`);
                 return { kind: 'remote', name: subCfg.name, description: subCfg.description, url: subCfg.a2a_agent_url };
             }
-            const entry = await compileEntrySpec(subCfg, opts);
-            return entry.kind === 'workflow' ? entry : { kind: 'agent', agent: entry.spec };
+            // 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 === 'agent' ? { kind: 'agent', agent: entry.spec } : entry;
         }));
-    const name = overrideName || config.orchestrator.name;
-    // Orchestrator tools are registry names only — no entrypoint has ever
-    // attached an MCP server to an orchestrator, and this compiler preserves
-    // that exactly rather than widening the contract in passing.
-    const own = gateTools(await resolveAgentTools(config.orchestrator.tools, undefined, opts, config.orchestrator.openapi, config.orchestrator.examples), config.orchestrator.require_approval, name);
-    // The skills toolset goes last, after the delegations and the agent's own tools.
-    const { instruction, tools } = await withSkills(config.orchestrator.instruction, own, config.orchestrator.skills, name, opts);
-    logCapabilities(opts, name, config.orchestrator.model, config.orchestrator.tools);
-    return specOf(config.orchestrator, name, overrideDescription || config.orchestrator.description, instruction, [...delegated, ...asTools(tools)], opts);
+    const orchestrator = toEngineAgent(config.orchestrator); // YAML v2 (ADR 0115), for a config built in code
+    const name = overrideName || orchestrator.name;
+    // The orchestrator's own tools resolve as a subagent's do: registry
+    // names, OpenAPI operations, and the MCP server's tools (narrowed by
+    // mcp_tools, under its mcp_auth grant), so a one-agent syndicate can reach an MCP server.
+    const own = gateTools(await resolveAgentTools(orchestrator.tools, orchestrator.mcp_server_url, opts, orchestrator.openapi, orchestrator.examples, orchestrator.mcp_tools, orchestrator.mcp_auth), orchestrator.require_approval, name);
+    const model = resolveAgentModel(orchestrator.model, opts);
+    // The skills toolset goes last, after the delegations and the agent's own tools; the
+    // skills index goes after the instruction with its model_overrides entry applied.
+    const { instruction, tools } = await withSkills(instructionFor(orchestrator, model.modelId), own, orchestrator.skills, name, opts);
+    logCapabilities(opts, name, orchestrator.model, orchestrator.tools);
+    const spec = specOf(orchestrator, name, overrideDescription || orchestrator.description, instruction, [...delegated, ...asTools(tools)], model);
+    // The syndicate's own key: a nested syndicate's orchestrator runs its delegations under its own file's (ADR 0116).
+    if (config.max_concurrency !== undefined)
+        spec.maxConcurrency = config.max_concurrency;
+    return spec;
 }

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
@@ -145,6 +147,8 @@ export function compileNative(spec) {
         agent.fallbackModel = spec.fallbackModel;
     if (spec.context)
         agent.context = spec.context;
+    if (spec.maxConcurrency !== undefined)
+        agent.maxConcurrency = spec.maxConcurrency;
     return agent;
 }
 /**
@@ -180,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 };
 }
@@ -212,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/dispatch.d.ts

@@ -26,11 +26,16 @@
  * be logged, traced, and streamed to a waiting user as progress. In DELEGATE
  * mode the choice is only ever implicit in a tool call.
  *
- * ── Why the router MUST be tool-less ──────────────────────────────────────
- * The classifier holds an `outputSchema`, and an agent holding one answers
- * with that JSON and nothing else (see config/agents/examples/critic.yaml; ADK
- * refused the combination outright). So the classifier is a leaf with no
- * subagent tools, and dispatch happens in code where it belongs.
+ * ── Why the router is tool-less ────────────────────────────────────────────
+ * The classifier holds an `outputSchema`, and an agent holding one ends its
+ * turn on that JSON. Its JSON names a route for code to run, so it holds no
+ * subagent tools: dispatch happens in code where it belongs. This is a choice
+ * of method, not a constraint of the engine: an orchestrator may hold an
+ * `outputSchema` beside its subagent tools, delegate, and answer in that
+ * schema itself (ADR 0109; ADK refused the combination, the engine does not).
+ * Plan-dispatch is for a turn whose answer IS the specialist's; a schema on a
+ * delegating orchestrator is for a turn whose answer is the orchestrator's
+ * own structured judgment of what its team returned.
  *
  * ── Fail-static ───────────────────────────────────────────────────────────
  * Every failure mode here resolves to `default_route` and answers the user.

package/dist/lib/dispatch.js

@@ -26,11 +26,16 @@
  * be logged, traced, and streamed to a waiting user as progress. In DELEGATE
  * mode the choice is only ever implicit in a tool call.
  *
- * ── Why the router MUST be tool-less ──────────────────────────────────────
- * The classifier holds an `outputSchema`, and an agent holding one answers
- * with that JSON and nothing else (see config/agents/examples/critic.yaml; ADK
- * refused the combination outright). So the classifier is a leaf with no
- * subagent tools, and dispatch happens in code where it belongs.
+ * ── Why the router is tool-less ────────────────────────────────────────────
+ * The classifier holds an `outputSchema`, and an agent holding one ends its
+ * turn on that JSON. Its JSON names a route for code to run, so it holds no
+ * subagent tools: dispatch happens in code where it belongs. This is a choice
+ * of method, not a constraint of the engine: an orchestrator may hold an
+ * `outputSchema` beside its subagent tools, delegate, and answer in that
+ * schema itself (ADR 0109; ADK refused the combination, the engine does not).
+ * Plan-dispatch is for a turn whose answer IS the specialist's; a schema on a
+ * delegating orchestrator is for a turn whose answer is the orchestrator's
+ * own structured judgment of what its team returned.
  *
  * ── Fail-static ───────────────────────────────────────────────────────────
  * Every failure mode here resolves to `default_route` and answers the user.

package/dist/lib/doctor.d.ts

@@ -7,7 +7,8 @@
  *   from the YAMLs and the environment: every syndicate the loader can see,
  *   every agent's model, the provider that id routes to, whether that path
  *   is funded (direct key, gateway, or local), and which declared
- *   server-side tools the path will drop. Then it says exactly what to set,
+ *   server-side tools the path will drop, and which tools need an OAuth
+ *   grant before they work (ADR 0112). Then it says exactly what to set,
  *   grouped by how much each variable unlocks.
  *
  * WHAT IT NEVER DOES:
@@ -46,6 +47,49 @@ export interface DoctorRow {
     gaps: CapabilityGap[];
 }
 export type VerdictState = 'ready' | 'ready-local' | 'via-gateway' | 'blocked';
+/**
+ * A tool that sends an OAuth token (ADR 0112): which agent holds it, the
+ * provider, and the grant. An authorization_code grant needs each user's
+ * consent before the tool works for them; a client_credentials grant needs
+ * its variables set. Variable names only, never a value.
+ */
+export interface DoctorGrant {
+    agent: string;
+    /** `openapi <spec>` or `mcp <url>`. */
+    tools: string;
+    provider: string;
+    grant: 'authorization_code' | 'client_credentials';
+    scopes: string[];
+    /** The variables the grant reads that are not set here. */
+    missingEnv: string[];
+    /** Why the operator's OAuth host allowlist refuses this grant here (ADR 0114); empty when it is permitted. */
+    hostProblems: string[];
+}
+/**
+ * The server's OAuth setup under this environment (ADR 0114): which of its
+ * variables are set, and what is wrong, names only. Present when a
+ * syndicate declares a grant or any of the variables is set.
+ */
+export interface DoctorOAuth {
+    /** Which of MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI and MELCHIZEDEK_OAUTH_HOSTS are set. */
+    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;
@@ -75,6 +119,13 @@ export interface DoctorSyndicate {
         declared: boolean;
         issue?: string;
     };
+    /** 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;
@@ -108,6 +159,47 @@ export interface DoctorResult {
     /** Every provider not on its default endpoint: a cloud platform or a proxy (ADR 0023). */
     endpoints: DoctorEndpoint[];
     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;
@@ -133,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
@@ -161,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;