melchizedek-agents 0.19.0 → 1.0.0

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,46 +12,42 @@
  *   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 '@google/adk';
 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 { 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 {
@@ -64,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
@@ -84,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';
 /**
@@ -102,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;
@@ -154,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
@@ -172,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)];
@@ -232,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) {
@@ -278,10 +240,121 @@ function specOf(yaml, name, description, instruction, tools, opts) {
     return spec;
 }
 const asTools = (tools) => tools.map((tool) => ({ kind: 'tool', tool }));
+/**
+ * A nested `yaml_reference:` syndicate, loaded. A nested syndicate runs
+ * inside a tool call (or as a route whose own subagents do): a pause there
+ * cannot reach the caller (ADR 0028), so one that declares approval gates is
+ * refused.
+ */
+/** Where the yaml_reference chain a compile is inside is kept: an own symbol on the options, so a spread copy keeps it. */
+const NESTING = Symbol('melchizedek.compile.nesting');
+/** The deepest a yaml_reference chain may go: well past any syndicate the engine ships, short of the stack. */
+const MAX_NESTING_DEPTH = 16;
+/**
+ * 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.
+ */
+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 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 ?? [])]) {
+        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) {
@@ -291,14 +364,12 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
         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.`);
+        const nestedOpts = nestedOptions(subCfg.yaml_reference, opts);
+        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, opts, subCfg.name, subCfg.description);
+        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);
@@ -308,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.
  */
@@ -317,13 +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). Nested as a yaml_reference, only its
-    // orchestrator runs, since ADK cannot yet make a Workflow a subagent.
-    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}: nested as a subagent, so only its orchestrator runs (a Workflow cannot be a subagent yet)`);
     const delegated = isDispatchSyndicate(config)
         ? []
         : await Promise.all((config.subagents ?? []).map(async (subCfg) => {
@@ -331,7 +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 };
             }
-            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
@@ -343,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);
-}

package/dist/lib/compileAdk.d.ts

@@ -8,16 +8,19 @@
  *   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
+ *   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, so the two modules load in
- * either order.
+ * 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 { LlmAgent } from '@google/adk';
+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. */

package/dist/lib/compileAdk.js

@@ -8,17 +8,21 @@
  *   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
+ *   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, so the two modules load in
- * either order.
+ * 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 { AgentTool, BaseLlm, BuiltInCodeExecutor, LLMRegistry, LlmAgent, LlmSummarizer, LogLevel, TokenBasedContextCompactor, setLogLevel as setAdkLogLevel } from '@google/adk';
+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';
@@ -27,13 +31,13 @@ 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]));
+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 };
 /**
@@ -66,6 +70,7 @@ function passthroughFields(spec) {
  * 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();
@@ -98,8 +103,9 @@ function withFallback(primary, fallbackId, opts) {
     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. */
+/** 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':
@@ -108,6 +114,9 @@ function adkTools(spec, opts) {
                 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 });
         }
     });
 }
@@ -116,6 +125,7 @@ function adkTools(spec, opts) {
  * 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,