melchizedek-agents 0.20.0 → 1.0.0

package/dist/lib/compile.d.ts

@@ -1,6 +1,6 @@
 /**
- * lib/compile.ts — the one YAML → agent compiler: a runtime-neutral
- * AgentSpec, and the ADK agent graph built from it.
+ * lib/compile.ts — the one YAML → agent compiler: an AgentSpec per agent,
+ * which lib/compileNative.ts turns into what the runtime runs.
  *
  * WHY this file exists:
  *   The A2A server carried this logic as two closures inside its executor,
@@ -12,44 +12,40 @@
  *   So the compiler moved here and both callers import it.
  *
  * What it does NOT own: model resolution and nested-config loading. Both are
- * injected, because the two callers differ precisely there:
- *   - the A2A server resolves `model` to a provider INSTANCE carrying the
+ * injected, because the callers differ precisely there:
+ *   - the A2A server resolves `model` to a ModelAdapter carrying the
  *     caller's BYOK key (lib/models/registry.ts resolveModel);
- *   - the observatory passes the model id through as a string (the
- *     LLMRegistry routes it) and loads nested syndicates with its
- *     per-variant overrides already applied.
+ *   - the observatory passes the model id through as a string (the loop
+ *     resolves it, lib/models/registry.ts resolveAdapter) and loads nested
+ *     syndicates with its per-variant overrides already applied.
  *
  * ── Two orchestration methods, one compiler ───────────────────────────────
- * DELEGATE (no `dispatch:` block): every subagent becomes an AgentTool on
- * the orchestrator. PLAN-DISPATCH (`dispatch:` present): the orchestrator
+ * DELEGATE (no `dispatch:` block): every subagent becomes a delegation tool
+ * on the orchestrator. PLAN-DISPATCH (`dispatch:` present): the orchestrator
  * is compiled WITHOUT subagent tools — it is a pure classifier — and the
- * caller runs `compileSubagent(route)` directly for the chosen route. Both
- * paths build subagents through the same function, so the agent a route
- * dispatches to is identical to the one DELEGATE would have wrapped.
+ * turn runner compiles the chosen route's own spec. Both paths build
+ * subagents through the same function, so the agent a route dispatches to
+ * is identical to the one DELEGATE would have delegated to.
  * Contract and rationale: lib/dispatch.ts.
  *
- * ── One spec, two runtimes (ADR 0073) ─────────────────────────────────────
- * compileSpec and compileSubagentSpec do the work every runtime shares:
- * resolve and gate the tools, append the skills index, resolve the model
- * once, build the generateContentConfig. The result is an AgentSpec.
- * lib/compileAdk.ts builds ADK's LlmAgent from it (compileGraph and
- * compileSubagent are spec + compileAdk), and lib/compileNative.ts builds
- * the native loop's NativeAgent (ADR 0045). runSyndicateTurn picks one by
- * MELCHIZEDEK_RUNTIME or its `runtime` option.
+ * ── The spec (ADR 0073, ADR 0107) ─────────────────────────────────────────
+ * compileSpec and compileSubagentSpec resolve and gate the tools, append the
+ * skills index, resolve the model once and build the generateContentConfig.
+ * The result is an AgentSpec; lib/compileNative.ts builds the loop's
+ * NativeAgent from it.
  */
