melchizedek-agents 0.19.0 → 0.20.0

package/dist/lib/workflow/agentNode.js

@@ -43,8 +43,25 @@
  *      error; a run that ends with one and no output returns it as the
  *      run's `error`, and the scheduler fails the attempt with
  *      NodeReportedError, ADK's message, retried or stopping the walk as
- *      ADK's does, and reported once (by the node's own event). A run the turn stopped throws. A run that pauses on a person
- *      (an ask_user tool, an approval) is an interrupt, not run here yet.
+ *      ADK's does, and reported once (by the node's own event). A run the turn stopped throws. A run that pauses on
+ *      an ask_user tool call is refused by name.
+ *   8. APPROVALS (ADR 0098). A run that pauses on approval requests (a tool
+ *      in the agent's `require_approval`) resolves with their ids as the
+ *      node's interrupts: the node waits and the walk ends paused, as an
+ *      ask_user node's does. The resumed walk reruns the node with
+ *      `resumedInterruptIds`: until every request has a decision among the
+ *      answers (a confirmation, never a plain-text message) it waits again
+ *      without running, its open requests raised again on one event of the
+ *      new run (`waitAgain`), so the run after still resumes them; then the
+ *      agent's run continues instead of starting afresh, unless it already
+ *      did on an earlier resume, whose stored output is then the node's
+ *      (`outputAfter`). No input turn is stored, so the person's answer stays the
+ *      latest user event, and the loop's approval resume
+ *      (lib/runtime/native/interrupts.ts, ADR 0077) runs or refuses the
+ *      pinned call before the next model step, which reads the node's turn
+ *      from its input on. ADK's runLlmAgentAsNode stores the input again and
+ *      starts the agent afresh, so the pinned call never runs there; ADK
+ *      turns refuse gates on workflow nodes instead.
  *
  * `agentNodeRuntime` puts it together for the scheduler: a `runNode` for
  * agent nodes and map items, and an `onEvent` that stores the event ADK
@@ -52,10 +69,11 @@
  * (lib/workflow/nodeEvents.ts), so a session the native walk writes holds
  * what ADK's holds, in the same order.
  *
- * NOT HERE: interrupts inside a node (an ask_user tool call, an approval),
+ * NOT HERE: an ask_user tool call inside a node, a pause inside a map item,
  * tool nodes (lib/workflow/toolNode.ts) and ask_user nodes
  * (lib/workflow/pause.ts). It imports nothing from ADK.
  */
+import { APPROVAL_REQUEST } from '../runtime/approvals.js';
 import { createTurnEvent, getFunctionCalls } from '../runtime/events.js';
 import { runAgentLoop } from '../runtime/native/agentLoop.js';
 import { predecessorOutputs } from '../runtime/native/request.js';
@@ -130,12 +148,71 @@ function nodeStamp(agent, run, invocationId, state) {
             }
         }
         enrichNodeEvent(event, run, { invocationId });
+        // ADK's node runner (consume): an event that raises an interrupt records the node's input for the resume.
+        if (event.longRunningToolIds?.length)
+            event.actions = { ...event.actions, agentState: { ...(event.actions?.agentState ?? {}), input: run.input } };
         if (event.output !== undefined)
             state.output = event.output;
         if (event.errorCode !== undefined)
             state.reported = { errorCode: event.errorCode, ...(event.errorMessage !== undefined ? { errorMessage: event.errorMessage } : {}) };
     };
 }
