melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/tools/taskTools.d.ts

@@ -10,7 +10,9 @@
  *   a list of records with a status — so both live in one store:
  *
  *     kind: todo        the user's own tasks. open → done | cancelled.
- *     kind: background  a job for the worker. queued → running → done | failed.
+ *     kind: background  a job for the worker. queued → running → done | failed,
+ *                       and cancelled from queued or running (a running job's
+ *                       worker sees it at its next renewal and stops).
  *
  *   The tools only WRITE the queue. They never run a job: a tool that
  *   orchestrates agents is exactly what the tool-contract doctrine refuses
@@ -28,11 +30,18 @@
  *     gitignored). Every operation re-reads the file, so the chat process
  *     and the worker see each other's writes. It is SINGLE-USER: every
  *     caller shares one list. Run ONE worker: the claim is a
- *     read-modify-write, not a lock.
+ *     read-modify-write, not a lock. A running job's step checkpoints
+ *     (ADR 0113) sit in a sidecar, <store>.checkpoints.json, keyed by id;
+ *     every write of the store drops those of jobs no longer running or
+ *     queued. A checkpoint above the cap (TaskBackendOptions.
+ *     checkpointMaxBytes, default 5 MiB of JSON) is not saved, on either
+ *     store: the job keeps its previous one and one line names the job id
+ *     and the sizes.
  *   - With Postgres (postgresStorage().taskQueue, migration 0009) each
  *     caller has its own list, scoped by the caller the tool call carries
  *     (the A2A server's scope key), and any number of workers claim jobs
- *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021).
+ *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021). The
+ *     checkpoint is a column beside the record (migration 0014).
  *
  * SECURITY:
  *   On the file store every caller of a shared endpoint shares one list: do
@@ -95,8 +104,13 @@ export interface TaskBackend {
     mutate<T>(owner: string, change: (store: TaskStore) => T): Promise<T>;
     /** The oldest queued background job of any owner, now running and leased. */
     claimNext(worker: WorkerLease): Promise<OwnedTask | null>;
-    /** Keeps a claimed job leased while it runs. */
-    renew(worker: WorkerLease, job: OwnedTask): Promise<void>;
+    /**
+     * Keeps a claimed job leased while it runs. Resolves false when the claim
+     * is gone (the job left `running`, for instance cancelled with
+     * task_update, or another worker holds it): the worker must stop the run.
+     * A backend that resolves void makes no such claim.
+     */
+    renew(worker: WorkerLease, job: OwnedTask): Promise<void | boolean>;
     /** Records a job's outcome; a record no longer running is left alone. */
     finish(job: OwnedTask, outcome: JobOutcome): Promise<void>;
     /** Jobs whose worker died: queued again, or failed after MAX_ATTEMPTS. */
@@ -104,7 +118,45 @@ export interface TaskBackend {
         requeued: string[];
         failed: string[];
     }>;
+    /**
+     * Durable runs (ADR 0113): stores the run's latest step checkpoint beside
+     * the job. Resolves false when the job is no longer this worker's running
+     * job (cancelled, finished, or re-leased): the run must stop.
+     *
+     * A checkpoint lives only while its job is `running` or `queued` (a job
+     * re-queued after an interruption keeps it, so the next claim resumes);
+     * any other status drops it, and so does a pruned or deleted record. It is
+     * kept beside the record, never in it, so task_get never shows it.
+     */
+    saveCheckpoint?(worker: WorkerLease, job: OwnedTask, checkpoint: object): Promise<boolean>;
+    /** The checkpoint a re-queued job left, or null. */
+    loadCheckpoint?(job: OwnedTask): Promise<object | null>;
 }
