melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/compile.js

@@ -1,5 +1,6 @@
 /**
- * lib/compile.ts — the one YAML → ADK agent-graph compiler.
+ * lib/compile.ts — the one YAML → agent compiler: a runtime-neutral
+ * AgentSpec, and the ADK agent graph built from it.
  *
  * WHY this file exists:
  *   The A2A server carried this logic as two closures inside its executor,
@@ -26,19 +27,31 @@
  * paths build subagents through the same function, so the agent a route
  * dispatches to is identical to the one DELEGATE would have wrapped.
  * 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.
  */
-import { AgentTool, BaseLlm, BuiltInCodeExecutor, ExampleTool, FunctionTool, LLMRegistry, LlmAgent, LlmSummarizer, TokenBasedContextCompactor } from '@google/adk';
+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';
+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 { examplesInstructionTool } from './tools/examples.js';
 import { capabilitySummary, describeCapabilities } from './models/capabilities.js';
-import { FallbackLlm } from './models/fallback.js';
-import { resolveModel as resolveRegistryModel } from './models/registry.js';
-import { remoteAgentTool } from './a2a/remoteAgent.js';
 import { buildSkillHarness } from './tools/skillToolset.js';
-import { buildOpenApiTools, isOpenApiTool, namesTool } from './tools/openapiTools.js';
+import { buildOpenApiTools, namesTool, openApiOperationId } from './tools/openapiTools.js';
 /** generateContentConfig as every entrypoint has always sent it to ADK. */
 function withServerSideToolInvocations(generateContentConfig) {
     const cfg = (generateContentConfig ?? {});
@@ -50,59 +63,31 @@ 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).
+export { REASONING_BUDGETS, reasoningConfig } from './models/reasoning.js';
 /**
- * The LlmAgent fields a YAML agent may set beyond model, instruction, tools
- * and schemas. The schema reference (config/agents/syndicateSchema.yaml)
- * documents each as mapping 1:1 to its ADK counterpart; before this they
- * were parsed and silently dropped, so `includeContents: none` — which the
- * intake template relies on so that a document never sees an earlier one —
- * changed nothing. Only fields the YAML sets are passed, so ADK's defaults
- * stay in force otherwise.
- */
-function passthroughFields(cfg) {
-    const out = {};
-    if (cfg.includeContents !== undefined)
-        out.includeContents = cfg.includeContents;
-    if (cfg.outputKey !== undefined)
-        out.outputKey = cfg.outputKey;
-    if (cfg.globalInstruction !== undefined)
-        out.globalInstruction = cfg.globalInstruction;
-    if (cfg.disallowTransferToParent !== undefined)
-        out.disallowTransferToParent = cfg.disallowTransferToParent;
-    if (cfg.disallowTransferToPeers !== undefined)
-        out.disallowTransferToPeers = cfg.disallowTransferToPeers;
-    return out;
-}
-export const DEFAULT_KEEP_RECENT_EVENTS = 6;
-/**
- * The LlmAgent fields the engine builds from YAML rather than passing
- * through (ADR 0033): `code_execution: gemini` (Gemini's server-side
- * sandbox runs the model's Python; nothing runs on this host), `context:`
- * (ADK's token-based compactor with an LLM summarizer, so a long
- * conversation is summarized instead of overflowing the window), and
- * `mode: task` (the agent works until it calls finish_task; on a workflow
- * node, its arguments become the node's output).
+ * An agent's generateContentConfig with its `reasoning:` key mapped in for
+ * the model it runs on. Unchanged (the same object) when the agent sets no
+ * `reasoning`. The loader refuses `reasoning` next to the older spelling;
+ * this refuses it too, for a config built in code.
  */