+/** Whether `event` carries the approval request `id` (an `adk_request_confirmation` call). */
+function isApprovalRequest(event, id) {
+    return !!event && getFunctionCalls(event).some((call) => call.id === id && call.name === APPROVAL_REQUEST);
+}
+/**
+ * Whether a resumed walk's answer to an approval request is a decision: a
+ * ToolConfirmation (`{ confirmed }`), or ADK's `{ response: <json> }` form.
+ * A plain-text message the resume read as the answer is not one, and the
+ * node keeps waiting.
+ */
+function isApprovalAnswer(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const answer = value;
+    return typeof answer.confirmed === 'boolean' || typeof answer.response === 'string';
+}
+/**
+ * Rule 8, a node whose decided requests an earlier resume already acted on
+ * (another node's approval was the one answered since): the output its run
+ * stored after the last of those requests, else undefined. The node does
+ * not run again.
+ */
+function outputAfter(events, path, ids) {
+    const open = new Set(ids);
+    let start = -1;
+    events.forEach((event, i) => {
+        if (getFunctionCalls(event).some((call) => call.name === APPROVAL_REQUEST && call.id !== undefined && open.has(call.id)))
+            start = i;
+    });
+    if (start === -1)
+        return undefined;
+    for (let i = events.length - 1; i > start; i--) {
+        const event = events[i];
+        if (event.nodeInfo?.path === path && event.output !== undefined && !event.partial)
+            return event.output;
+    }
+    return undefined;
+}
+/**
+ * Rule 8, a node still waiting: its open requests raised again, as one event
+ * of this run (a copy of each request call, stamped as the node's), so the
+ * next message's resume finds the walk paused in this invocation as in the
+ * one before; nothing runs. Resolves with the ids it waits on.
+ */
+async function waitAgain(agent, run, ctx, waiting) {
+    const open = new Set(waiting);
+    const calls = ctx.session.events.flatMap((event) => getFunctionCalls(event).filter((call) => call.name === APPROVAL_REQUEST && call.id !== undefined && open.has(call.id)));
+    const seen = new Set();
+    const parts = calls.filter((call) => !seen.has(call.id) && seen.add(call.id)).map((call) => ({ functionCall: structuredClone(call) }));
+    const event = createTurnEvent({ author: agent.name, invocationId: ctx.invocationId, content: { role: 'model', parts } });
+    event.longRunningToolIds = [...seen];
+    nodeStamp(agent, run, ctx.invocationId, { output: undefined })(event);
+    const stored = await (ctx.appendInput ?? ((e) => ctx.sessions.append(ctx.session, e)))(event);
+    ctx.onEvent?.(stored);
+    return { interruptIds: [...seen] };
+}
 /**
  * Runs `agent` as the node `run` names, on the native loop, and resolves
  * with the node's output, or with the error it reported when it ended on
@@ -146,7 +223,17 @@ export async function runAgentNode(agent, run, ctx) {
     const taskMode = agent.mode === 'task';
     const nodeAgent = asNodeAgent(agent);
     const { session, sessions, invocationId } = ctx;
-    if (!taskMode && run.input !== undefined && run.input !== null) {
+    // Rule 8: a node that waited on an approval resumes its own run once every request it raised is answered.
+    const resumed = run.resumedInterruptIds ?? [];
+    if (resumed.length > 0) {
+        const waiting = resumed.filter((id) => !isApprovalAnswer(run.resumeInputs?.[id]));
+        if (waiting.length > 0)
+            return waitAgain(agent, run, ctx, waiting);
+        const finished = outputAfter(ctx.session.events, run.path, resumed);
+        if (finished !== undefined)
+            return { output: finished };
+    }
+    if (resumed.length === 0 && !taskMode && run.input !== undefined && run.input !== null) {
         const userEvent = createTurnEvent({ author: 'user', invocationId, branch: run.branch, content: nodeInputContent(run.input) });
         const stored = await (ctx.appendInput ?? ((e) => sessions.append(session, e)))(userEvent);
         ctx.onEvent?.(stored);
@@ -179,7 +266,11 @@ export async function runAgentNode(agent, run, ctx) {
             ctx.onEvent?.(next.value);
     }
     if (end.reason === 'paused') {
-        throw new Error(`Node '${agent.name}' paused on ${(end.pending ?? []).join(', ')}: a pause inside an agent node does not run on the native runtime yet.`);
+        // Rule 8: an approval request pauses the node, and the walk with it; any other pause (an ask_user call) is refused.
+        const pending = end.pending ?? [];
+        if (pending.length > 0 && pending.every((id) => isApprovalRequest(end.lastEvent, id)))
+            return { interruptIds: [...pending] };
+        throw new Error(`Node '${agent.name}' paused on ${pending.join(', ')}: a pause inside an agent node other than an approval does not run on the native runtime yet.`);
     }
     if (end.reason === 'stopped')
         throw new NodeStoppedError(agent.name, end.stop);

package/dist/lib/workflow/graph.d.ts

@@ -19,8 +19,8 @@
  *   1. The block's cross-field rules — every name an agent or a declared
  *      node, `START` opening a chain, a routing map after the node it
  *      routes, a declared node exactly one kind, the reserved `__route`
- *      suffix, `workflow` without `dispatch`, and the pauses and remotes a
- *      node cannot carry yet. Same paths and messages as the schema's
+ *      suffix, `workflow` without `dispatch`, `retry` and `timeout` refused on
+ *      a map entry, and the pauses and remotes a node cannot carry yet. Same paths and messages as the schema's
  *      (lib/syndicateSchema.ts, `workflowProblems`), thrown together as a
  *      `WorkflowGraphError`.
  *   2. The graph's own rules, on the built edges — no empty routing map,
@@ -74,8 +74,9 @@ export interface MapNode {
     /** Concurrency of the map; absent means the runtime's default (8). */
     maxParallel?: number;
     /**
-     * The map entry's own modifiers. ADK's compile does not hand them to its
-     * ParallelWorker, so neither runtime applies them; they are kept as written.
+     * The map entry's own modifiers: always empty, since the schema refuses
+     * `retry` and `timeout` on a map entry (ADR 0103). ADK's compile hands
+     * neither to its ParallelWorker.
      */
     settings: GraphNodeSettings;
     /** The mapped agent's own node modifiers (`nodes.<agent>`), which ADK applies to each item's run. */

