melchizedek-agents 0.19.0 → 0.20.0

package/dist/lib/adkPeer.js

@@ -0,0 +1,240 @@
+/**
+ * lib/adkPeer.ts — @google/adk as an optional peer (ADR 0102).
+ *
+ * WHY this file exists:
+ *   From 0.20.0 the native runtime is the default, and @google/adk is needed
+ *   only for MELCHIZEDEK_RUNTIME=adk and the features only ADK runs. Until
+ *   1.0.0 removes ADK (ADR 0045), the engine's objects still carry an ADK
+ *   face: the tool registry holds FunctionTools that carry their own Tool,
+ *   the model shims are BaseLlm classes that carry their contract adapter,
+ *   and the durable session stores are ADK BaseSessionServices as well as
+ *   the engine's SessionService. Those classes extend ADK's at load time.
+ *
+ *   This module is the one place the package loads ADK. It tries once, when
+ *   it is first imported, and every other module takes ADK's values from
+ *   here, never from '@google/adk' directly (a type-only import is fine):
+ *   - When ADK is installed, each export below IS ADK's own value, so the
+ *     ADK runtime, `instanceof` and ADK's registry behave exactly as before.
+ *   - When it is not, the base classes are stand-ins: they construct as
+ *     ADK's do (a tool's name, a model's id, a toolset's filter) and carry
+ *     ADK's own Symbol.for marks, so the engine reads them as it reads ADK's,
+ *     and every method only ADK calls throws AdkNotInstalledError, which
+ *     names the package. Everything else (`Runner`, `LlmAgent`, the plugins)
+ *     is reached through requireAdk(feature), which throws the same error.
+ *
+ *   A package that is installed but fails to load for another reason (a
+ *   missing dependency of its own, a syntax error) is not "absent": that
+ *   error is rethrown, so nothing hides a broken install.
+ *
+ * The load is a top-level await of a dynamic import: an ES module cannot
+ * load another synchronously, and the exported classes must exist before
+ * any subclass is defined.
+ */
+/** The package this module loads. */
+export const ADK_PACKAGE = '@google/adk';
+/** Whether `err` says the package itself could not be found (and not a module it imports). */
+function isMissingPackage(err) {
+    const e = err;
+    if (!e || typeof e !== 'object')
+        return false;
+    if (e.code !== 'ERR_MODULE_NOT_FOUND' && e.code !== 'MODULE_NOT_FOUND')
+        return false;
+    return typeof e.message === 'string' && e.message.includes(`'${ADK_PACKAGE}'`);
+}
+let loaded;
+try {
+    loaded = await import('@google/adk');
+}
+catch (err) {
+    if (!isMissingPackage(err))
+        throw err;
+}
+/** ADK's module when it is installed, else undefined. */
+export const adk = loaded;
+/** Whether @google/adk is installed and loaded. */
+export function adkInstalled() {
+    return loaded !== undefined;
+}
+/** The installed @google/adk version, read from its package.json, or undefined when it is not installed. */
+export async function adkVersion() {
+    if (!loaded)
+        return undefined;
+    try {
+        const { createRequire } = await import('node:module');
+        const require = createRequire(import.meta.url);
+        const fs = await import('node:fs');
+        const path = await import('node:path');
+        // The package's exports map hides package.json, so walk up from its entry.
+        let dir = path.dirname(require.resolve(ADK_PACKAGE));
+        for (let i = 0; i < 6; i++) {
+            const file = path.join(dir, 'package.json');
+            if (fs.existsSync(file)) {
+                const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (pkg.name === ADK_PACKAGE)
+                    return pkg.version;
+            }
+            dir = path.dirname(dir);
+        }
+    }
+    catch {
+        // Unreadable: the version is unknown, not the package absent.
+    }
+    return undefined;
+}
+/** A feature only ADK runs was used without @google/adk installed. */
+export class AdkNotInstalledError extends Error {
+    feature;
+    constructor(feature) {
+        super(`${feature} needs ${ADK_PACKAGE}, which is not installed. ` +
+            `Install it beside melchizedek-agents (npm install ${ADK_PACKAGE}@~2.2.0), ` +
+            `or run on the native runtime (the default; unset MELCHIZEDEK_RUNTIME or set it to native).`);
+        this.name = 'AdkNotInstalledError';
+        this.feature = feature;
+    }
+}
+/** ADK's module, or AdkNotInstalledError naming `feature` when it is not installed. */
+export function requireAdk(feature) {
+    if (!loaded)
+        throw new AdkNotInstalledError(feature);
+    return loaded;
+}
+// ── Stand-ins for ADK's base classes ─────────────────────────────────────────
+//
+// Each matches the ADK constructor's effect on the instance and ADK's
+// Symbol.for mark, nothing more. They exist only when ADK is not installed.
+const BASE_TOOL = Symbol.for('google.adk.baseTool');
+const IN_MODEL_TOOL = Symbol.for('google.adk.inModelTool');
+const FUNCTION_TOOL = Symbol.for('google.adk.functionTool');
+const BASE_TOOLSET = Symbol.for('google.adk.baseToolset');
+const BASE_MODEL = Symbol.for('google.adk.baseModel');
+const GEMINI_MODEL = Symbol.for('google.adk.geminiModel');
+function adkOnly(what) {
+    throw new AdkNotInstalledError(what);
+}
+class MissingBaseTool {
+    [BASE_TOOL] = true;
+    name;
+    description;
+    isLongRunning;
+    constructor(params) {
+        this.name = params.name;
+        this.description = params.description;
+        this.isLongRunning = params.isLongRunning ?? false;
+    }
+    _getDeclaration() {
+        return undefined;
+    }
+    async checkRequireConfirmation() {
+        return false;
+    }
+    async processLlmRequest(_request) {
+        adkOnly(`The ADK face of the tool '${this.name}'`);
+    }
+    async runAsync(_request) {
+        return adkOnly(`The ADK face of the tool '${this.name}'`);
+    }
+}
+class MissingFunctionTool extends MissingBaseTool {
+    [FUNCTION_TOOL] = true;
+    execute;
+    parameters;
+    requireConfirmation;
+    constructor(options) {
+        const name = options.name ?? options.execute.name;
+        if (!name)
+            throw new Error('Tool name cannot be empty. Either name the `execute` function or provide a `name`.');
+        super({ name, description: options.description, isLongRunning: options.isLongRunning });
+        this.execute = options.execute;
+        this.parameters = options.parameters;
+        this.requireConfirmation = options.requireConfirmation ?? false;
+    }
+}
+class MissingBaseToolset {
+    [BASE_TOOLSET] = true;
+    toolFilter;
+    prefix;
+    constructor(toolFilter, prefix) {
+        this.toolFilter = toolFilter;
+        this.prefix = prefix;
+    }
+    async getTools() {
+        return adkOnly('An ADK toolset');
+    }
+    async close() { }
+}
+class MissingBaseLlm {
+    [BASE_MODEL] = true;
+    model;
+    static supportedModels = [];
+    constructor({ model }) {
+        this.model = model;
+    }
+    generateContentAsync() {
+        return adkOnly(`The ADK face of the model '${this.model}'`);
+    }
+    async connect() {
+        return adkOnly(`The ADK face of the model '${this.model}'`);
+    }
+}
+/**
+ * ADK's Gemini, absent: it holds what a caller gave it (the model, a key,
+ * Vertex AI's settings), as ADK's does, so the native runtime reads it as it
+ * reads TracedGemini (lib/compileNative.ts). Calling it throws.
+ */
+class MissingGemini extends MissingBaseLlm {
+    [GEMINI_MODEL] = true;
+    apiKey;
+    vertexai;
+    project;
+    location;
+    headers;
+    constructor(params) {
+        super({ model: params.model ?? 'gemini-2.5-flash' });
+        if (params.apiKey !== undefined)
+            this.apiKey = params.apiKey;
+        if (params.vertexai !== undefined)
+            this.vertexai = params.vertexai;
+        if (params.project !== undefined)
+            this.project = params.project;
+        if (params.location !== undefined)
+            this.location = params.location;
+        if (params.headers !== undefined)
+            this.headers = params.headers;
+    }
+}
+/**
+ * ADK's session service base, absent. A store that extends it is still the
+ * engine's SessionService; only the ADK face (the base's appendEvent, which
+ * ADK's Runner reaches) needs ADK.
+ */
+class MissingBaseSessionService {
+    async appendEvent(_request) {
+        return adkOnly('The ADK face of a session store');
+    }
+    /** ADK's own: the session when it exists, else a new one, through the store's methods. */
+    async getOrCreateSession(request) {
+        const self = this;
+        if (!request.sessionId)
+            return self.createSession(request);
+        const session = await self.getSession({ appName: request.appName, userId: request.userId, sessionId: request.sessionId });
+        return session ?? self.createSession(request);
+    }
+}
+/** ADK's GOOGLE_SEARCH, absent: an in-model tool named google_search, which the engine reads by ADK's mark. */
+class MissingGoogleSearchTool extends MissingBaseTool {
+    [IN_MODEL_TOOL] = true;
+    constructor() {
+        super({ name: 'google_search', description: 'Google Search Tool' });
+    }
+}
+// ── The values every other module imports ────────────────────────────────────
+//
+// A type of the same name sits beside each value, so `import { BaseTool }`
+// from here serves as both, as it did from '@google/adk'.
+export const BaseTool = loaded?.BaseTool ?? MissingBaseTool;
+export const FunctionTool = loaded?.FunctionTool ?? MissingFunctionTool;
+export const BaseToolset = loaded?.BaseToolset ?? MissingBaseToolset;
+export const BaseLlm = loaded?.BaseLlm ?? MissingBaseLlm;
+export const Gemini = loaded?.Gemini ?? MissingGemini;
+export const BaseSessionService = loaded?.BaseSessionService ?? MissingBaseSessionService;
+export const GOOGLE_SEARCH = loaded?.GOOGLE_SEARCH ?? new MissingGoogleSearchTool();