-function executionFields(cfg, opts) {
-    const out = {};
-    if (cfg.code_execution === 'gemini')
-        out.codeExecutor = new BuiltInCodeExecutor();
-    if (cfg.mode)
-        out.mode = cfg.mode;
-    if (cfg.context) {
-        const resolve = opts.resolveModel ?? ((m) => m);
-        const summaryModel = resolve(cfg.context.summary_model ?? cfg.model);
-        const llm = typeof summaryModel === 'string' || !summaryModel ? LLMRegistry.newLlm(String(summaryModel ?? cfg.model)) : summaryModel;
-        out.contextCompactors = [
-            new TokenBasedContextCompactor({
-                tokenThreshold: cfg.context.compact_after_tokens,
-                eventRetentionSize: cfg.context.keep_recent_events ?? DEFAULT_KEEP_RECENT_EVENTS,
-                summarizer: new LlmSummarizer({ llm }),
-            }),
-        ];
+export function withReasoning(agent, model) {
+    const cfg = agent.generateContentConfig;
+    if (agent.reasoning === undefined)
+        return cfg;
+    const clash = REASONING_OLDER_SPELLING.filter((k) => cfg?.[k] !== undefined);
+    if (clash.length) {
+        throw new Error(`${agent.name ?? 'agent'}: reasoning cannot be combined with ${clash.map((k) => `generateContentConfig.${k}`).join(' or ')}; reasoning replaces it (ADR 0047)`);
     }
-    return out;
+    return { ...cfg, ...reasoningConfig(model ?? '', agent.reasoning) };
 }
+/** 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);
+}
+export { DEFAULT_KEEP_RECENT_EVENTS } from './runtime/native/compaction.js';
 /**
  * Says, once per compiled agent, what its resolved path cannot honour — a
  * dropped server-side tool, a gateway stand-in, or no route at all. Quiet
@@ -131,9 +116,13 @@ export function requireApprovalOn(tool) {
     return gated;
 }
 /**
- * A copy of an OpenAPI tool (lib/tools/openapiTools.ts) 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.
+ * 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);
@@ -157,17 +146,16 @@ function gateTools(tools, names, agentName) {
         return tools;
     const wanted = new Set(names);
     const out = tools.map((t) => {
-        const tool = t;
-        const name = tool?.name;
+        const name = t?.name;
         if (!name)
             return t;
         // An OpenAPI operation may be named as the YAML named it (its operationId).
-        const match = [...wanted].find((w) => w === name || (isOpenApiTool(t) && namesTool(w, { name, operation: tool.operation })));
+        const operationId = openApiOperationId(t);
+        const match = [...wanted].find((w) => w === name || (operationId !== undefined && namesTool(w, { name, operation: { operationId } })));
         if (!match)
             return t;
         wanted.delete(match);
-        if (isOpenApiTool(t))
-            return requireApprovalOnBaseTool(t);
+        // 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).`);
         }
@@ -185,27 +173,14 @@ export function declaresApprovals(config) {
     return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s));
 }
 /**
- * ADK's ExampleTool from YAML pairs: never called by the model, it adds the
- * exchanges to every request's instruction as few-shot examples.
+ * 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.
  */
 export function examplesTool(examples) {
-    if (!examples?.length)
-        return [];
-    return [
-        new ExampleTool(examples.map((e) => ({ input: { role: 'user', parts: [{ text: e.input }] }, output: [{ role: 'model', parts: [{ text: e.output }] }] }))),
-    ];
-}
-/**
- * An agent with `fallback_model:` gets its model wrapped (lib/models/fallback.ts):
- * the fallback answers a provider-side failure, and a provider that keeps
- * failing is skipped for a cooldown. A model id string is resolved to its
- * adapter first, so the wrapper always holds two adapters.
- */
-function withFallback(primary, fallbackId, resolve, opts) {
-    if (!fallbackId)
-        return primary;
-    const asLlm = (m) => (m instanceof BaseLlm ? m : resolveRegistryModel(String(m)));
-    return new FallbackLlm(asLlm(primary), asLlm(resolve(fallbackId)), opts.log ?? ((m) => console.warn(m)));
+    const tool = examplesInstructionTool(examples);
+    return tool ? [toAdkInstructionTool(tool)] : [];
 }
 async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
     const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
@@ -258,94 +233,200 @@ 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}`);
-    return { instruction: `${instruction.trimEnd()}\n\n${harness.instruction}`, tools: [...tools, harness.toolset] };
+    // 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)] };
 }
 /** True when a turn running this agent directly may pause for a person (ADR 0028). */
 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);
+    const spec = {
+        name,
+        instruction,
+        tools,
+        resolvedModel,
+        generateContentConfig: withServerSideToolInvocations(withReasoning(yaml, modelId)),
+    };
+    if (description !== undefined)
+        spec.description = description;
+    if (yaml.model !== undefined)
+        spec.model = yaml.model;
+    if (modelId !== undefined)
+        spec.modelId = modelId;
+    if (yaml.fallback_model)
+        spec.fallbackModel = yaml.fallback_model;
+    if (yaml.outputSchema)
+        spec.outputSchema = yaml.outputSchema;
+    if (yaml.includeContents !== undefined)
+        spec.includeContents = yaml.includeContents;
+    if (yaml.outputKey !== undefined)
+        spec.outputKey = yaml.outputKey;
+    if (yaml.globalInstruction !== undefined)
+        spec.globalInstruction = yaml.globalInstruction;
+    if (yaml.disallowTransferToParent !== undefined)
+        spec.disallowTransferToParent = yaml.disallowTransferToParent;
+    if (yaml.disallowTransferToPeers !== undefined)
+        spec.disallowTransferToPeers = yaml.disallowTransferToPeers;
+    if (yaml.code_execution)
+        spec.codeExecution = yaml.code_execution;
+    if (yaml.context)
+        spec.context = yaml.context;
+    if (yaml.mode)
+        spec.mode = yaml.mode;
+    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. */
+const MAX_NESTING_DEPTH = 16;
 /**
- * Builds ONE runnable agent from a subagent entry. A `yaml_reference` entry
- * compiles the nested syndicate's whole graph under this entry's name and
+ * The options a nested `ref` compiles with: `opts` and the chain of
+ * references above it. A reference already on the chain (a syndicate that
+ * reaches itself) or a chain past MAX_NESTING_DEPTH is refused by name (WS5-5,
+ * ADR 0101): the compile would otherwise recurse until the stack gave out,
+ * which took the process with it.
+ */
+function nestedOptions(ref, opts) {
+    const chain = (opts[NESTING] ?? []);
+    if (chain.includes(ref))
+        throw new Error(`${ref}: a nested syndicate reaches itself (${[...chain, ref].join(' → ')}); a yaml_reference chain must end.`);
+    if (chain.length >= MAX_NESTING_DEPTH)
+        throw new Error(`${ref}: nested syndicates go deeper than ${MAX_NESTING_DEPTH} levels (${[...chain, ref].join(' → ')}).`);
+    return { ...opts, [NESTING]: [...chain, ref] };
+}
+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 nested;
+}
+/**
+ * The spec of a workflow syndicate: every agent through compileSubagentSpec
+ * (the orchestrator first, as a node like any other), and the registry's
+ * 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, on both runtimes.
+ */
+export async function compileWorkflowSpec(config, opts = {}, name, description, ref) {
+    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 as a subagent (${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 = [];
+    for (const yaml of [{ description: '', ...config.orchestrator }, ...(config.subagents ?? [])]) {
+        agents.push({ yaml, spec: await compileSubagentSpec(yaml, opts) });
+    }
+    return {
+        name: workflowName,
+        description: description ?? '',
+        config: { ...config, syndicate_name: workflowName },
+        agents,
+        resolveTool: (tool) => resolveNamedTools([tool], opts.onUnknownTool)[0],
+    };
+}
+/**
+ * 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.
  */
-export async function compileSubagent(subCfg, opts = {}) {
+export async function compileSubagentSpec(subCfg, opts = {}) {
     if (subCfg.a2a_agent_url) {
         // A remote agent has its own model and prompt on its own server; there
         // is no local agent to build. It is reached as a delegation tool
-        // (compileGraph) or a dispatch route (lib/runtime/syndicateTurn.ts).
+        // (compileSpec) or a dispatch route (lib/runtime/syndicateTurn.ts).
         throw new Error(`'${subCfg.name}' is a remote A2A agent (a2a_agent_url) and has no local agent to compile.`);
     }
     if (subCfg.yaml_reference) {
-        opts.log?.(`Loading nested syndicate: ${subCfg.yaml_reference}`);
-        const nested = (opts.loadNested ?? loadSyndicate)(subCfg.yaml_reference);
-        if (declaresApprovals(nested)) {
-            // 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).
-            throw new Error(`${subCfg.yaml_reference}: approval gates (require_approval) are not supported inside a nested syndicate.`);
-        }
-        return compileGraph(nested, opts, subCfg.name, subCfg.description);
+        const nestedOpts = nestedOptions(subCfg.yaml_reference, opts);
+        return compileSpec(loadNestedSyndicate(subCfg.yaml_reference, nestedOpts), 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);
-    const resolveModel = opts.resolveModel ?? ((m) => m);
     logCapabilities(opts, subCfg.name, subCfg.model, subCfg.tools);
-    return new LlmAgent({
-        name: subCfg.name,
-        description: subCfg.description,
-        model: withFallback(resolveModel(subCfg.model), subCfg.fallback_model, resolveModel, opts),
-        instruction,
-        tools: tools.length > 0 ? tools : undefined,
-        outputSchema: subCfg.outputSchema,
-        generateContentConfig: withServerSideToolInvocations(subCfg.generateContentConfig),
-        ...passthroughFields(subCfg),
-        ...executionFields(subCfg, opts),
-        ...(opts.nodeConfig?.(subCfg.name) ?? {}),
-    });
+    return specOf(subCfg, subCfg.name, subCfg.description, instruction, asTools(tools), opts);
 }
 /**
- * Compiles a syndicate's orchestrator. In DELEGATE mode its subagents are
- * attached as AgentTools; in PLAN-DISPATCH mode it gets none (ADK refuses
- * outputSchema + AgentTool on one agent — see config/agents/critic.yaml),
- * and the caller dispatches to `compileSubagent(route)` itself.
+ * 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
+ * config/agents/critic.yaml), and the caller dispatches to a route's own
+ * spec itself.
  */
-export async function compileGraph(config, opts = {}, overrideName, overrideDescription) {
+export async function compileSpec(config, opts = {}, overrideName, overrideDescription) {
     // A registry definition carries its nested syndicates (ADR 0018 item 6).
     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). Nested as a yaml_reference, only its
-    // orchestrator runs, since ADK cannot yet make a Workflow a subagent.
+    // 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`);
     }
     if (config.workflow)
