melchizedek-agents 0.19.0 → 1.0.0

package/dist/lib/adkPeer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+import type * as AdkModule from '@google/adk';
+/** The package this module loads. */
+export declare const ADK_PACKAGE = "@google/adk";
+/** @google/adk's module namespace, as its types describe it. */
+export type Adk = typeof AdkModule;
+/** ADK's module when it is installed, else undefined. */
+export declare const adk: Adk | undefined;
+/** Whether @google/adk is installed and loaded. */
+export declare function adkInstalled(): boolean;
+/** The installed @google/adk version, read from its package.json, or undefined when it is not installed. */
+export declare function adkVersion(): Promise<string | undefined>;
+/** A feature only ADK runs was used without @google/adk installed. */
+export declare class AdkNotInstalledError extends Error {
+    readonly feature: string;
+    constructor(feature: string);
+}
+/** ADK's module, or AdkNotInstalledError naming `feature` when it is not installed. */
+export declare function requireAdk(feature: string): Adk;
+export declare const BaseTool: Adk['BaseTool'];
+export type BaseTool = AdkModule.BaseTool;
+export declare const FunctionTool: Adk['FunctionTool'];
+export type FunctionTool<TParameters extends AdkModule.ToolInputParameters = undefined> = AdkModule.FunctionTool<TParameters>;
+export declare const BaseToolset: Adk['BaseToolset'];
+export type BaseToolset = AdkModule.BaseToolset;
+export declare const BaseLlm: Adk['BaseLlm'];
+export type BaseLlm = AdkModule.BaseLlm;
+export declare const Gemini: Adk['Gemini'];
+export type Gemini = AdkModule.Gemini;
+export declare const BaseSessionService: Adk['BaseSessionService'];
+export type BaseSessionService = AdkModule.BaseSessionService;
+export declare const GOOGLE_SEARCH: Adk['GOOGLE_SEARCH'];

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

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