melchizedek-agents 0.18.0 → 0.19.0

package/dist/lib/wiki/entities.js

@@ -31,7 +31,7 @@
  *   private one, so any public slice of this graph is closed by
  *   construction.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { isPrivatePath } from './format.js';
@@ -604,11 +604,53 @@ export function relationEdges(records) {
         ...(r.at ? { at: r.at } : {}),
     }));
 }
+/**
+ * Replace the whole store with `records`, in the order given. The store's
+ * order is the order of assertion; nothing sorts it.
+ */
 export function saveRelations(wikiRoot, records) {
     const file = relationsPath(wikiRoot);
     mkdirSync(dirname(file), { recursive: true });
-    const sorted = [...records].sort((a, b) => a.from.localeCompare(b.from) || a.rel.localeCompare(b.rel) || a.to.localeCompare(b.to));
-    writeFileSync(file, `${JSON.stringify({ version: 1, relations: sorted }, null, 2)}\n`, 'utf-8');
+    writeFileSync(file, `${JSON.stringify({ version: 1, relations: records }, null, 2)}\n`, 'utf-8');
+}
+/**
+ * Add one assertion at the end of the store. Every record already there
+ * keeps its place and its bytes, so two branches that each assert something
+ * merge by keeping both sides. Returns false, writing nothing, when the edge
+ * is already asserted. Throws when the store does not parse rather than
+ * write over it.
+ */
+export function appendRelation(wikiRoot, record) {
+    const next = relationRecordSchema.parse(record);
+    const file = relationsPath(wikiRoot);
+    let store = { version: 1, relations: [] };
+    // Read once, with no existence check first: a check and then a read can
+    // see two different files (CodeQL js/file-system-race).
+    let text;
+    try {
+        text = readFileSync(file, 'utf-8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    if (text !== undefined) {
+        const raw = JSON.parse(text);
+        const parsed = relationStoreSchema.safeParse(raw);
+        if (!parsed.success)
+            throw new Error(`relations.json is not a relation store: ${parsed.error.issues[0]?.message ?? 'invalid'}`);
+        store = raw;
+        store.relations ??= [];
+        if (parsed.data.relations.some((r) => edgeKey(r) === edgeKey(next)))
+            return false;
+    }
+    store.relations.push(next);
+    mkdirSync(dirname(file), { recursive: true });
+    // Replace the store in one step, so a reader never sees half a file.
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`, 'utf-8');
+    renameSync(tmp, file);
+    return true;
 }
 export function writeSnapshot(wikiRoot, graph, generated) {
     const file = snapshotPath(wikiRoot);

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

@@ -0,0 +1,136 @@
+/**
+ * lib/workflow/agentNode.ts — an agent as a workflow node on the native
+ * runtime, as ADK 2.2 runs an LlmAgent node (ADR 0030, ADR 0090).
+ *
+ * ADK runs an agent node through `runLlmAgentAsNode`
+ * (workflow/run_llm_agent_as_node.js) inside its node runner
+ * (workflow/node_runner.js). This module is the same run on the native
+ * agent loop (lib/runtime/native/agentLoop.ts), rule for rule:
+ *
+ *   1. THE INPUT IS THE USER TURN. The previous node's output is stored as a
+ *      user event on the node's branch before the agent runs: a Content as
+ *      it is (role `user`), a string as one text part, anything else as its
+ *      JSON. An undefined or null input stores nothing. The event carries no
+ *      node path, as ADK appends it straight to the session.
+ *   2. THE includeContents RULE. An agent whose YAML does not set
+ *      `includeContents` runs with `none`: it sees the current turn, which
+ *      is its input, and nothing else of the session. One that sets it keeps
+ *      what it set. ADK sets this on the agent itself; here the node runs a
+ *      copy, so the compiled agent is unchanged.
+ *   3. TASK MODE. A `mode: task` agent gets no user turn and keeps its
+ *      includeContents; the loop runs it as a task node (`taskNode`), which
+ *      ends on finish_task's successful answer and writes the output on that
+ *      event (lib/runtime/native/taskMode.ts, ADR 0081).
+ *   4. THE OUTPUT. Outside task mode, each stored model event with content
+ *      and no function call carries the node's output: its text (thought
+ *      parts left out), or, with an output schema, the text parsed as JSON
+ *      when it parses; and `nodeInfo.messageAsOutput` (ADK's maybeSetOutput).
+ *      The node's output is the last output an event carried.
+ *   5. THE STAMP. Every event the loop stores gets `nodeInfo.path` (the
+ *      node's path, `<workflow>.<node>`, or `<workflow>.<map>.<agent>@<i>`
+ *      for a map item), `nodeInfo.outputFor` on an event with an output,
+ *      and the node's branch when it has none (ADK's enrichEvent, the one
+ *      port in lib/workflow/toolNode.ts, enrichNodeEvent). The loop
+ *      calls the stamp before it stores each event (`nodeStamp`), after the
+ *      outputKey and task hooks, the order ADK applies them in.
+ *   6. THE INSTRUCTION SCOPE. The run carries ADK's workflow instruction
+ *      scope (`workflowScope`): the node's input, and the output every event
+ *      of the invocation stored before the node ran, by node name
+ *      (predecessorOutputs, ADK's collectPredecessorOutputs). The request
+ *      fills `{x.field}` and `<x.field from Node>` from it
+ *      (lib/runtime/native/request.ts, injectSessionState).
+ *   7. FAILURE. An event carrying an error code is the node's reported
+ *      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.
+ *
+ * `agentNodeRuntime` puts it together for the scheduler: a `runNode` for
+ * agent nodes and map items, and an `onEvent` that stores the event ADK
+ * stores for each route step (lib/workflow/route.ts), join and map
+ * (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),
+ * tool nodes (lib/workflow/toolNode.ts) and ask_user nodes
+ * (lib/workflow/pause.ts). It imports nothing from ADK.
+ */
+import type { TurnContent, TurnEvent } from '../runtime/events.ts';
+import type { AgentLoopContext } from '../runtime/native/agentLoop.ts';
+import type { NativeAgent } from '../runtime/native/request.ts';
+import type { Session, SessionService } from '../runtime/sessions.ts';
+import type { NodeResult, NodeRun, NodeRunner, SchedulerEvent } from './scheduler.ts';
+/** A node whose run ended on an error event and produced no output: the scheduler's, which fails the attempt (rule 7). */
+export { NodeReportedError } from './scheduler.ts';
+/** A node run the turn stopped (cancel, deadline, max_steps): the stop's code and message. */
+export declare class NodeStoppedError extends Error {
+    readonly code: string;
+    readonly nodeName: string;
+    constructor(nodeName: string, stop: {
+        code: string;
+        message: string;
+    } | undefined);
+}
+/** The user turn a node input becomes (ADK's toUserContent). */
+export declare function nodeInputContent(input: unknown): TurnContent;
+/** The agent a node runs: outside task mode, `includeContents: none` unless the agent set it. A copy; the compiled agent is unchanged. */
+export declare function asNodeAgent(agent: NativeAgent): NativeAgent;
+/** ADK's maybeSetOutput: the output a stored model event carries outside task mode, or undefined when it carries none. */
+export declare function eventOutput(agent: Pick<NativeAgent, 'outputSchema'>, event: TurnEvent): unknown;
+/** The loop options a node run takes from its caller; the node sets the rest. */
+export type AgentNodeLoopOptions = Omit<AgentLoopContext, 'session' | 'sessions' | 'invocationId' | 'userContent' | 'branch' | 'signal' | 'taskNode' | 'nodeStamp' | 'workflowScope'>;
+export interface AgentNodeContext {
+    session: Session;
+    sessions: SessionService;
+    /** The workflow run's invocation id: every event of every node carries it. */
+    invocationId: string;
+    /** The message that started the turn (the invocation's user content). */
+    userContent?: TurnContent;
+    /** Loop options for every node: adapters, self-correction, memory, streaming. */
+    loop?: AgentNodeLoopOptions;
+    /** Each event as it is stored, in order. */
+    onEvent?: (event: TurnEvent) => void;
+    /** Each partial (streamed, never stored) event the node's loop yields, as it yields it. */
+    onPartial?: (event: TurnEvent) => void;
+    /** Stores the node's user turn; default `sessions.append`. agentNodeRuntime passes its queue. Called synchronously, before the run's first await. */
+    appendInput?: (event: TurnEvent) => Promise<TurnEvent>;
+}
+/**
+ * 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
+ * one with no output. Throws NodeStoppedError when the turn stopped it, and
+ * an Error when it paused on a person.
+ */
+export declare function runAgentNode(agent: NativeAgent, run: Pick<NodeRun, 'input' | 'path' | 'branch' | 'signal'>, ctx: AgentNodeContext): Promise<NodeResult>;
+export interface AgentNodeRuntimeOptions extends Omit<AgentNodeContext, 'appendInput'> {
+    /** Every agent of the syndicate, compiled for native, by YAML name. */
+    agents: ReadonlyMap<string, NativeAgent>;
+    /**
+     * Runs every run that is not an agent node or a map item (tool, ask_user),
+     * as toolNodeRunner(context, next) hands on what it does not run, so the
+     * runners chain. Default: refuses them by name.
+     */
+    next?: NodeRunner;
+}
+export interface AgentNodeRuntime {
+    /** The scheduler's runNode: agent nodes and map items run here; every other run goes to `next`. */
+    runNode: NodeRunner;
+    /** The scheduler's onEvent: stores the event ADK stores for each route step, join and map. */
+    onEvent: (event: SchedulerEvent) => void;
+    /**
+     * Stores an event another runner of the chain made (a tool node's, through
+     * its context's onEvent) on the same queue, in walk order, and hands it to
+     * the `onEvent` option once stored.
+     */
+    store(event: TurnEvent): Promise<TurnEvent>;
+    /** Resolves once every event queued for storage is stored; rejects with the first store error. */
+    settled(): Promise<void>;
+}
+/**
+ * The scheduler's node runner for a syndicate's agents, and the store for
+ * its route steps' events. Node user turns and route events are stored in
+ * the order the walk reaches them, through one queue, so a route step's
+ * event lands before its successor's input as on ADK.
+ */
+export declare function agentNodeRuntime(options: AgentNodeRuntimeOptions): AgentNodeRuntime;

package/dist/lib/workflow/agentNode.js

@@ -0,0 +1,274 @@
+/**
+ * lib/workflow/agentNode.ts — an agent as a workflow node on the native
+ * runtime, as ADK 2.2 runs an LlmAgent node (ADR 0030, ADR 0090).
+ *
+ * ADK runs an agent node through `runLlmAgentAsNode`
+ * (workflow/run_llm_agent_as_node.js) inside its node runner
+ * (workflow/node_runner.js). This module is the same run on the native
+ * agent loop (lib/runtime/native/agentLoop.ts), rule for rule:
+ *
+ *   1. THE INPUT IS THE USER TURN. The previous node's output is stored as a
+ *      user event on the node's branch before the agent runs: a Content as
+ *      it is (role `user`), a string as one text part, anything else as its
+ *      JSON. An undefined or null input stores nothing. The event carries no
+ *      node path, as ADK appends it straight to the session.
+ *   2. THE includeContents RULE. An agent whose YAML does not set
+ *      `includeContents` runs with `none`: it sees the current turn, which
+ *      is its input, and nothing else of the session. One that sets it keeps
+ *      what it set. ADK sets this on the agent itself; here the node runs a
+ *      copy, so the compiled agent is unchanged.
+ *   3. TASK MODE. A `mode: task` agent gets no user turn and keeps its
+ *      includeContents; the loop runs it as a task node (`taskNode`), which
+ *      ends on finish_task's successful answer and writes the output on that
+ *      event (lib/runtime/native/taskMode.ts, ADR 0081).
+ *   4. THE OUTPUT. Outside task mode, each stored model event with content
+ *      and no function call carries the node's output: its text (thought
+ *      parts left out), or, with an output schema, the text parsed as JSON
+ *      when it parses; and `nodeInfo.messageAsOutput` (ADK's maybeSetOutput).
+ *      The node's output is the last output an event carried.
+ *   5. THE STAMP. Every event the loop stores gets `nodeInfo.path` (the
+ *      node's path, `<workflow>.<node>`, or `<workflow>.<map>.<agent>@<i>`
+ *      for a map item), `nodeInfo.outputFor` on an event with an output,
+ *      and the node's branch when it has none (ADK's enrichEvent, the one
+ *      port in lib/workflow/toolNode.ts, enrichNodeEvent). The loop
+ *      calls the stamp before it stores each event (`nodeStamp`), after the
+ *      outputKey and task hooks, the order ADK applies them in.
+ *   6. THE INSTRUCTION SCOPE. The run carries ADK's workflow instruction
+ *      scope (`workflowScope`): the node's input, and the output every event
+ *      of the invocation stored before the node ran, by node name
+ *      (predecessorOutputs, ADK's collectPredecessorOutputs). The request
+ *      fills `{x.field}` and `<x.field from Node>` from it
+ *      (lib/runtime/native/request.ts, injectSessionState).
+ *   7. FAILURE. An event carrying an error code is the node's reported
+ *      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.
+ *
+ * `agentNodeRuntime` puts it together for the scheduler: a `runNode` for
+ * agent nodes and map items, and an `onEvent` that stores the event ADK
+ * stores for each route step (lib/workflow/route.ts), join and map
+ * (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),
+ * tool nodes (lib/workflow/toolNode.ts) and ask_user nodes
+ * (lib/workflow/pause.ts). It imports nothing from ADK.
+ */
+import { createTurnEvent, getFunctionCalls } from '../runtime/events.js';
+import { runAgentLoop } from '../runtime/native/agentLoop.js';
+import { predecessorOutputs } from '../runtime/native/request.js';
+import { joinNodeEvent, mapNodeEvent } from './nodeEvents.js';
+import { routeStepEvent } from './route.js';
+import { enrichNodeEvent } from './toolNode.js';
+// ── Errors, as ADK names them ────────────────────────────────────────────────
+/** A node whose run ended on an error event and produced no output: the scheduler's, which fails the attempt (rule 7). */
+export { NodeReportedError } from './scheduler.js';
+/** A node run the turn stopped (cancel, deadline, max_steps): the stop's code and message. */
+export class NodeStoppedError extends Error {
+    code;
+    nodeName;
+    constructor(nodeName, stop) {
+        super(`Node '${nodeName}' stopped: ${stop ? `${stop.code}: ${stop.message}` : 'the turn stopped it'}`);
+        this.name = 'NodeStoppedError';
+        this.code = stop?.code ?? 'STOPPED';
+        this.nodeName = nodeName;
+    }
+}
+// ── The rules, one function each ─────────────────────────────────────────────
+/** ADK's isContent: an object with a `parts` array. */
+function isContent(value) {
+    return typeof value === 'object' && value !== null && Array.isArray(value.parts);
+}
+/** The user turn a node input becomes (ADK's toUserContent). */
+export function nodeInputContent(input) {
+    if (isContent(input))
+        return { ...input, role: 'user' };
+    if (typeof input === 'string')
+        return { role: 'user', parts: [{ text: input }] };
+    return { role: 'user', parts: [{ text: JSON.stringify(input) }] };
+}
+/** The agent a node runs: outside task mode, `includeContents: none` unless the agent set it. A copy; the compiled agent is unchanged. */
+export function asNodeAgent(agent) {
+    if (agent.mode === 'task' || agent.includeContents !== undefined)
+        return agent;
+    return { ...agent, includeContents: 'none' };
+}
+/** ADK's maybeSetOutput: the output a stored model event carries outside task mode, or undefined when it carries none. */
+export function eventOutput(agent, event) {
+    if (event.partial)
+        return undefined;
+    if (getFunctionCalls(event).length > 0)
+        return undefined;
+    const content = event.content;
+    if (!content || content.role !== 'model' || !content.parts)
+        return undefined;
+    const text = content.parts
+        .filter((p) => p.text && !p.thought)
+        .map((p) => p.text)
+        .join('');
+    if (agent.outputSchema && text.trim()) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    return text;
+}
+/** The stamp the loop applies to each event before it stores it (rules 4 and 5). */
+function nodeStamp(agent, run, invocationId, state) {
+    const taskMode = agent.mode === 'task';
+    return (event) => {
+        if (!taskMode) {
+            const output = eventOutput(agent, event);
+            if (output !== undefined) {
+                event.output = output;
+                event.nodeInfo = { ...(event.nodeInfo ?? {}), messageAsOutput: true };
+            }
+        }
+        enrichNodeEvent(event, run, { invocationId });
+        if (event.output !== undefined)
+            state.output = event.output;
+        if (event.errorCode !== undefined)
+            state.reported = { errorCode: event.errorCode, ...(event.errorMessage !== undefined ? { errorMessage: event.errorMessage } : {}) };
+    };
+}
+/**
+ * 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
+ * one with no output. Throws NodeStoppedError when the turn stopped it, and
+ * an Error when it paused on a person.
+ */
+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) {
+        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);
+    }
+    // ADK's withWorkflowInstructionScope: the input, and the outputs stored before the node runs.
+    const workflowScope = { input: run.input, outputsByNode: predecessorOutputs(session.events, invocationId) };
+    const state = { output: undefined };
+    const loop = runAgentLoop(nodeAgent, {
+        ...(ctx.loop ?? {}),
+        session,
+        sessions,
+        invocationId,
+        ...(ctx.userContent ? { userContent: ctx.userContent } : {}),
+        ...(run.branch !== undefined ? { branch: run.branch } : {}),
+        signal: run.signal,
+        taskNode: taskMode,
+        nodeStamp: nodeStamp(agent, run, invocationId, state),
+        workflowScope,
+    });
+    let end;
+    for (;;) {
+        const next = await loop.next();
+        if (next.done) {
+            end = next.value;
+            break;
+        }
+        if (next.value.partial)
+            ctx.onPartial?.(next.value);
+        else
+            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.`);
+    }
+    if (end.reason === 'stopped')
+        throw new NodeStoppedError(agent.name, end.stop);
+    // ADK's failIfNodeReportedError: an error with an output is not the node's failure. Without one the error is
+    // returned, not thrown: the scheduler fails the attempt with its own NodeReportedError (this class's message), which
+    // it knows the node reported, so it writes no node-error event of its own, as ADK writes none (ADR 0095).
+    if (state.reported && state.output === undefined) {
+        const code = state.reported.errorCode ?? 'UNKNOWN_ERROR';
+        return { error: { code, message: state.reported.errorMessage ?? code } };
+    }
+    return state.output === undefined ? {} : { output: state.output };
+}
+/**
+ * The scheduler's node runner for a syndicate's agents, and the store for
+ * its route steps' events. Node user turns and route events are stored in
+ * the order the walk reaches them, through one queue, so a route step's
+ * event lands before its successor's input as on ADK.
+ */
+export function agentNodeRuntime(options) {
+    const { agents, session, sessions, invocationId } = options;
+    let tail = Promise.resolve();
+    let failure;
+    const enqueue = (event, onStored) => {
+        const stored = tail.then(async () => {
+            const appended = await sessions.append(session, event);
+            onStored?.(appended);
+            return appended;
+        });
+        tail = stored.then(() => undefined, (error) => {
+            failure ??= { error };
+        });
+        return stored;
+    };
+    const ctx = {
+        session,
+        sessions,
+        invocationId,
+        ...(options.userContent ? { userContent: options.userContent } : {}),
+        ...(options.loop ? { loop: options.loop } : {}),
+        ...(options.onEvent ? { onEvent: options.onEvent } : {}),
+        ...(options.onPartial ? { onPartial: options.onPartial } : {}),
+        // An event queued before the input that failed to store stops the node before its agent runs.
+        appendInput: async (event) => {
+            const stored = await enqueue(event);
+            if (failure)
+                throw failure.error;
+            return stored;
+        },
+    };
+    const agentNamed = (name) => {
+        const agent = agents.get(name);
+        if (!agent)
+            throw new Error(`workflow: '${name}' is not a compiled agent of this syndicate`);
+        return agent;
+    };
+    // A node's user turn is queued as the node starts, in the same synchronous pass, as ADK's runLlmAgentAsNode appends it
+    // straight to the session; so it lands after every event queued before it (a route step's, a predecessor's) and
+    // before the events other runners hand over in that pass (`store`, below).
+    const runNode = async (run) => {
+        if (failure)
+            throw failure.error;
+        const target = run.target;
+        if (target.kind === 'agent')
+            return runAgentNode(agentNamed(target.name), run, ctx);
+        if (target.kind === 'map_item')
+            return runAgentNode(agentNamed(target.agent), run, ctx);
+        if (options.next)
+            return options.next(run);
+        throw new Error(`agentNodeRunner runs agent nodes and map items only; ${target.name} is a ${target.kind} run`);
+    };
+    const onEvent = (event) => {
+        if (event.type !== 'node_end')
+            return;
+        const run = { name: event.node, path: event.path, branch: event.branch, invocationId, output: event.output };
+        // The events ADK stores for the nodes the scheduler runs itself: a route step's, a join's, a map's.
+        const stored = event.kind === 'route' ? routeStepEvent({ ...run, route: event.route }) : event.kind === 'join' ? joinNodeEvent(run) : event.kind === 'map' ? mapNodeEvent(run) : undefined;
+        if (stored)
+            enqueue(stored, options.onEvent).catch(() => { }); // surfaced by runNode and settled()
+    };
+    return {
+        runNode,
+        onEvent,
+        // ADK's Runner stores what a node yields a few ticks after it is yielded, behind the user turns of nodes started in
+        // the same pass: queued one microtask later, which is still before the walk starts the node's successors.
+        store: (event) => Promise.resolve().then(() => enqueue(event, options.onEvent)),
+        async settled() {
+            await tail;
+            if (failure)
+                throw failure.error;
+        },
+    };
+}

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