-        opts.log?.(`${config.syndicate_name}: nested as a subagent, so only its orchestrator runs (a Workflow cannot be a subagent yet)`);
-    const compiledTools = isDispatchSyndicate(config)
+        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) => {
             if (subCfg.a2a_agent_url) {
                 opts.log?.(`Remote A2A agent: ${subCfg.name} → ${subCfg.a2a_agent_url}`);
-                return remoteAgentTool({ name: subCfg.name, description: subCfg.description, url: subCfg.a2a_agent_url });
+                return { kind: 'remote', name: subCfg.name, description: subCfg.description, url: subCfg.a2a_agent_url };
             }
-            return new AgentTool({ agent: await compileSubagent(subCfg, opts) });
+            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 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.
-    compiledTools.push(...gateTools(await resolveAgentTools(config.orchestrator.tools, undefined, opts, config.orchestrator.openapi, config.orchestrator.examples), config.orchestrator.require_approval, overrideName || config.orchestrator.name));
-    const { instruction, tools: orchestratorTools } = await withSkills(config.orchestrator.instruction, compiledTools, config.orchestrator.skills, overrideName || config.orchestrator.name, opts);
-    const resolveModel = opts.resolveModel ?? ((m) => m);
-    logCapabilities(opts, overrideName || config.orchestrator.name, config.orchestrator.model, config.orchestrator.tools);
-    return new LlmAgent({
-        name: overrideName || config.orchestrator.name,
-        description: overrideDescription || config.orchestrator.description,
-        model: withFallback(resolveModel(config.orchestrator.model), config.orchestrator.fallback_model, resolveModel, opts),
-        instruction,
-        tools: orchestratorTools.length > 0 ? orchestratorTools : undefined,
-        outputSchema: config.orchestrator.outputSchema,
-        generateContentConfig: withServerSideToolInvocations(config.orchestrator.generateContentConfig),
-        ...passthroughFields(config.orchestrator),
-        ...executionFields(config.orchestrator, opts),
-    });
+    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);
+}
+// ── 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);
 }