+/**
+ * The largest checkpoint a backend stores by default: 5 MiB of serialized
+ * JSON (ADR 0113). A save above the cap is skipped and the job's previous
+ * checkpoint kept, so a huge run resumes from an older step boundary instead
+ * of failing or bloating the table.
+ */
+export declare const DEFAULT_CHECKPOINT_MAX_BYTES: number;
+/** The worker's variable that moves the cap, in bytes (scripts/assistant_worker.ts). */
+export declare const CHECKPOINT_MAX_BYTES_ENV = "MELCHIZEDEK_CHECKPOINT_MAX_BYTES";
+/** How a backend stores checkpoints (fileTaskBackendWith, postgresTaskBackend). */
+export interface TaskBackendOptions {
+    /** The largest checkpoint stored, in bytes of serialized JSON. Default DEFAULT_CHECKPOINT_MAX_BYTES; a value that is not a positive integer is the default. */
+    checkpointMaxBytes?: number;
+    /** Where a skipped save is reported: one line naming the job id and the sizes, never the checkpoint. Default console.warn. */
+    log?: (line: string) => void;
+}
+/** The cap a variable's value sets: a positive whole number of bytes, else the default. */
+export declare function checkpointMaxBytesSetting(raw: string | undefined): number;
+/**
+ * The checkpoint serialized once, as the backend stores it, or null when it
+ * is above the cap: then one line is logged with the job id and the sizes
+ * only (the checkpoint carries the user's text and tool results), and the
+ * caller keeps the previous checkpoint.
+ */
+export declare function checkpointJson(job: Pick<OwnedTask, 'id'>, checkpoint: object, options?: TaskBackendOptions): string | null;
 /** Records kept at most; finished ones are pruned oldest-first to make room. */
 export declare const MAX_TASKS = 500;
 /** A worker result is stored up to this length, then cut with a marker. */
@@ -112,6 +164,7 @@ export declare const MAX_RESULT_CHARS = 20000;
 /** A job interrupted this many times is marked failed instead of re-queued. */
 export declare const MAX_ATTEMPTS = 2;
 export declare function taskStorePath(): string;
+export declare function taskCheckpointPath(storePath?: string): string;
 /**
  * Called once at worker start: a record left `running` means a worker died
  * mid-job. It goes back to the queue, or fails once it has been tried
@@ -129,7 +182,9 @@ export declare function finishJob(id: string, outcome: JobOutcome): void;
 export declare function applyFinish(store: TaskStore, id: string, outcome: JobOutcome): void;
 /** The interrupted-job rule for one record: back to the queue, or failed. */
 export declare function applyInterrupted(t: TaskRecord): 'requeued' | 'failed';
-/** The single-user JSON file (the default backend). */
+/** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */
+export declare function fileTaskBackendWith(options?: TaskBackendOptions): TaskBackend;
+/** The single-user JSON file (the default backend), checkpoints capped at DEFAULT_CHECKPOINT_MAX_BYTES. */
 export declare const fileTaskBackend: TaskBackend;
 /** Plugs in where tasks live (postgresStorage().taskQueue); default the JSON file. */
 export declare function setTaskBackend(backend: TaskBackend): void;

package/dist/lib/tools/taskTools.js

@@ -10,7 +10,9 @@
  *   a list of records with a status — so both live in one store:
  *
  *     kind: todo        the user's own tasks. open → done | cancelled.
- *     kind: background  a job for the worker. queued → running → done | failed.
+ *     kind: background  a job for the worker. queued → running → done | failed,
+ *                       and cancelled from queued or running (a running job's
+ *                       worker sees it at its next renewal and stops).
  *
  *   The tools only WRITE the queue. They never run a job: a tool that
  *   orchestrates agents is exactly what the tool-contract doctrine refuses
@@ -28,11 +30,18 @@
  *     gitignored). Every operation re-reads the file, so the chat process
  *     and the worker see each other's writes. It is SINGLE-USER: every
  *     caller shares one list. Run ONE worker: the claim is a
- *     read-modify-write, not a lock.
+ *     read-modify-write, not a lock. A running job's step checkpoints
+ *     (ADR 0113) sit in a sidecar, <store>.checkpoints.json, keyed by id;
+ *     every write of the store drops those of jobs no longer running or
+ *     queued. A checkpoint above the cap (TaskBackendOptions.
+ *     checkpointMaxBytes, default 5 MiB of JSON) is not saved, on either
+ *     store: the job keeps its previous one and one line names the job id
+ *     and the sizes.
  *   - With Postgres (postgresStorage().taskQueue, migration 0009) each
  *     caller has its own list, scoped by the caller the tool call carries
  *     (the A2A server's scope key), and any number of workers claim jobs
- *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021).
+ *     with FOR UPDATE SKIP LOCKED under a renewed lease (ADR 0021). The
+ *     checkpoint is a column beside the record (migration 0014).
  *
  * SECURITY:
  *   On the file store every caller of a shared endpoint shares one list: do