package/dist/lib/compile.d.ts

@@ -37,7 +37,7 @@
  * the native loop's NativeAgent (ADR 0045). runSyndicateTurn picks one by
  * MELCHIZEDEK_RUNTIME or its `runtime` option.
  */
-import { BaseLlm, FunctionTool } from '@google/adk';
+import { BaseLlm, FunctionTool } from './adkPeer.ts';
 import type { BaseTool, LlmAgent } from '@google/adk';
 import type { ReasoningSetting, SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
 import type { ExampleConfig } from './tools/examples.ts';
@@ -122,7 +122,9 @@ export declare function agentGates(agent: {
  * period an ADK object that carries its own Tool or InstructionTool
  * (lib/tools/adkTool.ts), an MCP tool or the skills toolset, gated by
  * require_approval where the YAML says so. `agent` is a delegated subagent
- * (DELEGATE mode), `remote` a subagent served over A2A.
+ * (DELEGATE mode), `remote` a subagent served over A2A, `workflow` a
+ * `yaml_reference` to a workflow syndicate, whose whole graph is the tool
+ * (ADR 0098).
  */
 export type SpecTool = {
     kind: 'tool';
@@ -135,7 +137,32 @@ export type SpecTool = {
     name: string;
     description: string;
     url: string;
+} | {
+    kind: 'workflow';
+    workflow: WorkflowSpec;
 };
+/**
+ * A workflow syndicate, compiled for either runtime: lib/workflow.ts builds
+ * ADK's Workflow from it, lib/compileNative.ts the native walk's graph and
+ * agents. Nested as a subagent (a `yaml_reference` in DELEGATE mode), the
+ * graph runs under the entry's name and description, and that name is the
+ * root of every node path, as ADK names a Workflow's nodes after it.
+ */
+export interface WorkflowSpec {
+    /** The workflow's name: the syndicate's, or the subagent entry's when nested. */
+    name: string;
+    /** The tool's description when nested; '' at the root. */
+    description: string;
+    /** The syndicate, its `syndicate_name` set to `name`. */
+    config: SyndicateYamlConfig;
+    /** Every agent of the graph, the orchestrator first, as compileSubagentSpec builds it, with its YAML entry. */
+    agents: Array<{
+        yaml: SubagentYamlConfig;
+        spec: AgentSpec;
+    }>;
+    /** The registry entry for a tool node's tool name, or undefined (CompileOptions.onUnknownTool applies). */
+    resolveTool: (name: string) => unknown;
+}
 /**
  * One YAML agent, compiled, for either runtime: what lib/compileAdk.ts
  * turns into ADK's LlmAgent and lib/compileNative.ts into the native loop's
@@ -174,6 +201,17 @@ export interface AgentSpec {
     /** `mode: task`. */
     mode?: 'task';
 }
+/**
+ * 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 declare function compileWorkflowSpec(config: SyndicateYamlConfig, opts?: CompileOptions, name?: string, description?: string, ref?: string): Promise<WorkflowSpec>;
 /**
  * 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

package/dist/lib/compile.js

@@ -37,10 +37,11 @@
  * the native loop's NativeAgent (ADR 0045). runSyndicateTurn picks one by
  * MELCHIZEDEK_RUNTIME or its `runtime` option.
  */
-import { BaseLlm, FunctionTool } 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';
@@ -278,6 +279,71 @@ 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, 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
@@ -291,14 +357,8 @@ 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.`);
-        }
-        return compileSpec(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);
@@ -317,13 +377,14 @@ 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.
+    // 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)`);
+        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) => {
@@ -331,6 +392,13 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
                 opts.log?.(`Remote A2A agent: ${subCfg.name} → ${subCfg.a2a_agent_url}`);
                 return { kind: 'remote', name: subCfg.name, description: subCfg.description, url: subCfg.a2a_agent_url };
             }
+            if (subCfg.yaml_reference) {
+                const nestedOpts = nestedOptions(subCfg.yaml_reference, opts);
+                const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts);
+                if (isWorkflowSyndicate(nested))
+                    return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference) };
+                return { kind: 'agent', agent: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
+            }
             return { kind: 'agent', agent: await compileSubagentSpec(subCfg, opts) };
         }));
     const name = overrideName || config.orchestrator.name;

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,