package/dist/lib/compileAdk.d.ts

@@ -0,0 +1,32 @@
+/**
+ * lib/compileAdk.ts — an AgentSpec as the ADK runtime runs it: today's
+ * LlmAgent (ADR 0045, ADR 0073).
+ *
+ * WHY this file exists:
+ *   lib/compile.ts turns a YAML agent into a runtime-neutral AgentSpec: its
+ *   tools resolved and gated, its instruction with the skills index, its
+ *   model resolved once and its generateContentConfig built for that model.
+ *   This file adds what only ADK's LlmAgent takes: the model wrapped in a
+ *   FallbackLlm for `fallback_model:`, each delegated subagent as an
+ *   AgentTool (a nested workflow's whole Workflow too; a remote one as its
+ *   A2A tool), Gemini's code executor, the
+ *   context compactor, task mode and a workflow node's settings. Every field
+ *   reaches LlmAgent as compileGraph and compileSubagent always passed it, so
+ *   the ADK runtime runs the agent it ran before the split.
+ *   lib/compileNative.ts builds the native loop's agent from the same spec.
+ *
+ * Imports from lib/compile.ts are types only. A nested workflow's Workflow
+ * comes from lib/workflow.ts (assembleWorkflow, ADR 0098), which imports
+ * lib/compile.ts; every use of either is inside a function, so the modules
+ * load in any order.
+ */
+import type { LlmAgent } from '@google/adk';
+import type { AgentSpec, CompileOptions } from './compile.ts';
+import { DEFAULT_KEEP_RECENT_EVENTS } from './runtime/native/compaction.ts';
+/** Events kept verbatim after a compaction summary when `context:` names none: the native compactor's default. */
+export { DEFAULT_KEEP_RECENT_EVENTS };
+/**
+ * The LlmAgent for `spec`. `extra` is spread last: a workflow node's
+ * settings (CompileOptions.nodeConfig), which compileSubagent passes.
+ */
+export declare function compileAdk(spec: AgentSpec, opts?: CompileOptions, extra?: Record<string, unknown>): LlmAgent;