@@ -48,6 +57,43 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 import { dirname, join, resolve } from 'node:path';
 import { z } from 'zod';
 import { defineTool } from './toolContract.js';
+/**
+ * The largest checkpoint a backend stores by default: 5 MiB of serialized
+ * JSON (ADR 0113). A save above the cap is skipped and the job's previous
+ * checkpoint kept, so a huge run resumes from an older step boundary instead
+ * of failing or bloating the table.
+ */
+export const DEFAULT_CHECKPOINT_MAX_BYTES = 5 * 1024 * 1024;
+/** The worker's variable that moves the cap, in bytes (scripts/assistant_worker.ts). */
+export const CHECKPOINT_MAX_BYTES_ENV = 'MELCHIZEDEK_CHECKPOINT_MAX_BYTES';
+const validCap = (n) => typeof n === 'number' && Number.isSafeInteger(n) && n > 0;
+/** The cap a variable's value sets: a positive whole number of bytes, else the default. */
+export function checkpointMaxBytesSetting(raw) {
+    const value = raw?.trim() ?? '';
+    if (!/^\d+$/.test(value))
+        return DEFAULT_CHECKPOINT_MAX_BYTES;
+    const n = Number(value);
+    return validCap(n) ? n : DEFAULT_CHECKPOINT_MAX_BYTES;
+}
+/**
+ * The checkpoint serialized once, as the backend stores it, or null when it
+ * is above the cap: then one line is logged with the job id and the sizes
+ * only (the checkpoint carries the user's text and tool results), and the
+ * caller keeps the previous checkpoint.
+ */
+export function checkpointJson(job, checkpoint, options = {}) {
+    const cap = validCap(options.checkpointMaxBytes) ? options.checkpointMaxBytes : DEFAULT_CHECKPOINT_MAX_BYTES;
+    const json = JSON.stringify(checkpoint);
+    // One UTF-16 unit is at most three UTF-8 bytes: a short string is under the cap without counting.
+    if (json.length * 3 <= cap)
+        return json;
+    const bytes = Buffer.byteLength(json, 'utf8');
+    if (bytes <= cap)
+        return json;
+    const log = options.log ?? ((line) => console.warn(`[tasks] ${line}`));
+    log(`checkpoint for job ${job.id} not saved: ${bytes} bytes is over the ${cap}-byte cap; the previous checkpoint is kept`);
+    return null;
+}
 /** Records kept at most; finished ones are pruned oldest-first to make room. */
 export const MAX_TASKS = 500;
 /** A worker result is stored up to this length, then cut with a marker. */
@@ -73,18 +119,62 @@ function readStore(path = taskStorePath()) {
     }
     return { version: 1, next_id: parsed.next_id, tasks: parsed.tasks };
 }