package/dist/lib/workflow/graph.js

@@ -19,8 +19,8 @@
  *   1. The block's cross-field rules — every name an agent or a declared
  *      node, `START` opening a chain, a routing map after the node it
  *      routes, a declared node exactly one kind, the reserved `__route`
- *      suffix, `workflow` without `dispatch`, and the pauses and remotes a
- *      node cannot carry yet. Same paths and messages as the schema's
+ *      suffix, `workflow` without `dispatch`, `retry` and `timeout` refused on
+ *      a map entry, and the pauses and remotes a node cannot carry yet. Same paths and messages as the schema's
  *      (lib/syndicateSchema.ts, `workflowProblems`), thrown together as a
  *      `WorkflowGraphError`.
  *   2. The graph's own rules, on the built edges — no empty routing map,
@@ -254,6 +254,15 @@ export function workflowConfigProblems(raw, subs) {
         if (kind !== 'map' && entry.max_parallel !== undefined) {
             out.push({ path: ['workflow', 'nodes', name, 'max_parallel'], message: 'max_parallel applies to map only' });
         }
+        // A map item runs under its agent's own modifiers, as on ADK (ADR 0089, ADR 0103): the map entry's would be applied by neither runtime.
+        if (kind === 'map') {
+            for (const key of ['retry', 'timeout']) {
+                if (entry[key] === undefined)
+                    continue;
+                const target = entry.map;
+                out.push({ path: ['workflow', 'nodes', name, key], message: `${key} on a map node is not applied: each item runs under its agent's own ${key}; set it on nodes.${target}` });
+            }
+        }
     }
     for (const name of agentNames) {
         if (name.endsWith(ROUTE_STEP_SUFFIX))
@@ -324,8 +333,9 @@ export function workflowConfigProblems(raw, subs) {
     for (const [path, agent] of agents) {
         if (!isObj(agent))
             continue;
-        if (Array.isArray(agent.require_approval) && agent.require_approval.length) {
-            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported inside a workflow yet' });
+        // A map item cannot pause: the walk resumes a paused agent node, not an item of a map (ADR 0094, ADR 0098).
+        if (typeof agent.name === 'string' && mapped.has(agent.name) && Array.isArray(agent.require_approval) && agent.require_approval.length) {
+            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported on an agent a map node runs: a map item cannot pause the walk' });
         }
         if (isObj(agent.skills) && agent.skills.scripts === 'local') {
             out.push({ path: [...path, 'skills', 'scripts'], message: 'skill scripts (an approval pause) are not supported inside a workflow yet' });

package/dist/lib/workflow/resume.d.ts

@@ -119,13 +119,13 @@ export declare function workflowNodeInput(content: TurnContent | undefined): unk
  */
 export declare function resumeInputsFromPlainText(content: TurnContent | undefined, events: readonly StoredEvent[], invocationId: string): Record<string, unknown>;
 /**
- * A pause the native walk cannot resume: one raised inside an agent node (an
- * `ask_user` tool call, an approval, a credential request) or inside a map
- * item. ADK resumes those inside the node (the agent's own history, the
- * ParallelWorker's item); the native agent node refuses to pause at all
- * (lib/workflow/agentNode.ts), so it cannot pick one up either. Resuming the
- * walk anyway would run the node again from its input and ask again, so the
- * resume refuses by name instead.
+ * A pause the native walk cannot resume: one raised inside an agent node
+ * other than an approval (an `ask_user` tool call, a credential request) or
+ * inside a map item. ADK resumes those inside the node (the agent's own
+ * history, the ParallelWorker's item); the native agent node pauses only on
+ * an approval (lib/workflow/agentNode.ts, ADR 0098), so it cannot pick the
+ * others up. Resuming the walk anyway would run the node again from its
+ * input and ask again, so the resume refuses by name instead.
  */
 export declare class UnsupportedWorkflowResumeError extends Error {
     /** The node path the pause was raised at. */
@@ -134,8 +134,9 @@ export declare class UnsupportedWorkflowResumeError extends Error {
 }
 /**
  * Throws UnsupportedWorkflowResumeError for the first interrupt in the run's
- * events that is not an ask_user node's input request at a direct child of
- * the workflow (the workflow's own record aside).
+ * events that is neither an ask_user node's input request nor an agent
+ * node's approval request at a direct child of the workflow (the workflow's
+ * own record aside).
  */
 export declare function assertResumable(runEvents: readonly StoredEvent[], workflowPath: string): void;
 export interface WorkflowResumeRequest {

package/dist/lib/workflow/resume.js

@@ -384,27 +384,28 @@ export function resumeInputsFromPlainText(content, events, invocationId) {
 }
 // ── What the native walk cannot resume yet ───────────────────────────────────
 /**
- * A pause the native walk cannot resume: one raised inside an agent node (an
- * `ask_user` tool call, an approval, a credential request) or inside a map
- * item. ADK resumes those inside the node (the agent's own history, the
- * ParallelWorker's item); the native agent node refuses to pause at all
- * (lib/workflow/agentNode.ts), so it cannot pick one up either. Resuming the
- * walk anyway would run the node again from its input and ask again, so the
- * resume refuses by name instead.
+ * A pause the native walk cannot resume: one raised inside an agent node
+ * other than an approval (an `ask_user` tool call, a credential request) or
+ * inside a map item. ADK resumes those inside the node (the agent's own
+ * history, the ParallelWorker's item); the native agent node pauses only on
+ * an approval (lib/workflow/agentNode.ts, ADR 0098), so it cannot pick the
+ * others up. Resuming the walk anyway would run the node again from its
+ * input and ask again, so the resume refuses by name instead.
  */
 export class UnsupportedWorkflowResumeError extends Error {
     /** The node path the pause was raised at. */
     nodePath;
     constructor(nodePath, why) {
-        super(`Cannot resume the workflow on the native runtime: the pause at '${nodePath}' was raised ${why}, which only an ask_user node's pause supports here.`);
+        super(`Cannot resume the workflow on the native runtime: the pause at '${nodePath}' was raised ${why}, which only an ask_user node's pause or an agent node's approval supports here.`);
         this.name = 'UnsupportedWorkflowResumeError';
         this.nodePath = nodePath;
     }
 }
 /**
  * Throws UnsupportedWorkflowResumeError for the first interrupt in the run's
- * events that is not an ask_user node's input request at a direct child of
- * the workflow (the workflow's own record aside).
+ * events that is neither an ask_user node's input request nor an agent
+ * node's approval request at a direct child of the workflow (the workflow's
+ * own record aside).
  */
 export function assertResumable(runEvents, workflowPath) {
     for (const event of runEvents) {
@@ -415,8 +416,8 @@ export function assertResumable(runEvents, workflowPath) {
             continue;
         if (directChildName(path, workflowPath) === undefined)
             throw new UnsupportedWorkflowResumeError(path || String(event.author ?? ''), 'inside a nested node (a map item)');
-        const asksForInput = partsOf(event).some((p) => p.functionCall?.name === INPUT_REQUEST);
-        if (!asksForInput)
+        const resumable = partsOf(event).some((p) => p.functionCall?.name === INPUT_REQUEST || p.functionCall?.name === APPROVAL_REQUEST);
+        if (!resumable)
             throw new UnsupportedWorkflowResumeError(path, 'inside an agent node');
     }
 }

package/dist/lib/workflow/scheduler.d.ts

@@ -147,6 +147,12 @@ export interface NodeRun {
      * Absent in a walk that is not a resume.
      */
     resumeInputs?: Readonly<Record<string, unknown>>;
+    /**
+     * The interrupts this node's prior run paused on, when this run resumes it
+     * (a resumed walk's first activation of a node that waited). An agent node
+     * resumes its own run on them instead of starting afresh (ADR 0098).
+     */
+    resumedInterruptIds?: readonly string[];
 }
 /** An error a node reports instead of throwing, as an ADK event's errorCode and errorMessage. */
 export interface ReportedNodeError {
@@ -361,14 +367,11 @@ export declare const RETRY_DEFAULTS: {
     readonly jitter: 1;
 };
 /**
- * A node's retry: the YAML's fields, plus ADK's two the YAML does not spell
- * yet (`exceptions`: the error names that may be retried, all when absent;
- * `jitter`: the random spread, default 1).
+ * A node's retry, as the YAML spells it: ADK's fields, `exceptions` (the
+ * error names that may be retried, all when absent) and `jitter` (the
+ * random spread, default 1) included.
  */
-export type RetrySettings = RetryYaml & {
-    exceptions?: string[];
-    jitter?: number;
-};
+export type RetrySettings = RetryYaml;
 /** The names an error answers to: its class's and its `name`, as ADK matches `exceptions`. */
 export declare function errorNames(error: unknown): string[];
 /** ADK's errorType: the class name, or the assigned name of a plain Error. */

package/dist/lib/workflow/scheduler.js

@@ -292,7 +292,12 @@ export async function runWorkflowGraph(graph, options) {
             }
         }
         const resuming = prior !== undefined && prior.interruptIds.size > 0 && prior.input !== undefined;
-        return { ...(resuming ? { input: prior.input } : {}), resumeInputs: repeat ? {} : resume.resumeInputs };
+        const waited = prior !== undefined && prior.interruptIds.size > 0 && !repeat;
+        return {
+            ...(resuming ? { input: prior.input } : {}),
+            resumeInputs: repeat ? {} : resume.resumeInputs,
+            ...(waited ? { resumedInterruptIds: [...prior.interruptIds] } : {}),
+        };
     };
     // Seed: one trigger per START edge, each on its own branch when there are several.
     const startEdges = graph.edges.filter((e) => e.from === START_NODE);
@@ -329,7 +334,15 @@ export async function runWorkflowGraph(graph, options) {
             const path = `${workflowPath}.${name}`;
             const input = start.input !== undefined ? start.input : trigger.input;
             emit({ type: 'node_start', node: name, kind: node.kind, runId, path, branch, input });
-            const ctx = { input, runId, path, branch, signal: controller.signal, ...(start.resumeInputs ? { resumeInputs: start.resumeInputs } : {}) };
+            const ctx = {
+                input,
+                runId,
+                path,
+                branch,
+                signal: controller.signal,
+                ...(start.resumeInputs ? { resumeInputs: start.resumeInputs } : {}),
+                ...(start.resumedInterruptIds ? { resumedInterruptIds: start.resumedInterruptIds } : {}),
+            };
             const traced = { name, kind: node.kind, path, runId, attempts: state.attempts };
             const run = walk.traceNode(traced, () => executeNode(node, ctx, walk, state.attempts)).then((result) => ({ name, result: { ...result, branch } }), (error) => ({ name, error }));
             pending.set(name, run);

package/dist/lib/workflow.d.ts

@@ -41,18 +41,32 @@
  *   the wiki), including a `map` node, which ADK would otherwise name after
  *   the agent it wraps.
  *
+ * ── As a subagent (ADR 0098) ─────────────────────────────────────────────
+ * A delegated `yaml_reference` to a workflow syndicate is the whole graph:
+ * `assembleWorkflow` builds its Workflow under the subagent entry's name
+ * and description, and lib/compileAdk.ts wraps it in ADK's AgentTool, whose
+ * answer is the graph's last event's text. A nested workflow with an
+ * `ask_user` node is refused by name (lib/compile.ts compileWorkflowSpec): a
+ * pause inside a tool call cannot reach the caller (ADR 0028). As a dispatch
+ * route or a workflow node, a workflow syndicate is still its orchestrator
+ * alone.
+ *
+ * ── Approval gates (ADR 0098) ────────────────────────────────────────────
+ * A tool in a node agent's `require_approval` pauses the node on ADK's
+ * `adk_request_confirmation`, and the walk with it. Only the native walk
+ * resumes it (lib/workflow/agentNode.ts): ADK's runLlmAgentAsNode reruns the
+ * node from its input and never runs the pinned call, so runSyndicateTurn
+ * refuses a gated workflow on ADK. The schema refuses a gate on an agent a
+ * map runs (an item cannot pause the walk).
+ *
  * ── Not in this version ───────────────────────────────────────────────────
- * Approval gates (`require_approval`, `skills.scripts: local`) and remote
- * `a2a_agent_url` subagents are refused inside a workflow by the schema: a
- * gated call pauses a node through ADK's interrupt path, whose resume is not
- * the one ADR 0028 built, and a remote agent is reachable only as a tool.
- * Both are open for a later record. A `Workflow` cannot yet be another
- * agent's subagent (an ADK limit), so `yaml_reference` to a workflow
- * syndicate compiles its orchestrator alone.
+ * Skill scripts (`skills.scripts: local`, an approval pause) and remote
+ * `a2a_agent_url` subagents are refused inside a workflow by the schema; a
+ * remote agent is reachable only as a tool. Both are open for a later
+ * record.
  */
-import { Workflow } from '@google/adk';
-import type { BaseNode, LlmAgent } from '@google/adk';
-import type { CompileOptions } from './compile.ts';
+import type { BaseNode, LlmAgent, Workflow } from '@google/adk';
+import type { CompileOptions, WorkflowSpec } from './compile.ts';
 import type { SyndicateYamlConfig } from './loadSyndicate.ts';
 export * from './workflowConfig.ts';
 export interface CompiledWorkflow {
@@ -63,10 +77,18 @@ export interface CompiledWorkflow {
     nodes: Map<string, BaseNode>;
 }
 /**
- * Compile a workflow syndicate: every agent through `compileSubagent` (its
+ * Compile a workflow syndicate: every agent through `compileSubagentSpec` (its
  * tools, skills and MCP server as in any mode), the declared nodes, the
  * hidden route steps, and the edge chains, into one ADK `Workflow` named
  * after the syndicate. Throws on a name the schema let through, a tool that
  * is not registered, or a graph ADK rejects (unreachable node, cycle).
  */
 export declare function compileWorkflow(config: SyndicateYamlConfig, opts?: CompileOptions, transformAgent?: (agent: LlmAgent) => LlmAgent): Promise<CompiledWorkflow>;
+/**
+ * ADK's Workflow from a compiled workflow spec, synchronously: each agent
+ * built by compileAdk with its node modifiers (retry, timeout) at
+ * construction, then the declared nodes, route steps and edges. A nested
+ * workflow (ADR 0098) is this Workflow under its subagent entry's name and
+ * description, which lib/compileAdk.ts wraps in ADK's AgentTool.
+ */
+export declare function assembleWorkflow(spec: WorkflowSpec, opts?: CompileOptions, transformAgent?: (agent: LlmAgent) => LlmAgent): CompiledWorkflow;

package/dist/lib/workflow.js

@@ -41,22 +41,37 @@
  *   the wiki), including a `map` node, which ADK would otherwise name after
  *   the agent it wraps.
  *
+ * ── As a subagent (ADR 0098) ─────────────────────────────────────────────
+ * A delegated `yaml_reference` to a workflow syndicate is the whole graph:
+ * `assembleWorkflow` builds its Workflow under the subagent entry's name
+ * and description, and lib/compileAdk.ts wraps it in ADK's AgentTool, whose
+ * answer is the graph's last event's text. A nested workflow with an
+ * `ask_user` node is refused by name (lib/compile.ts compileWorkflowSpec): a
+ * pause inside a tool call cannot reach the caller (ADR 0028). As a dispatch
+ * route or a workflow node, a workflow syndicate is still its orchestrator
+ * alone.
+ *
+ * ── Approval gates (ADR 0098) ────────────────────────────────────────────
+ * A tool in a node agent's `require_approval` pauses the node on ADK's
+ * `adk_request_confirmation`, and the walk with it. Only the native walk
+ * resumes it (lib/workflow/agentNode.ts): ADK's runLlmAgentAsNode reruns the
+ * node from its input and never runs the pinned call, so runSyndicateTurn
+ * refuses a gated workflow on ADK. The schema refuses a gate on an agent a
+ * map runs (an item cannot pause the walk).
+ *
  * ── Not in this version ───────────────────────────────────────────────────
- * Approval gates (`require_approval`, `skills.scripts: local`) and remote
- * `a2a_agent_url` subagents are refused inside a workflow by the schema: a
- * gated call pauses a node through ADK's interrupt path, whose resume is not
- * the one ADR 0028 built, and a remote agent is reachable only as a tool.
- * Both are open for a later record. A `Workflow` cannot yet be another
- * agent's subagent (an ADK limit), so `yaml_reference` to a workflow
- * syndicate compiles its orchestrator alone.
+ * Skill scripts (`skills.scripts: local`, an approval pause) and remote
+ * `a2a_agent_url` subagents are refused inside a workflow by the schema; a
+ * remote agent is reachable only as a tool. Both are open for a later
+ * record.
  */
-import { DEFAULT_ROUTE, FunctionNode, JoinNode, ParallelWorker, RequestInput, ToolNode, Workflow, createEvent, } from '@google/adk';
-import { compileSubagent } from './compile.js';
-import { resolveTools as resolveNamedTools } from './toolRegistry.js';
+import { requireAdk } from './adkPeer.js';
+import { compileWorkflowSpec } from './compile.js';
+import { compileAdk } from './compileAdk.js';
 import { DEFAULT_ROUTE_KEY, ROUTE_STEP_SUFFIX, START_NAME, isWorkflowSyndicate, nodeKind, nodeSettings, routeOf } from './workflowConfig.js';
 export * from './workflowConfig.js';
 /**
- * Compile a workflow syndicate: every agent through `compileSubagent` (its
+ * Compile a workflow syndicate: every agent through `compileSubagentSpec` (its
  * tools, skills and MCP server as in any mode), the declared nodes, the
  * hidden route steps, and the edge chains, into one ADK `Workflow` named
  * after the syndicate. Throws on a name the schema let through, a tool that
@@ -65,23 +80,29 @@ export * from './workflowConfig.js';
 export async function compileWorkflow(config, opts = {}, transformAgent = (a) => a) {
     if (!isWorkflowSyndicate(config))
         throw new Error(`${config.syndicate_name}: no workflow block`);
+    return assembleWorkflow(await compileWorkflowSpec(config, opts), opts, transformAgent);
+}
+/**
+ * ADK's Workflow from a compiled workflow spec, synchronously: each agent
+ * built by compileAdk with its node modifiers (retry, timeout) at
+ * construction, then the declared nodes, route steps and edges. A nested
+ * workflow (ADR 0098) is this Workflow under its subagent entry's name and
+ * description, which lib/compileAdk.ts wraps in ADK's AgentTool.
+ */
+export function assembleWorkflow(spec, opts = {}, transformAgent = (a) => a) {
+    const config = spec.config;
+    if (!isWorkflowSyndicate(config))
+        throw new Error(`${config.syndicate_name}: no workflow block`);
+    // ADK's Workflow is the adk runtime's; the native walk (lib/workflow/turn.ts) needs none of this (ADR 0102).
+    const { DEFAULT_ROUTE, FunctionNode, JoinNode, ParallelWorker, RequestInput, ToolNode, Workflow, createEvent } = requireAdk("ADK's Workflow (a workflow syndicate on the adk runtime, compileWorkflow)");
     const wf = config.workflow;
     const nodeYaml = wf.nodes ?? {};
-    const agentConfigs = new Map();
-    agentConfigs.set(config.orchestrator.name, { description: '', ...config.orchestrator });
-    for (const sub of config.subagents ?? [])
-        agentConfigs.set(sub.name, sub);
-    // Agents, with their node modifiers (retry, timeout) at construction.
-    const compileOpts = {
-        ...opts,
-        nodeConfig: (name) => {
-            const settings = nodeSettings(nodeYaml[name]);
-            return Object.keys(settings).length ? settings : undefined;
-        },
-    };
+    // Agents, with their node modifiers (retry, timeout) at construction; not on a nested syndicate's orchestrator.
     const agents = new Map();
-    for (const [name, sub] of agentConfigs)
-        agents.set(name, transformAgent(await compileSubagent(sub, compileOpts)));
+    for (const { yaml, spec: agentSpec } of spec.agents) {
+        const settings = yaml.yaml_reference ? {} : nodeSettings(nodeYaml[yaml.name]);
+        agents.set(yaml.name, transformAgent(compileAdk(agentSpec, opts, settings)));
+    }
     // Declared nodes.
     const nodes = new Map(agents);
     for (const [name, entry] of Object.entries(nodeYaml)) {
@@ -118,7 +139,7 @@ export async function compileWorkflow(config, opts = {}, transformAgent = (a) =>
             nodes.set(name, worker);
         }
         else if (kind === 'tool') {
-            const [tool] = resolveNamedTools([entry.tool], opts.onUnknownTool);
+            const tool = spec.resolveTool(entry.tool);
             if (!tool)
                 throw new Error(`workflow node '${name}': tool '${entry.tool}' is not registered`);
             nodes.set(name, new ToolNode(tool, { name, ...settings }));
@@ -172,7 +193,8 @@ export async function compileWorkflow(config, opts = {}, transformAgent = (a) =>
         return out;
     });
     const workflow = new Workflow({
-        name: config.syndicate_name,
+        name: spec.name,
+        ...(spec.description ? { description: spec.description } : {}),
         edges,
         ...(wf.max_concurrency !== undefined ? { maxConcurrency: wf.max_concurrency } : {}),
     });

package/dist/lib/workflowConfig.d.ts

@@ -20,6 +20,10 @@ export interface RetryYaml {
     initial_delay?: number;
     max_delay?: number;
     backoff_factor?: number;
+    /** Randomness of the backoff: 0 none, default 1 (ADK's). */
+    jitter?: number;
+    /** Error names a failure is retried on (its class's or its `name`); every error when absent. */
+    exceptions?: string[];
 }
 /** Per-node settings. A node is an agent (modifiers only) or exactly one of the kinds. */
 export interface WorkflowNodeYaml {

package/dist/lib/workflowConfig.js

@@ -42,6 +42,10 @@ export function toRetryConfig(retry) {
         out.maxDelay = retry.max_delay;
     if (retry.backoff_factor !== undefined)
         out.backoffFactor = retry.backoff_factor;
+    if (retry.jitter !== undefined)
+        out.jitter = retry.jitter;
+    if (retry.exceptions !== undefined)
+        out.exceptions = [...retry.exceptions];
     return out;
 }
 /** The BaseNode fields a node entry's modifiers map to. */

package/dist/scripts/doctor.d.ts

@@ -6,7 +6,9 @@
  * examples/), resolves each agent's model to its provider under the current
  * .env, and prints: the provider, whether that path is funded (direct key,
  * gateway stand-in, or local), which declared server-side tools it keeps or
- * drops, and one verdict per syndicate. Closes with the env vars that would
+ * drops, and one verdict per syndicate. Says first which runtime a turn runs
+ * on (MELCHIZEDEK_RUNTIME, else native) and whether @google/adk, needed only
+ * for the adk runtime, is installed. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key

package/dist/scripts/doctor.js

@@ -6,7 +6,9 @@
  * examples/), resolves each agent's model to its provider under the current
  * .env, and prints: the provider, whether that path is funded (direct key,
  * gateway stand-in, or local), which declared server-side tools it keeps or
- * drops, and one verdict per syndicate. Closes with the env vars that would
+ * drops, and one verdict per syndicate. Says first which runtime a turn runs
+ * on (MELCHIZEDEK_RUNTIME, else native) and whether @google/adk, needed only
+ * for the adk runtime, is installed. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -86,5 +88,5 @@ if (json) {
 else {
     console.log(renderDoctor(result, { color: !noColor }));
 }
-if (check && result.counts.blocked > 0)
+if (check && (result.counts.blocked > 0 || result.runtime.problem))
     process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.19.0",
-  "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
+  "version": "0.20.0",
+  "description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop (Google ADK optional until 1.0), Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/jhwadman/melch-ai/issues"
   },
-  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is a PEER dependency — the consumer's app owns the ADK instance so the model registry is a singleton. The adk peer range is capped to the tested minor (~2.2.0): a new adk minor can pull a second genai copy, so the range widens only after a release is tested against it.",
+  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is an OPTIONAL PEER dependency since 0.20.0 (ADR 0102): the native runtime, the default, needs none of it; a consumer on MELCHIZEDEK_RUNTIME=adk installs it, and their app owns the ADK instance so the model registry is a singleton. lib/adkPeer.ts is the one module that loads it. The adk peer range is capped to the tested minor (~2.2.0): a new adk minor can pull a second genai copy, so the range widens only after a release is tested against it.",
   "engines": {
     "node": ">=22.6.0"
   },
@@ -168,6 +168,9 @@
     "@anthropic-ai/bedrock-sdk": {
       "optional": true
     },
+    "@google/adk": {
+      "optional": true
+    },
     "@anthropic-ai/vertex-sdk": {
       "optional": true
     },