package/dist/lib/compileAdk.js

@@ -0,0 +1,142 @@
+/**
+ * lib/compileAdk.ts — an AgentSpec as the ADK runtime runs it: today's
+ * LlmAgent (ADR 0045, ADR 0073).
+ *
+ * WHY this file exists:
+ *   lib/compile.ts turns a YAML agent into a runtime-neutral AgentSpec: its
+ *   tools resolved and gated, its instruction with the skills index, its
+ *   model resolved once and its generateContentConfig built for that model.
+ *   This file adds what only ADK's LlmAgent takes: the model wrapped in a
+ *   FallbackLlm for `fallback_model:`, each delegated subagent as an
+ *   AgentTool (a nested workflow's whole Workflow too; a remote one as its
+ *   A2A tool), Gemini's code executor, the
+ *   context compactor, task mode and a workflow node's settings. Every field
+ *   reaches LlmAgent as compileGraph and compileSubagent always passed it, so
+ *   the ADK runtime runs the agent it ran before the split.
+ *   lib/compileNative.ts builds the native loop's agent from the same spec.
+ *
+ * Imports from lib/compile.ts are types only. A nested workflow's Workflow
+ * comes from lib/workflow.ts (assembleWorkflow, ADR 0098), which imports
+ * lib/compile.ts; every use of either is inside a function, so the modules
+ * load in any order.
+ */
+import { BaseLlm, adk, requireAdk } from './adkPeer.js';
+import { remoteAgentTool } from './a2a/remoteAgent.js';
+import { assembleWorkflow } from './workflow.js';
+import { FallbackLlm } from './models/fallback.js';
+import { resolveModel as resolveRegistryModel } from './models/registry.js';
+import { onLogLevel } from './runtime/logging.js';
+import { DEFAULT_KEEP_RECENT_EVENTS } from './runtime/native/compaction.js';
+/**
+ * ADK's logger follows the engine's level (lib/runtime/logging.ts, ADR
+ * 0080), so a surface sets one level and never names ADK to quiet it.
+ */
+if (adk) {
+    const { LogLevel: Level, setLogLevel } = adk;
+    const levels = { debug: Level.DEBUG, info: Level.INFO, warn: Level.WARN, error: Level.ERROR };
+    onLogLevel((level) => setLogLevel(levels[level]));
+}
+/** What compileAdk builds needs @google/adk; without it, this names the package (ADR 0102). */
+const FEATURE = 'Compiling an agent for the ADK runtime (MELCHIZEDEK_RUNTIME=adk, compileGraph, compileSubagent)';
+/** Events kept verbatim after a compaction summary when `context:` names none: the native compactor's default. */
+export { DEFAULT_KEEP_RECENT_EVENTS };
+/**
+ * The LlmAgent fields a YAML agent may set beyond model, instruction, tools
+ * and schemas. The schema reference (config/agents/syndicateSchema.yaml)
+ * documents each as mapping 1:1 to its ADK counterpart. Only fields the YAML
+ * sets are passed, so ADK's defaults stay in force otherwise.
+ */
+function passthroughFields(spec) {
+    const out = {};
+    if (spec.includeContents !== undefined)
+        out.includeContents = spec.includeContents;
+    if (spec.outputKey !== undefined)
+        out.outputKey = spec.outputKey;
+    if (spec.globalInstruction !== undefined)
+        out.globalInstruction = spec.globalInstruction;
+    if (spec.disallowTransferToParent !== undefined)
+        out.disallowTransferToParent = spec.disallowTransferToParent;
+    if (spec.disallowTransferToPeers !== undefined)
+        out.disallowTransferToPeers = spec.disallowTransferToPeers;
+    return out;
+}
+/**
+ * The LlmAgent fields the engine builds from YAML rather than passing
+ * through (ADR 0033): `code_execution: gemini` (Gemini's server-side
+ * sandbox runs the model's Python; nothing runs on this host), `context:`
+ * (ADK's token-based compactor with an LLM summarizer, so a long
+ * conversation is summarized instead of overflowing the window), and
+ * `mode: task` (the agent works until it calls finish_task; on a workflow
+ * node, its arguments become the node's output).
+ */
+function executionFields(cfg, opts) {
+    const { BuiltInCodeExecutor, LLMRegistry, LlmSummarizer, TokenBasedContextCompactor } = requireAdk(FEATURE);
+    const out = {};
+    if (cfg.codeExecution === 'gemini')
+        out.codeExecutor = new BuiltInCodeExecutor();
+    if (cfg.mode)
+        out.mode = cfg.mode;
+    if (cfg.context) {
+        const resolve = opts.resolveModel ?? ((m) => m);
+        const summaryModel = resolve(cfg.context.summary_model ?? cfg.model);
+        const llm = typeof summaryModel === 'string' || !summaryModel ? LLMRegistry.newLlm(String(summaryModel ?? cfg.model)) : summaryModel;
+        out.contextCompactors = [
+            new TokenBasedContextCompactor({
+                tokenThreshold: cfg.context.compact_after_tokens,
+                eventRetentionSize: cfg.context.keep_recent_events ?? DEFAULT_KEEP_RECENT_EVENTS,
+                summarizer: new LlmSummarizer({ llm }),
+            }),
+        ];
+    }
+    return out;
+}
+/**
+ * An agent with `fallback_model:` gets its model wrapped (lib/models/fallback.ts):
+ * the fallback answers a provider-side failure, and a provider that keeps
+ * failing is skipped for a cooldown. A model id string is resolved to its
+ * adapter first, so the wrapper always holds two adapters.
+ */
+function withFallback(primary, fallbackId, opts) {
+    if (!fallbackId)
+        return primary;
+    const resolve = opts.resolveModel ?? ((m) => m);
+    const asLlm = (m) => (m instanceof BaseLlm ? m : resolveRegistryModel(String(m)));
+    return new FallbackLlm(asLlm(primary), asLlm(resolve(fallbackId)), opts.log ?? ((m) => console.warn(m)));
+}
+/** The spec's tools as LlmAgent takes them: a delegated subagent (a nested workflow's Workflow included) as an AgentTool, a remote one as its A2A tool. */
+function adkTools(spec, opts) {
+    const { AgentTool } = requireAdk(FEATURE);
+    return spec.tools.map((entry) => {
+        switch (entry.kind) {
+            case 'tool':
+                return entry.tool;
+            case 'agent':
+                return new AgentTool({ agent: compileAdk(entry.agent, opts) });
+            case 'remote':
+                return remoteAgentTool({ name: entry.name, description: entry.description, url: entry.url });
+            case 'workflow':
+                // ADK's AgentTool runs any node its Runner takes, a Workflow included: the whole graph, its last event's text the answer (ADR 0098).
+                return new AgentTool({ agent: assembleWorkflow(entry.workflow, opts).workflow });
+        }
+    });
+}
+/**
+ * The LlmAgent for `spec`. `extra` is spread last: a workflow node's
+ * settings (CompileOptions.nodeConfig), which compileSubagent passes.
+ */
+export function compileAdk(spec, opts = {}, extra = {}) {
+    const { LlmAgent } = requireAdk(FEATURE);
+    const tools = adkTools(spec, opts);
+    return new LlmAgent({
+        name: spec.name,
+        description: spec.description,
+        model: withFallback(spec.resolvedModel, spec.fallbackModel, opts),
+        instruction: spec.instruction,
+        tools: tools.length > 0 ? tools : undefined,
+        outputSchema: spec.outputSchema,
+        generateContentConfig: spec.generateContentConfig,
+        ...passthroughFields(spec),
+        ...executionFields(spec, opts),
+        ...extra,
+    });
+}