-import { BaseLlm, FunctionTool } from './adkPeer.ts';
-import type { BaseTool, LlmAgent } from '@google/adk';
 import type { ReasoningSetting, SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+import type { ModelAdapter } from './models/contract.ts';
 import type { ExampleConfig } from './tools/examples.ts';
 import type { SkillsConfig } from './tools/skillToolset.ts';
 export interface CompileOptions {
     /**
-     * Turns the YAML `model` string into what LlmAgent receives. Default:
-     * identity — the string goes straight to ADK's LLMRegistry, which needs
-     * `registerAvailableProviders()` to have run (lib/models/registry.ts).
-     * The A2A server substitutes a BYOK instance factory here.
+     * Turns the YAML `model` string into what the agent runs on: a model id,
+     * or a ModelAdapter (lib/models/contract.ts). Default: identity — the id
+     * resolves through lib/models/registry.ts resolveAdapter when the agent
+     * first calls it. The A2A server substitutes a BYOK adapter factory here.
      */
-    resolveModel?: (model: string | undefined) => string | BaseLlm | undefined;
+    resolveModel?: (model: string | undefined) => string | ModelAdapter | undefined;
     /**
      * Loads a nested `yaml_reference:` syndicate. Default: `loadSyndicate(ref)`
      * with no bindings — the same call the server makes. The observatory wraps
@@ -60,12 +56,6 @@ export interface CompileOptions {
     onUnknownTool?: (name: string) => void;
     /** Progress/diagnostic line sink (nested loads, MCP discovery). */
     log?: (message: string) => void;
-    /**
-     * Node settings for an agent compiled as a workflow node (lib/workflow.ts):
-     * ADK's `retryConfig` and `timeout`, which an LlmAgent takes only at
-     * construction. Called with the agent's name; undefined means none.
-     */
-    nodeConfig?: (agentName: string) => Record<string, unknown> | undefined;
 }
 export { REASONING_BUDGETS, reasoningConfig } from './models/reasoning.ts';
 /**
@@ -79,36 +69,17 @@ export declare function withReasoning(agent: {
     reasoning?: ReasoningSetting;
     generateContentConfig?: object;
 }, model: string | undefined): Record<string, unknown> | undefined;
-/** An agent's `context:` block and its default, owned by the native compactor (ADR 0033); compileAdk hands the same values to ADK's. */
+/** An agent's `context:` block and its default, owned by the compactor (ADR 0033). */
 export type { ContextConfig } from './runtime/native/compaction.ts';
 import type { ContextConfig } from './runtime/native/compaction.ts';
 export { DEFAULT_KEEP_RECENT_EVENTS } from './runtime/native/compaction.ts';
-/**
- * A copy of a FunctionTool that runs only after a person approves the call
- * (ADR 0028). ADK's own gate does the work: the call raises an
- * `adk_request_confirmation` interrupt pinning the call and its arguments,
- * and only an approval bound to that exact call runs it. The original stays
- * ungated for every other agent that lists the same tool.
- */
-export declare function requireApprovalOn(tool: FunctionTool): FunctionTool;
-/**
- * A copy of an ADK BaseTool that runs only after a person approves the
- * call: the same confirmation interrupt FunctionTool's own gate raises, so
- * the turn pauses and resumes exactly as ADR 0028 says. The engine no
- * longer uses it: an OpenAPI operation is a FunctionTool over an own Tool
- * (ADR 0067) and takes requireApprovalOn like every registry tool.
- * @deprecated Gate a FunctionTool with requireApprovalOn, or an own Tool
- * with requireApproval (lib/tools/tool.ts).
- */
-export declare function requireApprovalOnBaseTool<T extends BaseTool>(tool: T): T;
 /** True when any agent of a syndicate may pause for approval: a gated tool, or skill scripts. */
 export declare function declaresApprovals(config: SyndicateYamlConfig): boolean;
 export type { ExampleConfig };
 /**
- * An agent's `examples:` as the ADK tool for their InstructionTool
- * (lib/tools/examples.ts): never called by the model, it adds the exchanges
- * to every request's instruction as few-shot examples, in the words ADK's
- * ExampleTool used.
+ * An agent's `examples:` as their InstructionTool (lib/tools/examples.ts):
+ * never called by the model, it adds the exchanges to every request's
+ * instruction as few-shot examples, in the words ADK's ExampleTool used.
  */
 export declare function examplesTool(examples: ExampleConfig[] | undefined): unknown[];
 /** True when a turn running this agent directly may pause for a person (ADR 0028). */
@@ -118,10 +89,9 @@ export declare function agentGates(agent: {
 } | undefined): boolean;
 /**
  * One entry of an agent's tool list, in the order the model sees it.
- * `tool` is a resolved tool as the registry gives it: during the dual
- * period an ADK object that carries its own Tool or InstructionTool
- * (lib/tools/adkTool.ts), an MCP tool or the skills toolset, gated by
- * require_approval where the YAML says so. `agent` is a delegated subagent
+ * `tool` is a resolved tool as the registry gives it: an own Tool,
+ * InstructionTool, NativeToolMarker or Toolset (lib/tools/tool.ts), gated
+ * by require_approval where the YAML says so. `agent` is a delegated subagent
  * (DELEGATE mode), `remote` a subagent served over A2A, `workflow` a
  * `yaml_reference` to a workflow syndicate, whose whole graph is the tool
  * (ADR 0098).
@@ -142,11 +112,10 @@ export type SpecTool = {
     workflow: WorkflowSpec;
 };
 /**
- * A workflow syndicate, compiled for either runtime: lib/workflow.ts builds
- * ADK's Workflow from it, lib/compileNative.ts the native walk's graph and
- * agents. Nested as a subagent (a `yaml_reference` in DELEGATE mode), the
- * graph runs under the entry's name and description, and that name is the
- * root of every node path, as ADK names a Workflow's nodes after it.
+ * A workflow syndicate, compiled: lib/compileNative.ts builds the walk's
+ * graph and agents from it. Nested as a subagent (a `yaml_reference` in
+ * DELEGATE mode), the graph runs under the entry's name and description,
+ * and that name is the root of every node path.
  */
 export interface WorkflowSpec {
     /** The workflow's name: the syndicate's, or the subagent entry's when nested. */
@@ -160,12 +129,20 @@ export interface WorkflowSpec {
         yaml: SubagentYamlConfig;
         spec: AgentSpec;
     }>;
+    /**
+     * Every node that is a `yaml_reference` to a workflow syndicate, with its
+     * YAML entry: the nested graph under the entry's name (ADR 0106). The
+     * walk runs it as the node, on its own child session.
+     */
+    workflows: Array<{
+        yaml: SubagentYamlConfig;
+        workflow: WorkflowSpec;
+    }>;
     /** The registry entry for a tool node's tool name, or undefined (CompileOptions.onUnknownTool applies). */
     resolveTool: (name: string) => unknown;
 }
 /**
- * One YAML agent, compiled, for either runtime: what lib/compileAdk.ts
- * turns into ADK's LlmAgent and lib/compileNative.ts into the native loop's
+ * One YAML agent, compiled: what lib/compileNative.ts turns into the loop's
  * NativeAgent. Built once per agent by compileSpec and compileSubagentSpec:
  * the tools resolved (OpenAPI operations built, MCP tools listed) and
  * gated, the skills index appended to the instruction, the model resolved
@@ -181,14 +158,14 @@ export interface AgentSpec {
     resolvedModel?: unknown;
     /** The id the agent runs on: the YAML's, else the resolved adapter's. */
     modelId?: string;
-    /** `fallback_model:`, unresolved: each runtime resolves it where it calls it. */
+    /** `fallback_model:`, unresolved: the loop resolves it where it calls it. */
     fallbackModel?: string;
     /** The YAML instruction, with the skills index appended when the agent has `skills:`. */
     instruction: string;
     globalInstruction?: string;
     tools: SpecTool[];
     outputSchema?: Record<string, unknown>;
-    /** The YAML's config with `reasoning:` mapped in and server-side tool invocations on, as both runtimes send it. */
+    /** The YAML's config with `reasoning:` mapped in and server-side tool invocations on. */
     generateContentConfig: Record<string, unknown>;
     includeContents?: 'default' | 'none';
     outputKey?: string;
@@ -209,33 +186,46 @@ export interface AgentSpec {
  *
  * 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, on both runtimes.
+ * `ask_user` node is refused by name here.
  */
 export declare function compileWorkflowSpec(config: SyndicateYamlConfig, opts?: CompileOptions, name?: string, description?: string, ref?: string): Promise<WorkflowSpec>;
+/** Every agent spec a workflow runs, its nested workflow nodes' agents included, for one adapter lookup (nativeAdapterFor). */
+export declare function workflowAgentSpecs(spec: WorkflowSpec): AgentSpec[];
+/** A subagent entry, compiled: one agent, or a nested workflow syndicate's whole graph (ADR 0098, ADR 0106). */
+export type EntrySpec = {
+    kind: 'agent';
+    spec: AgentSpec;
+} | {
+    kind: 'workflow';
+    workflow: WorkflowSpec;
+};
+/**
+ * A subagent entry as what it runs: an inline agent or a nested syndicate's
+ * orchestrator as one agent, or a `yaml_reference` to a workflow syndicate
+ * 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).
+ */
+export declare function compileEntrySpec(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<EntrySpec>;
+/**
+ * The names of a syndicate's subagent entries that are `yaml_reference`s to
+ * a workflow syndicate. Loads each reference once and compiles nothing, so a
+ * runtime can refuse what it cannot run before the session is touched.
+ */
+export declare function workflowEntryNames(config: SyndicateYamlConfig, opts?: CompileOptions): string[];
 /**
  * The spec of ONE agent from a subagent entry. A `yaml_reference` entry is
- * the nested syndicate's whole graph under this entry's name and
- * description, so the parent sees one tool (or one route) either way.
+ * the nested syndicate's orchestrator under this entry's name and
+ * description, its own subagents delegated to as in any DELEGATE graph. A
+ * `yaml_reference` to a workflow syndicate has no one agent to build: it
+ * runs as its whole graph (compileEntrySpec), and is refused here by name.
  */
 export declare function compileSubagentSpec(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<AgentSpec>;
 /**
  * The spec of a syndicate's orchestrator. In DELEGATE mode its subagents
  * come first among its tools, as delegations; in PLAN-DISPATCH mode it gets
- * none (ADK refuses outputSchema + AgentTool on one agent — see
+ * none (a classifier answers with its outputSchema — see
  * config/agents/critic.yaml), and the caller dispatches to a route's own
  * spec itself.
  */
 export declare function compileSpec(config: SyndicateYamlConfig, opts?: CompileOptions, overrideName?: string, overrideDescription?: string): Promise<AgentSpec>;
-/**
- * Builds ONE runnable ADK agent from a subagent entry: its spec, as
- * lib/compileAdk.ts builds it. A workflow node's settings
- * (CompileOptions.nodeConfig) apply to a local agent, not to a nested
- * syndicate's orchestrator.
- */
-export declare function compileSubagent(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<LlmAgent>;
-/**
- * Compiles a syndicate's orchestrator for the ADK runtime. In DELEGATE mode
- * its subagents are attached as AgentTools; in PLAN-DISPATCH mode it gets
- * none, and the caller dispatches to `compileSubagent(route)` itself.
- */
-export declare function compileGraph(config: SyndicateYamlConfig, opts?: CompileOptions, overrideName?: string, overrideDescription?: string): Promise<LlmAgent>;

package/dist/lib/compile.js

@@ -1,6 +1,6 @@
 /**
- * lib/compile.ts — the one YAML → agent compiler: a runtime-neutral
- * AgentSpec, and the ADK agent graph built from it.
+ * lib/compile.ts — the one YAML → agent compiler: an AgentSpec per agent,
+ * which lib/compileNative.ts turns into what the runtime runs.
  *
  * WHY this file exists:
  *   The A2A server carried this logic as two closures inside its executor,
@@ -12,34 +12,29 @@
  *   So the compiler moved here and both callers import it.
  *
  * What it does NOT own: model resolution and nested-config loading. Both are
- * injected, because the two callers differ precisely there:
- *   - the A2A server resolves `model` to a provider INSTANCE carrying the
+ * injected, because the callers differ precisely there:
+ *   - the A2A server resolves `model` to a ModelAdapter carrying the
  *     caller's BYOK key (lib/models/registry.ts resolveModel);
- *   - the observatory passes the model id through as a string (the
- *     LLMRegistry routes it) and loads nested syndicates with its
- *     per-variant overrides already applied.
+ *   - the observatory passes the model id through as a string (the loop
+ *     resolves it, lib/models/registry.ts resolveAdapter) and loads nested
+ *     syndicates with its per-variant overrides already applied.
  *
  * ── Two orchestration methods, one compiler ───────────────────────────────
- * DELEGATE (no `dispatch:` block): every subagent becomes an AgentTool on
- * the orchestrator. PLAN-DISPATCH (`dispatch:` present): the orchestrator
+ * DELEGATE (no `dispatch:` block): every subagent becomes a delegation tool
+ * on the orchestrator. PLAN-DISPATCH (`dispatch:` present): the orchestrator
  * is compiled WITHOUT subagent tools — it is a pure classifier — and the
- * caller runs `compileSubagent(route)` directly for the chosen route. Both
- * paths build subagents through the same function, so the agent a route
- * dispatches to is identical to the one DELEGATE would have wrapped.
+ * turn runner compiles the chosen route's own spec. Both paths build
+ * subagents through the same function, so the agent a route dispatches to
+ * is identical to the one DELEGATE would have delegated to.
  * Contract and rationale: lib/dispatch.ts.
  *
- * ── One spec, two runtimes (ADR 0073) ─────────────────────────────────────
- * compileSpec and compileSubagentSpec do the work every runtime shares:
- * resolve and gate the tools, append the skills index, resolve the model
- * once, build the generateContentConfig. The result is an AgentSpec.
- * lib/compileAdk.ts builds ADK's LlmAgent from it (compileGraph and
- * compileSubagent are spec + compileAdk), and lib/compileNative.ts builds
- * the native loop's NativeAgent (ADR 0045). runSyndicateTurn picks one by
- * MELCHIZEDEK_RUNTIME or its `runtime` option.
+ * ── The spec (ADR 0073, ADR 0107) ─────────────────────────────────────────
+ * compileSpec and compileSubagentSpec resolve and gate the tools, append the
+ * skills index, resolve the model once and build the generateContentConfig.
+ * The result is an AgentSpec; lib/compileNative.ts builds the loop's
+ * NativeAgent from it.
  */
-import { BaseLlm, FunctionTool } from './adkPeer.js';
 import { relative } from 'node:path';
-import { compileAdk } from './compileAdk.js';
 import { isDispatchSyndicate } from './dispatch.js';
 import { isWorkflowSyndicate, nodeKind } from './workflowConfig.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
@@ -47,12 +42,12 @@ import { REASONING_OLDER_SPELLING } from './syndicateSchema.js';
 import { reasoningConfig } from './models/reasoning.js';
 import { resolveTools as resolveNamedTools } from './toolRegistry.js';
 import { createMcpTools } from './tools/mcpToolFactory.js';
-import { toAdkInstructionTool, toAdkToolset } from './tools/adkTool.js';
+import { requireApproval, toolOf } from './tools/tool.js';
 import { examplesInstructionTool } from './tools/examples.js';
 import { capabilitySummary, describeCapabilities } from './models/capabilities.js';
 import { buildSkillHarness } from './tools/skillToolset.js';
 import { buildOpenApiTools, namesTool, openApiOperationId } from './tools/openapiTools.js';
-/** generateContentConfig as every entrypoint has always sent it to ADK. */
+/** generateContentConfig as every entrypoint sends it: server-side tool invocations on. */
 function withServerSideToolInvocations(generateContentConfig) {
     const cfg = (generateContentConfig ?? {});
     return {
@@ -65,7 +60,7 @@ function withServerSideToolInvocations(generateContentConfig) {
 }
 // ── Reasoning (ADR 0047) ─────────────────────────────────────────────────────
 // REASONING_BUDGETS and reasoningConfig live in lib/models/reasoning.ts, so a
-// model adapter can map `reasoning:` without importing the compiler (and ADK).
+// model adapter can map `reasoning:` without importing the compiler.
 export { REASONING_BUDGETS, reasoningConfig } from './models/reasoning.js';
 /**
  * An agent's generateContentConfig with its `reasoning:` key mapped in for
@@ -85,7 +80,12 @@ export function withReasoning(agent, model) {
 }
 /** The model id an agent runs on, from its YAML or its resolved adapter. */
 function modelIdOf(yamlModel, resolved) {
-    return yamlModel ?? (typeof resolved === 'string' ? resolved : resolved instanceof BaseLlm ? resolved.model : undefined);
+    if (yamlModel !== undefined)
+        return yamlModel;
+    if (typeof resolved === 'string')
+        return resolved;
+    const own = resolved && typeof resolved === 'object' ? resolved.model : undefined;
+    return typeof own === 'string' ? own : undefined;
 }
 export { DEFAULT_KEEP_RECENT_EVENTS } from './runtime/native/compaction.js';
 /**
@@ -103,44 +103,6 @@ function logCapabilities(opts, agentName, model, tools) {
     if (line)
         opts.log(`capability · ${line}`);
 }
-/**
- * A copy of a FunctionTool that runs only after a person approves the call
- * (ADR 0028). ADK's own gate does the work: the call raises an
- * `adk_request_confirmation` interrupt pinning the call and its arguments,
- * and only an approval bound to that exact call runs it. The original stays
- * ungated for every other agent that lists the same tool.
- */
-export function requireApprovalOn(tool) {
-    const gated = Object.create(tool);
-    Object.defineProperty(gated, 'requireConfirmation', { value: true, enumerable: false });
-    return gated;
-}
-/**
- * A copy of an ADK BaseTool that runs only after a person approves the
- * call: the same confirmation interrupt FunctionTool's own gate raises, so
- * the turn pauses and resumes exactly as ADR 0028 says. The engine no
- * longer uses it: an OpenAPI operation is a FunctionTool over an own Tool
- * (ADR 0067) and takes requireApprovalOn like every registry tool.
- * @deprecated Gate a FunctionTool with requireApprovalOn, or an own Tool
- * with requireApproval (lib/tools/tool.ts).
- */
-export function requireApprovalOnBaseTool(tool) {
-    const gated = Object.create(tool);
-    Object.defineProperty(gated, 'runAsync', {
-        value: async (request) => {
-            const ctx = request.toolContext;
-            if (!ctx.toolConfirmation) {
-                ctx.requestConfirmation({ hint: `Approval is required before ${tool.name} runs.`, payload: request.args });
-                ctx.actions.skipSummarization = true;
-                return { error: 'This call requires approval, please approve or reject.' };
-            }
-            if (!ctx.toolConfirmation.confirmed)
-                return { error: 'This call was rejected.' };
-            return tool.runAsync(request);
-        },
-    });
-    return gated;
-}
 function gateTools(tools, names, agentName) {
     if (!names?.length)
         return tools;
@@ -155,11 +117,12 @@ function gateTools(tools, names, agentName) {
         if (!match)
             return t;
         wanted.delete(match);
-        // An OpenAPI operation is a FunctionTool over an own Tool (ADR 0067): one gate for both.
-        if (!(t instanceof FunctionTool)) {
-            throw new Error(`${agentName}: '${name}' cannot require approval — only function tools from the registry and OpenAPI operations can be gated (ADR 0028).`);
+        // A registry tool, an OpenAPI operation and an MCP tool are own Tools (ADR 0067): one gate for all.
+        const own = toolOf(t);
+        if (!own) {
+            throw new Error(`${agentName}: '${name}' cannot require approval — only function tools from the registry, OpenAPI operations and MCP tools can be gated (ADR 0028).`);
         }
-        return requireApprovalOn(t);
+        return requireApproval(own);
     });
     if (wanted.size) {
         // Fail closed: a gate on a tool that did not resolve must not leave an
@@ -173,14 +136,13 @@ export function declaresApprovals(config) {
     return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s));
 }
 /**
- * An agent's `examples:` as the ADK tool for their InstructionTool
- * (lib/tools/examples.ts): never called by the model, it adds the exchanges
- * to every request's instruction as few-shot examples, in the words ADK's
- * ExampleTool used.
+ * An agent's `examples:` as their InstructionTool (lib/tools/examples.ts):
+ * never called by the model, it adds the exchanges to every request's
+ * instruction as few-shot examples, in the words ADK's ExampleTool used.
  */
 export function examplesTool(examples) {
     const tool = examplesInstructionTool(examples);
-    return tool ? [toAdkInstructionTool(tool)] : [];
+    return tool ? [tool] : [];
 }
 async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
     const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
@@ -233,8 +195,7 @@ async function withSkills(instruction, tools, skills, agentName, opts) {
     opts.log?.(`skills · ${agentName}: ${count} skill${count === 1 ? '' : 's'} from ${skills.dir}${skills.scripts === 'local' ? ' · scripts run after approval' : ''}`);
     for (const problem of harness.problems)
         opts.log?.(`⚠ skills · ${skills.dir}: not loaded — ${problem}`);
-    // The ADK face of the engine's own toolset; compileNative reads the toolset back (toolsetOf).
-    return { instruction: `${instruction.trimEnd()}\n\n${harness.instruction}`, tools: [...tools, toAdkToolset(harness.toolset)] };
+    return { instruction: `${instruction.trimEnd()}\n\n${harness.instruction}`, tools: [...tools, harness.toolset] };
 }
 /** True when a turn running this agent directly may pause for a person (ADR 0028). */
 export function agentGates(agent) {
@@ -320,7 +281,7 @@ function loadNestedSyndicate(ref, opts) {
  *
  * 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, on both runtimes.
+ * `ask_user` node is refused by name here.
  */
 export async function compileWorkflowSpec(config, opts = {}, name, description, ref) {
     if (!isWorkflowSyndicate(config))
@@ -328,26 +289,72 @@ export async function compileWorkflowSpec(config, opts = {}, name, description,
     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 as a subagent (${name}) cannot carry to its caller; run the workflow as its own syndicate, or remove the node.`);
+            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 = [];
     for (const yaml of [{ description: '', ...config.orchestrator }, ...(config.subagents ?? [])]) {
-        agents.push({ yaml, spec: await compileSubagentSpec(yaml, opts) });
+        const entry = await compileEntrySpec(yaml, opts);
+        if (entry.kind === 'workflow')
+            workflows.push({ yaml, workflow: entry.workflow });
+        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).
+    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 (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.`);
+        }
     }
     return {
         name: workflowName,
         description: description ?? '',
         config: { ...config, syndicate_name: workflowName },
         agents,
+        workflows,
         resolveTool: (tool) => resolveNamedTools([tool], opts.onUnknownTool)[0],
     };
 }
+/** Every agent spec a workflow runs, its nested workflow nodes' agents included, for one adapter lookup (nativeAdapterFor). */
+export function workflowAgentSpecs(spec) {
+    return [...spec.agents.map((a) => a.spec), ...spec.workflows.flatMap((w) => workflowAgentSpecs(w.workflow))];
+}
+/**
+ * A subagent entry as what it runs: an inline agent or a nested syndicate's
+ * orchestrator as one agent, or a `yaml_reference` to a workflow syndicate
+ * 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).
+ */
+export async function compileEntrySpec(subCfg, opts = {}) {
+    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: 'agent', spec: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
+    }
+    return { kind: 'agent', spec: await compileSubagentSpec(subCfg, opts) };
+}
+/**
+ * The names of a syndicate's subagent entries that are `yaml_reference`s to
+ * a workflow syndicate. Loads each reference once and compiles nothing, so a
+ * runtime can refuse what it cannot run before the session is touched.
+ */
+export function workflowEntryNames(config, opts = {}) {
+    const load = opts.loadNested ?? (config.bundled_references ? nestedLoader(config) : loadSyndicate);
+    return (config.subagents ?? []).filter((s) => !!s.yaml_reference && !s.a2a_agent_url && isWorkflowSyndicate(load(s.yaml_reference))).map((s) => s.name);
+}
 /**
  * The spec of ONE agent from a subagent entry. A `yaml_reference` entry is
- * the nested syndicate's whole graph under this entry's name and
- * description, so the parent sees one tool (or one route) either way.
+ * the nested syndicate's orchestrator under this entry's name and
+ * description, its own subagents delegated to as in any DELEGATE graph. A
+ * `yaml_reference` to a workflow syndicate has no one agent to build: it
+ * runs as its whole graph (compileEntrySpec), and is refused here by name.
  */
 export async function compileSubagentSpec(subCfg, opts = {}) {
     if (subCfg.a2a_agent_url) {
@@ -358,7 +365,11 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
     }
     if (subCfg.yaml_reference) {
         const nestedOpts = nestedOptions(subCfg.yaml_reference, opts);
-        return compileSpec(loadNestedSyndicate(subCfg.yaml_reference, nestedOpts), nestedOpts, subCfg.name, subCfg.description);
+        const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts);
+        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).`);
+        }
+        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);
@@ -368,7 +379,7 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
 /**
  * The spec of a syndicate's orchestrator. In DELEGATE mode its subagents
  * come first among its tools, as delegations; in PLAN-DISPATCH mode it gets
- * none (ADK refuses outputSchema + AgentTool on one agent — see
+ * none (a classifier answers with its outputSchema — see
  * config/agents/critic.yaml), and the caller dispatches to a route's own
  * spec itself.
  */
@@ -377,14 +388,12 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
     if (config.bundled_references && !opts.loadNested)
         opts = { ...opts, loadNested: nestedLoader(config) };
     // A graph has no orchestrator-with-tools shape to build: its agents are
-    // nodes (lib/workflow.ts). A delegated yaml_reference to one runs the whole
-    // graph as the tool (nestedWorkflowSpec, ADR 0098); as a dispatch route or
-    // a workflow node it is still its orchestrator alone.
-    if (config.workflow && !overrideName) {
-        throw new Error(`${config.syndicate_name}: a workflow syndicate is compiled with compileWorkflow (lib/workflow.ts), not compileGraph`);
+    // nodes (lib/workflow.ts). A yaml_reference to one runs the whole graph, as
+    // a delegated tool (ADR 0098), a dispatch route or a workflow node (ADR
+    // 0106), through compileEntrySpec, which never compiles one here.
+    if (config.workflow) {
+        throw new Error(`${config.syndicate_name}: a workflow syndicate is compiled with compileWorkflowSpec, not compileSpec`);
     }
-    if (config.workflow)
-        opts.log?.(`${config.syndicate_name}: a dispatch route or a workflow node, so only its orchestrator runs (a delegated subagent runs the whole graph)`);
     const delegated = isDispatchSyndicate(config)
         ? []
         : await Promise.all((config.subagents ?? []).map(async (subCfg) => {
@@ -392,14 +401,8 @@ 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 };
             }
-            if (subCfg.yaml_reference) {
-                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: 'agent', agent: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
-            }
-            return { kind: 'agent', agent: await compileSubagentSpec(subCfg, opts) };
+            const entry = await compileEntrySpec(subCfg, opts);
+            return entry.kind === 'workflow' ? entry : { kind: 'agent', agent: entry.spec };
         }));
     const name = overrideName || config.orchestrator.name;
     // Orchestrator tools are registry names only — no entrypoint has ever
@@ -411,22 +414,3 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
     logCapabilities(opts, name, config.orchestrator.model, config.orchestrator.tools);
     return specOf(config.orchestrator, name, overrideDescription || config.orchestrator.description, instruction, [...delegated, ...asTools(tools)], opts);
 }
-// ── The ADK runtime's agents (lib/compileAdk.ts) ─────────────────────────────
-/**
- * Builds ONE runnable ADK agent from a subagent entry: its spec, as
- * lib/compileAdk.ts builds it. A workflow node's settings
- * (CompileOptions.nodeConfig) apply to a local agent, not to a nested
- * syndicate's orchestrator.
- */
-export async function compileSubagent(subCfg, opts = {}) {
-    const spec = await compileSubagentSpec(subCfg, opts);
-    return compileAdk(spec, opts, subCfg.yaml_reference ? {} : (opts.nodeConfig?.(subCfg.name) ?? {}));
-}
-/**
- * Compiles a syndicate's orchestrator for the ADK runtime. In DELEGATE mode
- * its subagents are attached as AgentTools; in PLAN-DISPATCH mode it gets
- * none, and the caller dispatches to `compileSubagent(route)` itself.
- */
-export async function compileGraph(config, opts = {}, overrideName, overrideDescription) {
-    return compileAdk(await compileSpec(config, opts, overrideName, overrideDescription), opts);
-}