melchizedek-agents 0.17.0 → 0.19.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,17 +27,30 @@
  * 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, BuiltInCodeExecutor, ExampleTool, FunctionTool, LLMRegistry, LlmAgent, LlmSummarizer, TokenBasedContextCompactor } from '@google/adk';
+import { BaseLlm, FunctionTool } from '@google/adk';
 import { relative } from 'node:path';
+import { compileAdk } from './compileAdk.js';
 import { isDispatchSyndicate } from './dispatch.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 { 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 ?? {});
@@ -48,59 +62,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.
+ * 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 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).
- */
-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
@@ -129,9 +115,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);
@@ -155,17 +145,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).`);
         }
@@ -183,17 +172,16 @@ 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 }] }] }))),
-    ];
+    const tool = examplesInstructionTool(examples);
+    return tool ? [toAdkInstructionTool(tool)] : [];
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples) {
+async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
     const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
     // OpenAPI operations become tools here, so require_approval can name them.
     for (const entry of openapi ?? []) {
@@ -207,7 +195,20 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, example
     }
     if (mcpServerUrl) {
         opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        const mcpTools = await createMcpTools(mcpServerUrl);
+        const offered = await createMcpTools(mcpServerUrl);
+        // 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.
+        const allowed = mcpAllowed ? new Set(mcpAllowed) : undefined;
+        const mcpTools = allowed ? offered.filter((t) => allowed.has(t.name)) : offered;
+        if (allowed) {
+            const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
+            if (missing.length)
+                opts.log?.(`MCP ${mcpServerUrl} does not offer ${missing.map((n) => `'${n}'`).join(', ')} (mcp_tools)`);
+            const hidden = offered.length - mcpTools.length;
+            if (hidden)
+                opts.log?.(`MCP ${mcpServerUrl}: ${hidden} tool(s) not in mcp_tools are not exposed`);
+        }
         for (const mcpTool of mcpTools) {
             if (!tools.some((t) => t.name === mcpTool.name))
                 tools.push(mcpTool);
@@ -231,22 +232,62 @@ 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 }));
 /**
- * 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 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) {
@@ -257,32 +298,21 @@ export async function compileSubagent(subCfg, opts = {}) {
             // 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);
+        return compileSpec(nested, opts, subCfg.name, subCfg.description);
     }
-    const gated = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts, subCfg.openapi, subCfg.examples), subCfg.require_approval, subCfg.name);
+    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: resolveModel(subCfg.model),
-        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) };
@@ -294,31 +324,41 @@ export async function compileGraph(config, opts = {}, overrideName, overrideDesc
     }
     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)
+    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) });
+            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: resolveModel(config.orchestrator.model),
-        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,29 @@
+/**
+ * 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 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, so the two modules load in
+ * either order.
+ */
+import { 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,132 @@
+/**
+ * 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 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, so the two modules load in
+ * either order.
+ */
+import { AgentTool, BaseLlm, BuiltInCodeExecutor, LLMRegistry, LlmAgent, LlmSummarizer, LogLevel, TokenBasedContextCompactor, setLogLevel as setAdkLogLevel } from '@google/adk';
+import { remoteAgentTool } from './a2a/remoteAgent.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.
+ */
+const ADK_LOG_LEVELS = {
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+};
+onLogLevel((level) => setAdkLogLevel(ADK_LOG_LEVELS[level]));
+/** 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 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 as an AgentTool, a remote one as its A2A tool. */
+function adkTools(spec, opts) {
+    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 });
+        }
+    });
+}
+/**
+ * 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 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,
+    });
+}

package/dist/lib/compileNative.d.ts

@@ -0,0 +1,85 @@
+/**
+ * lib/compileNative.ts — an AgentSpec as the native runtime runs it: the
+ * NativeAgent the agent loop takes (ADR 0045, ADR 0073).
+ *
+ * WHY this file exists:
+ *   lib/compile.ts turns a YAML agent into a runtime-neutral AgentSpec, and
+ *   lib/compileAdk.ts builds ADK's LlmAgent from it. This file builds the
+ *   native loop's agent from the same spec (lib/runtime/native/request.ts,
+ *   NativeAgent), so both runtimes run the agent the YAML describes, with
+ *   the same tools, instruction and config. tests/compile.test.ts compiles
+ *   one spec both ways and requires the same first request.
+ *
+ * TOOLS: each resolved tool is handed to the loop as the own Tool or
+ * InstructionTool behind it (lib/tools/tool.ts), else as itself: an MCP
+ * tool, the skills toolset, a gated registry FunctionTool, which the loop
+ * runs by shape during the dual period (ADR 0071). A delegated subagent
+ * becomes a subagentTool holding its own NativeAgent, which the loop runs as
+ * a child loop (lib/runtime/native/delegate.ts, ADR 0074), a nested
+ * syndicate as its orchestrator's agent; a remote A2A subagent is the own
+ * Tool the ADK runtime's FunctionTool wraps (lib/a2a/remoteAgent.ts).
+ *
+ * EVERY AGENT KEY COMPILES for the native loop: `context:` is handed to
+ * the loop, which compacts as ADK does (lib/runtime/native/compaction.ts,
+ * WS2-9); `mode: task` and `code_execution: gemini` pass through, the
+ * request declaring finish_task (lib/runtime/native/taskMode.ts) and asking
+ * Gemini for its code-execution tool (lib/runtime/native/request.ts). What
+ * native does not run yet (workflows, resuming an approval or a
+ * question, a caller's agent transform) is refused by the turn runner
+ * (lib/runtime/nativeTurn.ts), which owns those choices.
+ *
+ * THE MODEL: the loop calls a model through its contract adapter. A
+ * resolver may return an id, a contract adapter, an ADK shim (which carries
+ * one) or ADK's Gemini (TracedGemini), whose key reaches the registry's
+ * Gemini adapter. Any other ADK model class has no adapter behind it, so
+ * compileNative and nativeAdapterFor refuse it with UnsupportedOnRuntimeError
+ * before any model call, naming adkShim as the way to run it on native,
+ * rather than run the registry's model for that id in its place (ADR 0088).
+ * ADK classes are told apart by ADK's own Symbol.for marks, so this file
+ * imports nothing from ADK.
+ */
+import type { AgentSpec, CompileOptions } from './compile.ts';
+import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
+import type { ModelAdapter } from './models/contract.ts';
+import type { NativeAgent } from './runtime/native/request.ts';
+export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.ts';
+/**
+ * The class name of an ADK model the native runtime cannot run, else
+ * undefined: an ADK BaseLlm that is neither ADK's Gemini (TracedGemini
+ * included) nor a shim carrying a contract adapter (lib/models/adkShim.ts).
+ */
+export declare function unrunnableModelClass(resolved: unknown): string | undefined;
+/**
+ * The NativeAgent for `spec`. Throws when no model id is known, and
+ * UnsupportedOnRuntimeError when the resolver returned an ADK model class
+ * the loop cannot call (see the header).
+ */
+export declare function compileNative(spec: AgentSpec): NativeAgent;
+/**
+ * The model id a request is sent under, as ADK's LlmAgent sends it: the id
+ * of the model object the resolver returned (an ADK model or a contract
+ * adapter carries its own), else the id the resolver returned, else the
+ * spec's. A resolver may answer a YAML id with a model under another id (a
+ * gateway stand-in, a caller's alias); the adapter, the span and the
+ * circuit breaker then see that id on both runtimes.
+ */
+export declare function wireModelOf(spec: Pick<AgentSpec, 'modelId' | 'resolvedModel'>): string | undefined;
+/** A syndicate's orchestrator for the native loop: compileSpec, then compileNative. */
+export declare function compileNativeGraph(config: SyndicateYamlConfig, opts?: CompileOptions): Promise<NativeAgent>;
+/** 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. */
+type NativeModelSpec = Pick<AgentSpec, 'modelId' | 'resolvedModel'> & Partial<Pick<AgentSpec, 'name' | 'fallbackModel' | 'context' | 'tools'>>;
+/**
+ * The loop's `adapterFor` under the same model resolution the ADK runtime
+ * uses: the leaf adapter behind what CompileOptions.resolveModel returns
+ * (an ADK shim carries its contract adapter, so a caller's BYOK key on a
+ * shimmed provider reaches the call), else resolveAdapter for the id
+ * (lib/models/registry.ts). The spec's own resolution, and each delegated
+ * subagent's, is reused for the id its agent runs under (wireModelOf).
+ * Each agent's `fallback_model:` and compaction `summary_model` are
+ * resolved here, as compileAdk resolves them at compile time, so a model
+ * class native cannot run is refused before any model call; any other id
+ * is resolved when first asked for. Each is kept.
+ */
+export declare function nativeAdapterFor(opts?: CompileOptions, spec?: NativeModelSpec | readonly NativeModelSpec[]): (model: string) => ModelAdapter;