package/dist/lib/compileNative.d.ts

@@ -16,7 +16,8 @@
  * 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
+ * syndicate as its orchestrator's agent, a nested workflow syndicate as a
+ * workflowSubagentTool whose call walks the whole graph (ADR 0098); 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
@@ -38,11 +39,13 @@
  * 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 { AgentSpec, CompileOptions, WorkflowSpec } from './compile.ts';
 import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
 import type { ModelAdapter } from './models/contract.ts';
+import type { WorkflowSubagent } from './runtime/native/delegate.ts';
 import type { NativeAgent } from './runtime/native/request.ts';
 export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.ts';
+import type { WorkflowGraph } from './workflow/graph.ts';
 /**
  * The class name of an ADK model the native runtime cannot run, else
  * undefined: an ADK BaseLlm that is neither ADK's Gemini (TracedGemini
@@ -66,6 +69,29 @@ export declare function compileNative(spec: AgentSpec): NativeAgent;
 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>;
+/** A workflow syndicate for the native walk (lib/workflow/turn.ts): its graph, every agent by YAML name, and the tool nodes' lookup. */
+export interface NativeWorkflow {
+    name: string;
+    description: string;
+    graph: WorkflowGraph;
+    agents: Map<string, NativeAgent>;
+    resolveTool: (name: string) => unknown;
+}
+/**
+ * A workflow spec for the native walk: the graph, every agent compiled for
+ * native from the same specs ADK's assembleWorkflow builds its agents from,
+ * and the registry's lookup for tool nodes. A tool node ADK's compile
+ * refuses (an unregistered or long-running tool) is refused here, before
+ * any model call, with ADK's message.
+ */
+export declare function compileNativeWorkflow(spec: WorkflowSpec): NativeWorkflow;
+/**
+ * A nested workflow as the delegated subagent the native loop calls (ADR
+ * 0098): one call walks the whole graph with runNativeWorkflow on the child
+ * session lib/runtime/native/delegate.ts opened, as ADK's AgentTool runs a
+ * Workflow on its own Runner.
+ */
+export declare function workflowSubagentOf(workflow: NativeWorkflow): WorkflowSubagent;
 /** 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. */