@@ -0,0 +1,177 @@
+/**
+ * lib/workflow/graph.ts — the `workflow:` block as an engine-owned graph.
+ *
+ * The YAML (lib/workflowConfig.ts) says what runs after what in chains of
+ * names; this module turns those chains into the graph a scheduler runs:
+ * typed nodes (`start`, `agent`, `join`, `map`, `tool`, `ask_user`, and the
+ * hidden `route` step after a node a routing map follows), directed edges
+ * that are unconditional, keyed to a route, or the `default` route, and the
+ * workflow's `max_concurrency`. It imports nothing from ADK.
+ *
+ * It is the same graph `compileWorkflow` (lib/workflow.ts) hands ADK's
+ * `Workflow`: the same node names in the same order, the same edges in the
+ * same order with the same routes (tests/workflowGraph.test.ts holds the
+ * two together on every workflow fixture). The engine's own scheduler,
+ * lib/workflow/scheduler.ts, runs it (ADR 0087).
+ *
+ * ── Validation ────────────────────────────────────────────────────────────
+ * Two passes, each raising the message today's path raises:
+ *   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
+ *      (lib/syndicateSchema.ts, `workflowProblems`), thrown together as a
+ *      `WorkflowGraphError`.
+ *   2. The graph's own rules, on the built edges — no empty routing map,
+ *      `START` present, without routes and without incoming edges, every
+ *      node reachable from `START`, no duplicate edge, one `default` per
+ *      node, no unconditional cycle. Same messages ADK's graph validation
+ *      throws when `compileWorkflow` builds the `Workflow`, first problem
+ *      only, as ADK does.
+ * The schema's type checks (an edge chain of at least two elements, a name
+ * that is a non-empty string) are not repeated: the input is a syndicate
+ * that has passed `validateSyndicateConfig`, or one shaped like it. Whether
+ * a `tool` node's tool is registered is a compile-time question (the
+ * registry), not a graph one.
+ */
+import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
+import type { RetryYaml } from '../workflowConfig.ts';
+/**
+ * The entry node's name in the graph. The YAML writes it `START`; the graph
+ * names it as the ADK compile does, so a node path read from an ADK-written
+ * workflow event names the same node here.
+ */
+export declare const START_NODE = "__START__";
+/** What a node is. `route` is the hidden step after a node a routing map follows. */
+export type GraphNodeKind = 'start' | 'agent' | 'join' | 'map' | 'tool' | 'ask_user' | 'route';
+/** The modifiers a node entry carries (`retry`, `timeout`), in the YAML spelling. */
+export interface GraphNodeSettings {
+    retry?: RetryYaml;
+    /** Seconds this node may run before it fails. */
+    timeout?: number;
+}
+export interface StartNode {
+    kind: 'start';
+    name: typeof START_NODE;
+}
+export interface AgentNode {
+    kind: 'agent';
+    /** The agent's YAML name: the orchestrator or a subagent. */
+    name: string;
+    settings: GraphNodeSettings;
+}
+export interface JoinNode {
+    kind: 'join';
+    name: string;
+    settings: GraphNodeSettings;
+}
+export interface MapNode {
+    kind: 'map';
+    name: string;
+    /** The agent run once per item of the list input. It is not itself a graph node. */
+    agent: string;
+    /** 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.
+     */
+    settings: GraphNodeSettings;
+    /** The mapped agent's own node modifiers (`nodes.<agent>`), which ADK applies to each item's run. */
+    agentSettings: GraphNodeSettings;
+}
+export interface ToolNode {
+    kind: 'tool';
+    name: string;
+    /** The registry tool run with the node input as its arguments. */
+    tool: string;
+    settings: GraphNodeSettings;
+}
+export interface AskUserNode {
+    kind: 'ask_user';
+    name: string;
+    /** The question. */
+    message: string;
+    /** JSON Schema a structured reply must satisfy. */
+    schema?: Record<string, unknown>;
+    settings: GraphNodeSettings;
+}
+export interface RouteNode {
+    kind: 'route';
+    /** `<source>__route`. */
+    name: string;
+    /** The node whose output this step reads the route from. */
+    source: string;
+    /** Property of a JSON output holding the route (`route_key`, default "route"); else the trimmed text. */
+    routeKey: string;
+}
+export type GraphNode = StartNode | AgentNode | JoinNode | MapNode | ToolNode | AskUserNode | RouteNode;
+/**
+ * When an edge fires: always (`always`), when the source's route is `key`
+ * (`key`, the YAML routing-map key verbatim), or when no keyed edge from the
+ * same source matched (`default`).
+ */
+export type EdgeRoute = {
+    kind: 'always';
+} | {
+    kind: 'key';
+    key: string;
+} | {
+    kind: 'default';
+};
+export interface GraphEdge {
+    from: string;
+    to: string;
+    route: EdgeRoute;
+}
+export interface WorkflowGraph {
+    /** The syndicate's name, which names the workflow. */
+    name: string;
+    /** Every node, by name, in order of first appearance in `edges` (`START_NODE` first). */
+    nodes: Map<string, GraphNode>;
+    /** Every edge, chain by chain, element pair by element pair. */
+    edges: GraphEdge[];
+    /** Nodes that may run at once; absent means unbounded. */
+    maxConcurrency?: number;
+    /** Nodes with no outgoing edge: the workflow's output is theirs. */
+    terminals: string[];
+    /** Every agent the syndicate declares (orchestrator first), including one reached only through a map. */
+    agents: string[];
+}
+/** One problem the block's rules found, with the key path the schema reports it at. */
+export interface GraphProblem {
+    path: readonly PropertyKey[];
+    message: string;
+}
+/**
+ * Thrown by `buildWorkflowGraph`. For the block's rules, `problems` holds one
+ * `<key.path> — <what>` line per problem and the message reads as
+ * `SyndicateValidationError`'s does without a file; for a graph rule, it
+ * holds the one message, which is the error's message.
+ */
+export declare class WorkflowGraphError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[], message?: string);
+}
+/**
+ * The graph a workflow syndicate declares. Throws `WorkflowGraphError` on a
+ * rule the block breaks, and an `Error` when the syndicate has no
+ * `workflow:` block, with `compileWorkflow`'s message.
+ */
+export declare function buildWorkflowGraph(config: SyndicateYamlConfig): WorkflowGraph;
+/**
+ * The cross-field rules of a `workflow:` block, with the paths and messages
+ * `validateSyndicateConfig` reports for them, in the same order. Empty for a
+ * block that keeps them all.
+ */
+export declare function workflowConfigProblems(raw: Record<string, unknown>, subs: unknown[]): GraphProblem[];
+/**
+ * A routing-map key as the ADK compile stores it and prints it: an integer
+ * spelling becomes a number and `true`/`false` a boolean, compared as
+ * strings, so `01` and `1` name the same route there. Used for the
+ * duplicate-edge rule and its message, and by the scheduler
+ * (lib/workflow/scheduler.ts) to match an emitted route as ADK matches it
+ * (ADR 0087); the graph keeps the key verbatim.
+ */
+export declare function adkRouteString(route: EdgeRoute): string | null;