-function writeStore(store, path = taskStorePath()) {
+/** Atomic write: temp file + rename, so a reader never sees half a file. */
+function writeText(text, path) {
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`);
+    writeFileSync(tmp, text);
     renameSync(tmp, path);
 }
+/** Atomic JSON write. */
+function writeJson(value, path) {
+    writeText(`${JSON.stringify(value, null, 2)}\n`, path);
+}
+function writeStore(store, path = taskStorePath()) {
+    writeJson(store, path);
+}
+/** Statuses a job's checkpoint survives in. */
+const CHECKPOINTED = ['running', 'queued'];
+export function taskCheckpointPath(storePath = taskStorePath()) {
+    return `${storePath}.checkpoints.json`;
+}
+/** The sidecar, or empty when missing or unreadable (a checkpoint is an optimisation, never the record). */
+function readCheckpoints(storePath) {
+    const path = taskCheckpointPath(storePath);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const keepsCheckpoint = (t) => !!t && t.kind === 'background' && CHECKPOINTED.includes(t.status);
+/** Drops sidecar entries whose job is gone or no longer running/queued. */
+function pruneCheckpoints(store, storePath) {
+    if (!existsSync(taskCheckpointPath(storePath)))
+        return;
+    const entries = readCheckpoints(storePath);
+    const byId = new Map(store.tasks.map((t) => [t.id, t]));
+    let changed = false;
+    for (const id of Object.keys(entries)) {
+        if (!keepsCheckpoint(byId.get(id))) {
+            delete entries[id];
+            changed = true;
+        }
+    }
+    if (changed)
+        writeJson(entries, taskCheckpointPath(storePath));
+}
 /** Read, change, write — one synchronous step, so no await splits it. */
 function mutate(change) {
     const path = taskStorePath();
     const store = readStore(path);
     const out = change(store);
     writeStore(store, path);
+    pruneCheckpoints(store, path);
     return out;
 }
 const now = () => new Date().toISOString();
@@ -204,18 +294,51 @@ export function applyInterrupted(t) {
     t.status = 'queued';
     return 'requeued';
 }
-/** The single-user JSON file (the default backend). */
-export const fileTaskBackend = {
-    read: async () => readStore(),
-    mutate: async (_owner, change) => mutate(change),
-    claimNext: async () => {
-        const job = claimNextJob();
-        return job ? { ...job, owner: '' } : null;
-    },
-    renew: async () => { },
-    finish: async (job, outcome) => finishJob(job.id, outcome),
-    recover: async () => recoverInterruptedJobs(),
-};
+/**
+ * The sidecar with one job's checkpoint set from its serialized JSON, which
+ * is spliced in as it is rather than parsed and serialized again. The other
+ * entries are written compact; both shapes read back the same.
+ */
+function writeCheckpointEntry(storePath, id, json) {
+    const { [id]: _replaced, ...rest } = readCheckpoints(storePath);
+    const others = JSON.stringify(rest);
+    const entry = `${JSON.stringify(id)}:{"checkpoint":${json},"at":${JSON.stringify(now())}}`;
+    writeText(`${others === '{}' ? `{${entry}}` : `${others.slice(0, -1)},${entry}}`}\n`, taskCheckpointPath(storePath));
+}
+/** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */
+export function fileTaskBackendWith(options = {}) {
+    return {
+        read: async () => readStore(),
+        mutate: async (_owner, change) => mutate(change),
+        claimNext: async () => {
+            const job = claimNextJob();
+            return job ? { ...job, owner: '' } : null;
+        },
+        // No leases on the single-user file: the claim holds while the record is running.
+        renew: async (_worker, job) => readStore().tasks.find((t) => t.id === job.id)?.status === 'running',
+        finish: async (job, outcome) => finishJob(job.id, outcome),
+        recover: async () => recoverInterruptedJobs(),
+        saveCheckpoint: async (_worker, job, checkpoint) => {
+            const path = taskStorePath();
+            const record = readStore(path).tasks.find((t) => t.id === job.id);
+            if (!record || record.kind !== 'background' || record.status !== 'running')
+                return false;
+            // Over the cap: nothing written, the previous checkpoint kept, the claim still held.
+            const json = checkpointJson(job, checkpoint, options);
+            if (json !== null)
+                writeCheckpointEntry(path, job.id, json);
+            return true;
+        },
+        loadCheckpoint: async (job) => {
+            const path = taskStorePath();
+            if (!keepsCheckpoint(readStore(path).tasks.find((t) => t.id === job.id)))
+                return null;
+            return readCheckpoints(path)[job.id]?.checkpoint ?? null;
+        },
+    };
+}
+/** The single-user JSON file (the default backend), checkpoints capped at DEFAULT_CHECKPOINT_MAX_BYTES. */
+export const fileTaskBackend = fileTaskBackendWith();
 let activeBackend = fileTaskBackend;
 /** Plugs in where tasks live (postgresStorage().taskQueue); default the JSON file. */
 export function setTaskBackend(backend) {
@@ -318,7 +441,8 @@ export const taskGetContract = defineTool({
 export const taskUpdateContract = defineTool({
     name: 'task_update',
     description: 'Change a task: mark it done, cancel it, reopen it, or edit its title, notes, or due date. ' +
-        'For a background job, "cancelled" withdraws it before it runs and "queued" retries a failed or cancelled job. ' +
+        'For a background job, "cancelled" withdraws it before it runs, or stops it if it is running now ' +
+        '(the worker stops at its next step and keeps no result); "queued" retries a failed or cancelled job. ' +
         'Call task_list first if you do not have the id.',
     schema: z.object({
         id: taskId,
@@ -340,9 +464,9 @@ export const taskUpdateContract = defineTool({
                 return `Error: a ${task.kind} task cannot be set to "${status}". Allowed: ${allowed[task.kind].join(', ')}.`;
             }
             if (task.kind === 'background') {
-                if (task.status === 'running') {
-                    return `Error: ${id} is running now. Wait for it to finish, then read it with task_get.`;
-                }
+                // Cancelling a running job is allowed: its worker's next lease
+                // renewal or checkpoint sees the record left `running` and stops
+                // the run, and the worker's outcome is then left alone (applyFinish).
                 if (status === 'queued' && !['failed', 'cancelled'].includes(task.status)) {
                     return `Error: only a failed or cancelled job can be queued again; ${id} is ${task.status}.`;
                 }

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

@@ -63,6 +63,7 @@
  */
 import type { ModelAdapter } from '../models/contract.ts';
 import type { TurnEvent } from '../runtime/events.ts';
+import type { WorkflowSubagentEnd } from '../runtime/native/delegate.ts';
 import type { MemoryService } from '../runtime/memoryService.ts';
 import type { NativeAgent } from '../runtime/native/request.ts';
 import type { SelfCorrection } from '../runtime/native/selfCorrection.ts';
@@ -93,15 +94,33 @@ export interface NativeWorkflowParams {
     selfCorrection?: SelfCorrection;
     /** The run's tool credentials, pinned to its app (ADR 0072). */
     credentials?: Pick<CredentialStore, 'get'>;
-    /** The agent nodes that are a nested workflow syndicate, by YAML name (ADR 0106). */
-    workflows?: ReadonlyMap<string, NestedWorkflow>;
+    /** The agent nodes that are a nested workflow syndicate (ADR 0106) or a nested dispatch syndicate (ADR 0120), by YAML name. */
+    workflows?: ReadonlyMap<string, NestedWorkflow | NestedRun>;
 }
 /** A workflow syndicate run as a node of another (ADR 0106): its graph, its agents, its tool nodes' lookup, and its own nested nodes. */
 export interface NestedWorkflow {
     graph: WorkflowGraph;
     agents: ReadonlyMap<string, NativeAgent>;
     resolveTool: (name: string) => unknown;
-    workflows?: ReadonlyMap<string, NestedWorkflow>;
+    workflows?: ReadonlyMap<string, NestedWorkflow | NestedRun>;
+}
+/** Where a node's own run goes: its child session, the message, the turn's signal. */
+export interface NestedRunParams {
+    sessions: SessionService;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    userParts: unknown[];
+    signal?: AbortSignal;
+}
+/**
+ * A node that runs as something other than a graph (ADR 0120): a nested
+ * dispatch syndicate, its own turn (lib/runtime/native/delegate.ts
+ * nestedDispatchWalk). It runs where a nested workflow's walk runs, on the
+ * same child session, and ends as a walk ends.
+ */
+export interface NestedRun {
+    walk(run: NestedRunParams): AsyncGenerator<TurnEvent, WorkflowSubagentEnd | undefined>;
 }
 /** How the walk ended. */
 export interface NativeWorkflowEnd {

package/dist/lib/workflow/turn.js

@@ -62,7 +62,10 @@
  * carries, never instructions this module acts on.
  */
 import { randomUUID } from 'node:crypto';
-import { createTurnEvent } from '../runtime/events.js';
+import { APPROVAL_REQUEST } from '../runtime/approvals.js';
+import { createTurnEvent, getFunctionCalls } from '../runtime/events.js';
+import { entrySession } from '../runtime/native/delegate.js';
+import { INPUT_REQUEST } from '../workflowConfig.js';
 import { traceNodeExecution, traceToolNodeCall, traceWorkflowInvocation } from '../runtime/native/telemetry.js';
 import { TEMP_STATE_PREFIX } from '../runtime/sessions.js';
 import { NodeStoppedError, agentNodeRuntime, nodeInputContent } from './agentNode.js';
@@ -78,41 +81,150 @@ function lastText(event) {
         .filter((t) => t)
         .join('\n');
 }
+/** The requests a walk's interrupts are, as a node raises them: an approval request or an input request. */
+const RAISED = new Set([APPROVAL_REQUEST, INPUT_REQUEST]);
+/** The latest request call, by id, among `ids` that `events` hold (an agent's or a node's, never the user's). */
+function requestCalls(events, ids, author) {
+    const wanted = new Set(ids);
+    const calls = new Map();
+    for (let i = events.length - 1; i >= 0 && calls.size < wanted.size; i--) {
+        const event = events[i];
+        if (!event.author || event.author === 'user' || (author !== undefined && event.author !== author))
+            continue;
+        for (const call of getFunctionCalls(event)) {
+            if (call.id && call.name && RAISED.has(call.name) && wanted.has(call.id) && !calls.has(call.id))
+                calls.set(call.id, call);
+        }
+    }
+    return calls;
+}
+/**
+ * Whether a resumed walk's answer to `call` answers it: a decision for an
+ * approval request (a ToolConfirmation, or ADK's `{ response: <json> }`
+ * form, as lib/workflow/agentNode.ts reads one), any answer for an input
+ * request.
+ */
+function answers(call, value) {
+    if (value === undefined || !call)
+        return false;
+    if (call.name !== APPROVAL_REQUEST)
+        return true;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const answer = value;
+    return typeof answer.confirmed === 'boolean' || typeof answer.response === 'string';
+}
+/** The part that carries `value` down to the nested walk, as the answer to `call`: its explicit reply, under the request's name. */
+function answerPart(call, value) {
+    const response = call.name === APPROVAL_REQUEST ? value : { result: value };
+    return { functionResponse: { id: call.id, name: call.name, response } };
+}
+/**
+ * A node whose answered interrupts an earlier resume already carried down
+ * (another node's answer was the one since): the output it stored after
+ * the last event that raised them, else undefined.
+ */
+function outputAfterRaise(events, path, ids) {
+    const open = new Set(ids);
+    let start = -1;
+    events.forEach((event, i) => {
+        if (event.nodeInfo?.path === path && (event.longRunningToolIds ?? []).some((id) => open.has(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;
+}
+/**
+ * The node's pause on its caller's walk (ADR 0119): every request its own
+ * walk waits on, raised again as one event of the node's (a copy of each
+ * call, stamped with the node's path, the ids in `longRunningToolIds`, the
+ * node's input recorded for the resume), so the caller's walk pauses on
+ * the same ids, its resume reruns the node with their answers, and the
+ * turn finds the request (lib/runtime/native/interrupts.ts follows it down
+ * by id to the node that asked). Carries the walk's state writes so far.
+ */
+function raiseAgain(name, run, invocationId, calls, stateDelta) {
+    const event = createTurnEvent({
+        author: name,
+        invocationId,
+        content: { role: 'model', parts: calls.map((call) => ({ functionCall: structuredClone(call) })) },
+        ...(Object.keys(stateDelta).length ? { actions: { stateDelta } } : {}),
+    });
+    event.longRunningToolIds = calls.map((call) => call.id);
+    enrichNodeEvent(event, run, { invocationId });
+    event.actions = { ...event.actions, agentState: { ...(event.actions?.agentState ?? {}), input: run.input } };
+    return event;
+}
 /**
  * Runs `workflow` as the node `run` names (ADR 0106), as a delegated nested
  * workflow runs (ADR 0098): the whole graph walked on the child session
- * under the node's name (created from the caller's state the first time,
- * `temp:` keys dropped, and kept), the node's input as its message, its last
- * yielded event's text the node's output. The caller stores one event for
- * the node, carrying that output and the walk's state writes, so a resumed
- * walk completes the node from it. A walk that ends paused is refused by
- * name: a pause cannot reach the caller's walk yet (WS6-2).
+ * filed under the walk's app name and the node's behind its kind
+ * (`<walk's app>/node:<node>`, entryAppName, ADR 0119, ADR 0120; the one
+ * under an older key is continued when it ran there before), created from the caller's state the first time, `temp:` keys
+ * dropped, and kept; the node's input as its message, its last yielded
+ * event's text the node's output. The caller stores one event for the
+ * node, carrying that output and the walk's state writes, so a resumed
+ * walk completes the node from it.
+ *
+ * A walk that ends paused (an ask_user node, a gated agent node, a node of
+ * its own that is a nested workflow) pauses the node on the same ids
+ * (raiseAgain), and the caller's walk with it. Rerun on the resume, the
+ * node walks its graph again on the answers among its ids, each as its
+ * explicit reply (an approval decision as it came, an input request's
+ * answer as `{ result }`), which the nested walk's resume reads as a
+ * top-level one's; with none of them answered it waits again without
+ * walking; once an earlier resume finished it, its stored output is the
+ * node's.
  */
 async function runWorkflowNode(name, workflow, run, params, parent) {
-    const { sessions, userId, sessionId } = params;
-    const key = { appName: name, userId, sessionId };
+    const { sessions } = params;
+    const resumed = run.resumedInterruptIds ?? [];
+    let userParts;
+    if (resumed.length > 0) {
+        const raised = requestCalls(parent.session.events, resumed, name);
+        const answered = resumed.filter((id) => answers(raised.get(id), run.resumeInputs?.[id]));
+        if (answered.length === 0) {
+            parent.store(raiseAgain(name, run, parent.invocationId, resumed.map((id) => raised.get(id)).filter((c) => !!c), {}));
+            return { interruptIds: [...resumed] };
+        }
+        const finished = answered.length === resumed.length ? outputAfterRaise(parent.session.events, run.path, resumed) : undefined;
+        if (finished !== undefined)
+            return { output: finished };
+        userParts = answered.map((id) => answerPart(raised.get(id), run.resumeInputs[id]));
+    }
+    else {
+        const input = run.input === undefined || run.input === null ? parent.userContent : nodeInputContent(run.input);
+        userParts = input.parts ?? [];
+    }
     const state = Object.fromEntries(Object.entries(parent.session.state ?? {}).filter(([k]) => !k.startsWith(TEMP_STATE_PREFIX)));
-    if (!(await sessions.get(key)))
-        await sessions.create({ ...key, state });
-    const input = run.input === undefined || run.input === null ? parent.userContent : nodeInputContent(run.input);
-    const walk = runNativeWorkflow({
-        graph: workflow.graph,
-        agents: workflow.agents,
-        resolveTool: workflow.resolveTool,
-        ...(workflow.workflows ? { workflows: workflow.workflows } : {}),
-        sessions,
-        appName: name,
-        userId,
-        sessionId,
-        userParts: input.parts ?? [],
-        adapterFor: params.adapterFor,
-        signal: run.signal,
-        stream: false,
-        ...(params.memory ? { memory: params.memory } : {}),
-        ...(params.log ? { log: params.log } : {}),
-        ...(params.selfCorrection ? { selfCorrection: params.selfCorrection } : {}),
-        ...(params.credentials ? { credentials: params.credentials } : {}),
-    });
+    const child = await entrySession(sessions, { appName: parent.session.appName, userId: parent.session.userId, sessionId: parent.session.id, events: parent.session.events }, name, 'node', state, resumed.length > 0);
+    // A nested dispatch syndicate runs its own turn there (ADR 0120); a nested workflow walks its graph.
+    const walk = 'walk' in workflow
+        ? workflow.walk({ sessions, appName: child.appName, userId: child.userId, sessionId: child.id, userParts, ...(run.signal ? { signal: run.signal } : {}) })
+        : runNativeWorkflow({
+            graph: workflow.graph,
+            agents: workflow.agents,
+            resolveTool: workflow.resolveTool,
+            ...(workflow.workflows ? { workflows: workflow.workflows } : {}),
+            sessions,
+            appName: child.appName,
+            userId: child.userId,
+            sessionId: child.id,
+            userParts,
+            adapterFor: params.adapterFor,
+            signal: run.signal,
+            stream: false,
+            ...(params.memory ? { memory: params.memory } : {}),
+            ...(params.log ? { log: params.log } : {}),
+            ...(params.selfCorrection ? { selfCorrection: params.selfCorrection } : {}),
+            ...(params.credentials ? { credentials: params.credentials } : {}),
+        });
     let last;
     const stateDelta = {};
     let end;
@@ -133,7 +245,15 @@ async function runWorkflowNode(name, workflow, run, params, parent) {
         throw new NodeStoppedError(name, undefined);
     const paused = end.run?.interruptIds ?? [];
     if (paused.length > 0) {
-        throw new Error(`Node '${name}': the workflow it runs paused on ${paused.join(', ')}; a pause inside a workflow run as a node cannot reach the walk yet.`);
+        const walked = (await sessions.get({ appName: child.appName, userId: child.userId, sessionId: child.id }))?.events ?? [];
+        // A nested dispatch syndicate names the calls it waits on: they may sit in a route's delegation below its conversation (ADR 0120).
+        const named = 'requests' in end && end.requests ? new Map(end.requests.map((call) => [call.id, call])) : undefined;
+        const raised = named ?? requestCalls(walked, paused);
+        const missing = paused.filter((id) => !raised.has(id));
+        if (missing.length > 0)
+            throw new Error(`Node '${name}': the ${'walk' in workflow ? 'syndicate' : 'workflow'} it runs paused on ${missing.join(', ')}, which is not an approval request or a question.`);
+        parent.store(raiseAgain(name, run, parent.invocationId, paused.map((id) => raised.get(id)), stateDelta));
+        return { interruptIds: [...paused] };
     }
     const output = lastText(last);
     const event = createTurnEvent({

package/dist/lib/workflow.d.ts

@@ -41,16 +41,23 @@
  * A delegated `yaml_reference` to a workflow syndicate is the whole graph,
  * walked under the subagent entry's name and description on a child
  * session (lib/compileNative.ts workflowSubagentOf); its 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).
+ * graph's last event's text. A walk that pauses (an `ask_user` node, a
+ * gated agent node) leaves the call open, and the turn ends input-required
+ * with the agent path down to the node; the answer walks the graph again
+ * (lib/runtime/native/delegate.ts resumeWorkflowSubagent, ADR 0111).
  *
  * ── As a dispatch route or a workflow node (ADR 0106) ────────────────────
  * A `yaml_reference` to a workflow syndicate runs its whole graph there too,
- * on the child session filed under the entry's name, as a subagent does. A
- * route's answer is what the graph would answer as its own syndicate
- * (lib/runtime/syndicateTurn.ts); a node's is the nested walk's
- * (lib/workflow/turn.ts). A map over one is refused (lib/compile.ts).
+ * on the child session filed under the agent path and its kind
+ * (`<app>/route:<entry>`, `<walk's app>/node:<entry>`, ADR 0119, ADR 0120),
+ * as a subagent does. A route's answer is what the graph would
+ * answer as its own syndicate (lib/runtime/syndicateTurn.ts); a node's is
+ * the nested walk's (lib/workflow/turn.ts). A map over one is refused
+ * (lib/compile.ts). Its pauses (an `ask_user` node, a gate) reach the turn
+ * with the path from the entry down to the node that asked: a route's
+ * through the route's pause record in the conversation, a node's through
+ * its own pause on the caller's walk; the answer walks the nested graph
+ * again (ADR 0119).
  *
  * ── Approval gates (ADR 0098, ADR 0106) ──────────────────────────────────
  * A tool in a node agent's `require_approval`, and a skill script