melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/workflow/resume.js

@@ -0,0 +1,441 @@
+/**
+ * lib/workflow/resume.ts — a paused workflow resumes on the engine's own
+ * scheduler, as ADK 2.2 resumes it (ADR 0094).
+ *
+ * A walk that paused on an `ask_user` node (lib/workflow/pause.ts, ADR 0092)
+ * ended the turn `input-required`. The next message answers it. ADK keeps no
+ * workflow state between the two turns: it rebuilds every node's state from
+ * the session's events (workflow/utils/rehydration_utils.js) and walks the
+ * graph again from START. This module is that rebuild, with no ADK import,
+ * function for function:
+ *
+ *   1. THE RUN'S EVENTS (eventsForCurrentRun). The events of the current
+ *      invocation, plus those of every paused run immediately before it, so
+ *      a run paused twice resumes with both halves.
+ *   2. THE ANSWERS. A plain-text message answers the one open interrupt
+ *      (run_node_as_invocation.js resumeInputsFromPlainText), and a
+ *      function response named for an interrupt answers it explicitly
+ *      (resolvedInterruptResponses: `{ result: x }` unwrapped, a structured
+ *      reply checked against the request's `response_schema`, a reply to an
+ *      unknown or already-answered interrupt refused with ADK's message).
+ *      Together they are ADK's `ctx.resumeInputs`.
+ *   3. THE NODE STATES (reconstructNodeRuns). Per direct child of the
+ *      workflow, its runs in order: the output, route and branch an event
+ *      carried, the interrupts it raised, the answers to them, and the
+ *      input recorded in `actions.agentState.input` (pause.ts writes it).
+ *   4. THE WALK'S INPUT (extractNodeInput): the message's text, else the
+ *      message itself, as ADK hands its root workflow.
+ *
+ * `workflowResume` puts the four together; the scheduler
+ * (lib/workflow/scheduler.ts, `RunWorkflowOptions.resume`) then treats a
+ * node whose prior run has an output and no open interrupt as done
+ * (`isFastForwardable`), reruns a paused node that reruns on resume
+ * (`rerunsOnResume`) on its recorded input with the answers in
+ * `NodeRun.resumeInputs`, and walks on. An ask_user node rerun with an
+ * answer outputs `{ reply, input }` (pause.ts), as the FunctionNode
+ * lib/workflow.ts compiles does.
+ *
+ * TRUST: the answers are the person's words and the stored events are the
+ * session's; both are data the walk carries, never instructions this module
+ * acts on. A function call in an event the user authored raises nothing:
+ * only a node's event opens an interrupt. No regular expression reads input.
+ */
+import { z } from 'zod';
+import { APPROVAL_REQUEST } from '../runtime/approvals.js';
+import { CREDENTIAL_REQUEST } from '../runtime/credentials.js';
+import { INPUT_REQUEST } from '../workflowConfig.js';
+import { RESPONSE_SCHEMA_ARG } from './pause.js';
+/** The key ADK unwraps a bare reply from: `{ result: <value> }`. */
+const RESULT_KEY = 'result';
+const partsOf = (event) => event.content?.parts ?? [];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const stringOr = (value) => (typeof value === 'string' ? value : undefined);
+// ── 1. The run's events ──────────────────────────────────────────────────────
+/**
+ * ADK's raisedInterrupt (requiresUserInput): the event carries an input,
+ * credential or confirmation request with an interrupt id.
+ */
+export function raisedInterrupt(event) {
+    for (const part of partsOf(event)) {
+        const call = part.functionCall;
+        if (!call?.name)
+            continue;
+        if (call.name !== INPUT_REQUEST && call.name !== CREDENTIAL_REQUEST && call.name !== APPROVAL_REQUEST)
+            continue;
+        const args = call.args ?? {};
+        const credential = call.name === CREDENTIAL_REQUEST;
+        // ADK camel-cases a credential request's keys before it reads functionCallId.
+        const id = call.id ?? stringOr(args.interruptId) ?? stringOr(args.functionCallId) ?? (credential ? stringOr(args.function_call_id) : undefined);
+        if (id)
+            return true;
+    }
+    return false;
+}
+/**
+ * ADK's eventsForCurrentRun: the events from the start of the current
+ * invocation, extended back over every run just before it that paused (an
+ * event without an invocation id belongs to the one before it; events
+ * without a node path neither start nor pause a run).
+ */
+export function eventsForCurrentRun(events, currentInvocationId) {
+    const priorRuns = [];
+    let currentStart = events.length;
+    let lastInvocationId;
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        const invocationId = event.invocationId || lastInvocationId;
+        if (event.invocationId)
+            lastInvocationId = event.invocationId;
+        if (invocationId === currentInvocationId) {
+            if (currentStart === events.length)
+                currentStart = i;
+            continue;
+        }
+        if (!event.nodeInfo?.path)
+            continue;
+        let entry = priorRuns[priorRuns.length - 1];
+        if (!entry || entry.invocationId !== invocationId) {
+            entry = { start: i, invocationId, paused: false };
+            priorRuns.push(entry);
+        }
+        if (raisedInterrupt(event))
+            entry.paused = true;
+    }
+    let boundary = currentStart;
+    for (let i = priorRuns.length - 1; i >= 0 && priorRuns[i].paused; i--)
+        boundary = priorRuns[i].start;
+    return events.slice(boundary);
+}
+// ── 2. The answers ───────────────────────────────────────────────────────────
+/** ADK's responseSchemasByInterruptId: the schema each input request declared. */
+export function responseSchemasByInterruptId(events) {
+    const schemas = new Map();
+    for (const event of events) {
+        for (const part of partsOf(event)) {
+            const call = part.functionCall;
+            if (call?.name !== INPUT_REQUEST || !call.id)
+                continue;
+            const schema = call.args?.[RESPONSE_SCHEMA_ARG];
+            if (schema)
+                schemas.set(call.id, schema);
+        }
+    }
+    return schemas;
+}
+/** ADK's acceptsString: whether a JSON Schema admits a string. */
+function acceptsString(schema) {
+    if (!isRecord(schema))
+        return false;
+    const type = schema.type;
+    if (type === 'string')
+        return true;
+    if (Array.isArray(type) && type.includes('string'))
+        return true;
+    for (const key of ['anyOf', 'oneOf']) {
+        const branches = schema[key];
+        if (Array.isArray(branches) && branches.some(acceptsString))
+            return true;
+    }
+    return false;
+}
+/** ADK's unwrapResponse: `{ result: x }` is x, a JSON string parsed unless the schema takes a string. */
+export function unwrapResponse(response, responseSchema) {
+    if (isRecord(response) && Object.keys(response).length === 1 && RESULT_KEY in response) {
+        const value = response[RESULT_KEY];
+        if (typeof value !== 'string' || acceptsString(responseSchema))
+            return value;
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return response;
+}
+/**
+ * ADK's interruptResponseMismatch: a structured reply (an object) that the
+ * request's schema refuses, as ADK's message; a scalar reply, or a schema
+ * zod cannot read, is not checked.
+ */
+export function interruptResponseMismatch(interruptId, value, jsonSchema) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (jsonSchema === null || typeof jsonSchema !== 'object')
+        return undefined;
+    let validator;
+    try {
+        validator = z.fromJSONSchema(jsonSchema);
+    }
+    catch {
+        return undefined;
+    }
+    const result = validator.safeParse(value);
+    if (result.success)
+        return undefined;
+    const issues = result.error.issues
+        .map((issue) => `${issue.message}${issue.path.length ? ` at '${issue.path.join('.')}'` : ''}`)
+        .join('; ');
+    return `The reply to interrupt '${interruptId}' does not match the responseSchema it declared: ${issues}. A structured reply must either match that schema, or wrap a bare value as {result: <value>}; a plain-text reply is accepted as-is and is not checked. The interrupt is still waiting, so you can answer it again.`;
+}
+const waitingList = (open) => open.size ? `Still waiting: ${[...open].map((id) => `'${id}'`).join(', ')}.` : 'This run has no interrupt waiting for an answer.';
+function lastUserEvent(events) {
+    for (let i = events.length - 1; i >= 0; i--)
+        if (events[i].author === 'user')
+            return events[i];
+    return undefined;
+}
+/**
+ * ADK's resolvedInterruptResponses: every interrupt a function response in
+ * a user event answered, with the answer unwrapped. The newest user turn is
+ * held to account: a reply there to an interrupt that is not open, or one
+ * its schema refuses, throws ADK's message; an older one is skipped.
+ */
+export function resolvedInterruptResponses(events) {
+    const responseSchemas = responseSchemasByInterruptId(events);
+    const newestUserTurn = lastUserEvent(events);
+    const raised = new Set();
+    const open = new Set();
+    const resolved = new Map();
+    for (const event of events) {
+        if (event.author === 'user' && event.content?.parts) {
+            for (const part of event.content.parts) {
+                const response = part.functionResponse;
+                if (!response?.id)
+                    continue;
+                if (!open.has(response.id)) {
+                    if (response.name === INPUT_REQUEST && event === newestUserTurn) {
+                        throw new Error(raised.has(response.id)
+                            ? `Interrupt '${response.id}' has already been answered, so this reply resolves nothing. Sending it again does not change the earlier answer, and it would otherwise be served as a new message, restarting the node that asked. ${waitingList(open)}`
+                            : `The reply carries interrupt id '${response.id}', which does not match any interrupt this run raised. ${waitingList(open)} A reply must use the id from the 'adk_request_input' function call it answers. Nothing was resolved, so any waiting interrupt can still be answered.`);
+                    }
+                    continue;
+                }
+                const schema = responseSchemas.get(response.id);
+                const value = unwrapResponse(response.response, schema);
+                const mismatch = interruptResponseMismatch(response.id, value, schema);
+                if (mismatch) {
+                    if (event === newestUserTurn)
+                        throw new Error(mismatch);
+                    continue;
+                }
+                open.delete(response.id);
+                resolved.set(response.id, value);
+            }
+            continue;
+        }
+        for (const id of event.longRunningToolIds ?? []) {
+            raised.add(id);
+            open.add(id);
+        }
+    }
+    return resolved;
+}
+// ── 3. The node states ───────────────────────────────────────────────────────
+/** ADK's nodeNameFromPath: the last segment of a path, without its `@<run>` suffix. */
+export function nodeNameFromPath(path) {
+    let start = 0;
+    for (let i = 0; i < path.length; i++)
+        if (path[i] === '.' || path[i] === '/')
+            start = i + 1;
+    const leaf = path.slice(start);
+    const at = leaf.indexOf('@');
+    return at === -1 ? leaf : leaf.slice(0, at);
+}
+/** ADK's directChildName: the child of `parentPath` an event's path names, or undefined for any other path. */
+export function directChildName(path, parentPath) {
+    const prefix = `${parentPath}.`;
+    if (!path.startsWith(prefix))
+        return undefined;
+    const rest = path.slice(prefix.length);
+    if (rest.includes('.'))
+        return undefined;
+    const at = rest.indexOf('@');
+    return at === -1 ? rest : rest.slice(0, at);
+}
+const isRunClosed = (run) => run.output !== undefined || run.route !== undefined || run.interruptIds.size > 0;
+function keyFn(parentPath) {
+    if (parentPath)
+        return (event) => (event.nodeInfo?.path ? directChildName(event.nodeInfo.path, parentPath) : undefined);
+    return (event) => (event.nodeInfo?.path ? nodeNameFromPath(event.nodeInfo.path) : event.author);
+}
+/** ADK's reconstructRuns: each key's runs, a run closing on an output, a route or an interrupt. */
+function reconstructRuns(events, keyFor) {
+    const nodes = new Map();
+    const interruptOwner = new Map();
+    const resolved = resolvedInterruptResponses(events);
+    const currentRun = (name) => {
+        let runs = nodes.get(name);
+        if (!runs) {
+            runs = [];
+            nodes.set(name, runs);
+        }
+        const open = runs[runs.length - 1];
+        if (open && !isRunClosed(open))
+            return open;
+        const run = { interruptIds: new Set(), resolvedResponses: new Map() };
+        runs.push(run);
+        return run;
+    };
+    for (const event of events) {
+        if (event.author === 'user' && event.content?.parts) {
+            for (const part of event.content.parts) {
+                const id = part.functionResponse?.id;
+                if (id && interruptOwner.has(id) && resolved.has(id))
+                    interruptOwner.get(id).resolvedResponses.set(id, resolved.get(id));
+            }
+            continue;
+        }
+        const key = keyFor(event);
+        if (!key)
+            continue;
+        const run = currentRun(key);
+        if (event.output !== undefined) {
+            run.output = event.output;
+            run.branch = event.branch;
+        }
+        if (event.route !== undefined)
+            run.route = event.route;
+        for (const id of event.longRunningToolIds ?? []) {
+            run.interruptIds.add(id);
+            interruptOwner.set(id, run);
+        }
+        const agentState = event.actions?.agentState;
+        if (isRecord(agentState) && 'input' in agentState)
+            run.input = agentState.input;
+    }
+    return nodes;
+}
+/** ADK's reconstructNodeRuns: per direct child of `parentPath` (or per node name at the root), its runs in order. */
+export function reconstructNodeRuns(events, parentPath) {
+    return reconstructRuns(events, keyFn(parentPath));
+}
+/** ADK's reconstructNodeStates: each key's runs merged into one state. */
+export function reconstructNodeStates(events, parentPath) {
+    const merged = new Map();
+    for (const [key, runs] of reconstructRuns(events, keyFn(parentPath))) {
+        const node = { interruptIds: new Set(), resolvedResponses: new Map() };
+        for (const run of runs) {
+            if (run.output !== undefined) {
+                node.output = run.output;
+                node.branch = run.branch;
+            }
+            if (run.route !== undefined)
+                node.route = run.route;
+            if (run.input !== undefined)
+                node.input = run.input;
+            for (const id of run.interruptIds)
+                node.interruptIds.add(id);
+            for (const [id, value] of run.resolvedResponses)
+                node.resolvedResponses.set(id, value);
+        }
+        merged.set(key, node);
+    }
+    return merged;
+}
+/** ADK's isFastForwardable: the run produced an output or a route, and every interrupt it raised is answered. */
+export function isFastForwardable(run) {
+    if (run.output === undefined && run.route === undefined)
+        return false;
+    for (const id of run.interruptIds)
+        if (!run.resolvedResponses.has(id))
+            return false;
+    return true;
+}
+/**
+ * ADK's rerunOnResume, by node kind as lib/workflow.ts compiles them: an
+ * agent (LlmAgent), an ask_user node (its FunctionNode sets it) and a map
+ * (ParallelWorker) run again on resume; a tool node, a join and a route
+ * step (BaseNode's default) do not, and resolve to their answers instead.
+ */
+export function rerunsOnResume(node) {
+    return node.kind === 'agent' || node.kind === 'ask_user' || node.kind === 'map';
+}
+// ── 4. The walk's input, and the plain-text answer ───────────────────────────
+/** ADK's extractNodeInput: the message's text parts joined, else the message itself. */
+export function workflowNodeInput(content) {
+    if (!content)
+        return undefined;
+    const texts = (content.parts ?? []).filter((p) => typeof p.text === 'string');
+    if (texts.length > 0)
+        return texts.map((p) => p.text).join('');
+    return content;
+}
+/**
+ * ADK's resumeInputsFromPlainText: a message of text parts only answers the
+ * one interrupt left open in the run's events; with none or several open,
+ * it answers nothing (it is the walk's new input).
+ */
+export function resumeInputsFromPlainText(content, events, invocationId) {
+    const parts = content?.parts ?? [];
+    if (!(parts.length > 0 && parts.every((p) => typeof p.text === 'string')))
+        return {};
+    const text = parts.map((p) => p.text).join('');
+    const pending = new Set();
+    for (const state of reconstructNodeStates(eventsForCurrentRun(events, invocationId)).values()) {
+        for (const id of state.interruptIds)
+            if (!state.resolvedResponses.has(id))
+                pending.add(id);
+    }
+    if (pending.size !== 1)
+        return {};
+    const [id] = pending;
+    return { [id]: text };
+}
+// ── What the native walk cannot resume yet ───────────────────────────────────
+/**
+ * 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 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 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) {
+        if (event.author === 'user' || !(event.longRunningToolIds?.length))
+            continue;
+        const path = event.nodeInfo?.path ?? '';
+        if (path === workflowPath)
+            continue;
+        if (directChildName(path, workflowPath) === undefined)
+            throw new UnsupportedWorkflowResumeError(path || String(event.author ?? ''), 'inside a nested node (a map item)');
+        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');
+    }
+}
+/**
+ * Everything a walk needs to resume as ADK's does: the new message as the
+ * walk's input, the prior runs of each node of the workflow, and the
+ * answers. On a session with nothing paused, every node runs fresh (its
+ * prior runs belong to finished invocations, which the run's events leave
+ * out). Throws ADK's message for a reply that answers nothing open, and
+ * UnsupportedWorkflowResumeError for a pause only ADK can resume.
+ */
+export function workflowResume(request) {
+    const resumeInputs = resumeInputsFromPlainText(request.userContent, request.events, request.invocationId);
+    const runEvents = eventsForCurrentRun(request.events, request.invocationId);
+    assertResumable(runEvents, request.workflowPath);
+    const priorRuns = reconstructNodeRuns(runEvents, request.workflowPath || undefined);
+    // ADK's applyResumeInputs: the explicit answers, over the plain-text one.
+    for (const [id, value] of resolvedInterruptResponses(runEvents))
+        resumeInputs[id] = value;
+    return { input: workflowNodeInput(request.userContent), resume: { priorRuns, resumeInputs } };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * lib/workflow/route.ts — the route a workflow node's output takes, and the
+ * event a route step stores (ADR 0030, ADR 0090).
+ *
+ * ADK's TypeScript port never derives a route from an agent's output, so a
+ * routing map after a node gets a hidden step, `<Node>__route`, that reads
+ * the route from the output and re-emits the output with it (lib/workflow.ts
+ * compiles it as a FunctionNode; lib/workflow/scheduler.ts runs it itself).
+ * The rule is one function both runtimes call, `routeOf`:
+ *
+ *   - an object output (an agent with an output schema, a join, a tool's
+ *     result): its `route_key` property, `route` by default, trimmed, `''`
+ *     when the property is absent or null;
+ *   - a string output: the text, trimmed. A JSON object an agent WITHOUT an
+ *     output schema writes is text, as ADK keeps it (run_llm_agent_as_node's
+ *     maybeSetOutput parses only with a schema), so it routes on its whole
+ *     text, which usually takes the `default` edge;
+ *   - anything else: its string form, trimmed; `''` for undefined or null.
+ *
+ * The scheduler then matches the route against the keys in ADK's spelling
+ * and takes the `default` edge when no key matched (scheduler.ts nextNodes),
+ * so the default catches every route no key names, `''` included.
+ *
+ * `routeStepEvent` is the event ADK's route step stores, so a session the
+ * native walk writes holds what ADK's holds: authored by the step, the
+ * output and the route, the step's node path, no content.
+ *
+ * No ADK import: the ADK path (lib/workflow.ts) imports `routeOf` from here
+ * through lib/workflowConfig.ts.
+ */
+import type { TurnEvent } from '../runtime/events.ts';
+/** The route_key a routing map reads when the node sets none. */
+export declare const DEFAULT_ROUTE_PROPERTY = "route";
+/**
+ * The route a node's output takes: the `routeKey` property of an object
+ * output, else the trimmed text, else `''`. Linear in the output's size; no
+ * regular expression.
+ */
+export declare function routeOf(output: unknown, routeKey?: string): string;
+/** Where a route step ran: the scheduler's node_end for it. */
+export interface RouteStepRun {
+    /** The step's name, `<Node>__route`. */
+    name: string;
+    /** Its node path, `<workflow>.<Node>__route`. */
+    path: string;
+    branch: string | undefined;
+    invocationId: string;
+    /** The output it re-emits: its predecessor's. */
+    output: unknown;
+    /** The route it emitted (routeOf). */
+    route: unknown;
+}
+/**
+ * The event ADK stores for a route step: its FunctionNode's createEvent
+ * (author, invocation, branch, output, route), stamped by the node runner
+ * with the step's path and `outputFor` (node_runner.js enrichEvent).
+ */
+export declare function routeStepEvent(run: RouteStepRun): TurnEvent;

package/dist/lib/workflow/route.js

@@ -0,0 +1,69 @@
+/**
+ * lib/workflow/route.ts — the route a workflow node's output takes, and the
+ * event a route step stores (ADR 0030, ADR 0090).
+ *
+ * ADK's TypeScript port never derives a route from an agent's output, so a
+ * routing map after a node gets a hidden step, `<Node>__route`, that reads
+ * the route from the output and re-emits the output with it (lib/workflow.ts
+ * compiles it as a FunctionNode; lib/workflow/scheduler.ts runs it itself).
+ * The rule is one function both runtimes call, `routeOf`:
+ *
+ *   - an object output (an agent with an output schema, a join, a tool's
+ *     result): its `route_key` property, `route` by default, trimmed, `''`
+ *     when the property is absent or null;
+ *   - a string output: the text, trimmed. A JSON object an agent WITHOUT an
+ *     output schema writes is text, as ADK keeps it (run_llm_agent_as_node's
+ *     maybeSetOutput parses only with a schema), so it routes on its whole
+ *     text, which usually takes the `default` edge;
+ *   - anything else: its string form, trimmed; `''` for undefined or null.
+ *
+ * The scheduler then matches the route against the keys in ADK's spelling
+ * and takes the `default` edge when no key matched (scheduler.ts nextNodes),
+ * so the default catches every route no key names, `''` included.
+ *
+ * `routeStepEvent` is the event ADK's route step stores, so a session the
+ * native walk writes holds what ADK's holds: authored by the step, the
+ * output and the route, the step's node path, no content.
+ *
+ * No ADK import: the ADK path (lib/workflow.ts) imports `routeOf` from here
+ * through lib/workflowConfig.ts.
+ */
+import { createTurnEvent } from '../runtime/events.js';
+/** The route_key a routing map reads when the node sets none. */
+export const DEFAULT_ROUTE_PROPERTY = 'route';
+/**
+ * The route a node's output takes: the `routeKey` property of an object
+ * output, else the trimmed text, else `''`. Linear in the output's size; no
+ * regular expression.
+ */
+export function routeOf(output, routeKey = DEFAULT_ROUTE_PROPERTY) {
+    if (output && typeof output === 'object' && !Array.isArray(output)) {
+        const value = output[routeKey];
+        if (value === undefined || value === null)
+            return '';
+        return String(value).trim();
+    }
+    if (typeof output === 'string')
+        return output.trim();
+    return output === undefined || output === null ? '' : String(output).trim();
+}
+/**
+ * The event ADK stores for a route step: its FunctionNode's createEvent
+ * (author, invocation, branch, output, route), stamped by the node runner
+ * with the step's path and `outputFor` (node_runner.js enrichEvent).
+ */
+export function routeStepEvent(run) {
+    const event = createTurnEvent({
+        author: run.name,
+        invocationId: run.invocationId,
+        ...(run.branch !== undefined ? { branch: run.branch } : {}),
+    });
+    if (run.output !== undefined)
+        event.output = run.output;
+    if (run.route !== undefined)
+        event.route = run.route;
+    // What enrichNodeEvent (lib/workflow/toolNode.ts) writes on this event, kept here so this module stays a leaf:
+    // lib/workflowConfig.ts re-exports routeOf, and the schema and the ADK path import it.
+    event.nodeInfo = { path: run.path, ...(run.output !== undefined ? { outputFor: [run.path] } : {}) };
+    return event;
+}