melchizedek-agents 1.1.0 → 1.3.0

package/dist/lib/runtime/syndicateTurn.js

@@ -41,7 +41,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { DEFAULT_MAX_STEPS } from '../config.js';
-import { agentGates, compileEntrySpec, compileSpec, compileWorkflowSpec, declaresApprovals, workflowAgentSpecs } from '../compile.js';
+import { agentGates, compileEntrySpec, compileSpec, compileWorkflowSpec, workflowAgentSpecs } from '../compile.js';
 import { compileNative, compileNativeWorkflow, nativeAdapterFor } from '../compileNative.js';
 import { nativeMemory, refuseOnNative, runNativeAgent } from './nativeTurn.js';
 import { createTurnEvent, getFunctionCalls, getFunctionResponses } from './events.js';
@@ -57,7 +57,7 @@ export { CREDENTIAL_REQUEST, credentialResponsePart, describeConsent, pendingCon
 export { chooseRuntime, describeRuntime, runtimeSetting, DEFAULT_RUNTIME, RUNTIMES, RuntimeRemovedError, UnsupportedOnRuntimeError } from './runtimeFlag.js';
 // The session store a turn takes when nothing durable is configured, and the engine's interfaces (ADR 0107).
 export { InProcessSessionService } from './sessions.js';
-import { ROUTE_STEP_SUFFIX, describeInput, inputRequestFrom, isWorkflowSyndicate } from '../workflow.js';
+import { ROUTE_STEP_SUFFIX, inputRequestFrom, isWorkflowSyndicate } from '../workflow.js';
 export { describeInput } from '../workflow.js';
 import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from '../dispatch.js';
 import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from '../grounding.js';
@@ -70,7 +70,10 @@ import { traceAgentRun } from '../observability/tracer.js';
 import { ProjectedSessionService, renderTranscriptDigest } from '../session/transcript.js';
 import { approvalDecisionIn, describeApproval, interruptedTurnStart, pendingApproval } from './approvals.js';
 import { pendingQuestion, questionAnswerPart, questionFrom, turnStartOfCall } from './questions.js';
-import { delegatedPauses } from './native/interrupts.js';
+import { deepestPause, delegatedPauses, nestedWorkflowPause, routePause } from './native/interrupts.js';
+import { consentPinnedTo, entrySession } from './native/delegate.js';
+import { workflowPauseEvent } from '../workflow/pause.js';
+import { INPUT_REQUEST } from '../workflowConfig.js';
 export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.js';
 export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.js';
 import { RemoteA2AAgent, remoteContextId, remoteToolOutput } from '../a2a/remoteAgent.js';
@@ -83,15 +86,28 @@ const CLASSIFIER_PREAMBLE = `RECENT CONVERSATION, oldest first — context for y
 // The defaults live with the loop's self-correction (lib/runtime/native/selfCorrection.ts).
 export { DEFAULT_MODEL_ERROR_RETRIES, DEFAULT_TOOL_ERROR_RETRIES } from './native/selfCorrection.js';
 // ── Draining one agent's stream ──────────────────────────────────────────────
-function formatToolArgs(args) {
-    if (!args || Object.keys(args).length === 0)
-        return '';
-    return Object.entries(args)
-        .map(([k, v]) => {
-        const raw = typeof v === 'string' ? v : JSON.stringify(v);
-        return `${k}=${raw.length > 60 ? `${raw.slice(0, 60)}...` : raw}`;
-    })
-        .join(', ');
+/**
+ * The shape of a tool call's arguments for a log line: the key names and the
+ * size, never a value. Arguments are model-chosen and routinely carry the
+ * person's words, and a server log is not where those belong (the ledger is
+ * the deliberate record, with its own retention).
+ */
+function describeToolArgs(args) {
+    const keys = args ? Object.keys(args) : [];
+    if (!keys.length)
+        return 'no args';
+    let bytes;
+    try {
+        bytes = Buffer.byteLength(JSON.stringify(args), 'utf8');
+    }
+    catch {
+        return `args: ${keys.join(', ')}`;
+    }
+    return `args: ${keys.join(', ')} (${bytes.toLocaleString()} bytes)`;
+}
+/** A pending question for a log line: who asks, never what. */
+function describeInputForLog(input) {
+    return `${input.node} asks a question${input.path?.length ? ` (${input.path.join(' → ')})` : ''}`;
 }
 /**
  * Drains one agent's event stream into a DrainedRun. The answer is the LAST
@@ -185,7 +201,7 @@ export async function drainAgentStream(stream, opts = {}) {
             if (inputRequest) {
                 // An ask_user node: the workflow waits for the person (lib/workflow.ts).
                 d.inputRequests.push(inputRequest);
-                ev.log?.(`⏸ ${describeInput(inputRequest)}`);
+                ev.log?.(`⏸ ${describeInputForLog(inputRequest)}`);
                 continue;
             }
             if (!name)
@@ -194,7 +210,7 @@ export async function drainAgentStream(stream, opts = {}) {
             if (opts.subagentNames?.has(name))
                 d.delegations.push(name);
             d.toolCalls.push({ agent: e.author ?? 'unknown', name, args });
-            ev.log?.(`→ Tool: ${name}(${formatToolArgs(args)})`);
+            ev.log?.(`→ Tool: ${name} by ${e.author ?? 'unknown'} — ${describeToolArgs(args)}`);
             if (opts.publishToolStatus)
                 ev.onProgress?.(`Invoking tool: ${name}`);
         }
@@ -281,6 +297,8 @@ export async function runSyndicateTurn(opts) {
         // `trace: false`: no span from anything the turn runs, to any sink.
         untraced: opts.trace === false,
     });
+    // A nested dispatch syndicate, wherever the turn reaches one, runs as a turn of its own under these controls (ADR 0120).
+    control.nestedDispatch = (run) => runNestedDispatch(opts, control, runtime, run);
     try {
         const run = () => runWithTurnControl(control, () => runTurnInner(opts, control, runtime));
         // A span a library opens through OpenTelemetry's own API (not the
@@ -307,7 +325,50 @@ function nativeWorkflowAgent(spec, opts) {
     const { graph, agents, resolveTool, workflows } = compileNativeWorkflow(spec);
     return { runtime: 'native-workflow', graph, agents, adapterFor: nativeAdapterFor(opts, workflowAgentSpecs(spec)), resolveTool, workflows };
 }
-async function runTurnInner(opts, control, _runtime) {
+/**
+ * A nested dispatch syndicate's own turn (ADR 0120): runTurnInner on its
+ * conversation (`run`, opened by the caller), under the turn's controls,
+ * with the turn's store, memory, credentials and log, never streamed, its
+ * guards left to the turn at the top (collectGuards already lists them
+ * there). Its result is read as a walk's end: the route's final text, the
+ * conversation's state writes, and what it waits on, by id.
+ */
+async function runNestedDispatch(opts, control, runtime, run) {
+    const sessions = run.sessions;
+    const key = { appName: run.appName, userId: run.userId, sessionId: run.sessionId };
+    const kept = (state) => Object.fromEntries(Object.entries(state ?? {}).filter(([k]) => !k.startsWith(TEMP_STATE_PREFIX)));
+    const before = new Map(Object.entries(kept((await sessions.get(key))?.state)).map(([k, v]) => [k, JSON.stringify(v)]));
+    const config = run.config;
+    const trace = opts.trace === false ? false : { ...(opts.trace ?? {}), syndicateName: config.syndicate_name ?? run.name };
+    const nested = await runTurnInner({
+        config,
+        parts: run.parts,
+        appName: run.appName,
+        userId: run.userId,
+        sessionId: run.sessionId,
+        sessionService: sessions,
+        ...(opts.memoryService ? { memoryService: opts.memoryService } : {}),
+        compile: run.compile,
+        ...(opts.toolCredentials ? { toolCredentials: opts.toolCredentials } : {}),
+        streaming: false,
+        trace,
+        events: { ...(opts.events?.log ? { log: opts.events.log } : {}), ...(opts.events?.warn ? { warn: opts.events.warn } : {}) },
+    }, control, runtime, { credentialApp: opts.appName });
+    const after = kept((await sessions.get(key))?.state);
+    const stateDelta = Object.fromEntries(Object.entries(after).filter(([k, v]) => before.get(k) !== JSON.stringify(v)));
+    const interruptId = nested.approval?.id ?? nested.input?.id ?? nested.consent?.id;
+    return {
+        status: nested.status,
+        text: nested.text,
+        stateDelta,
+        ...(interruptId ? { interruptId } : {}),
+        ...(nested.approval ? { approval: nested.approval } : {}),
+        ...(nested.input ? { input: nested.input } : {}),
+        ...(nested.consent ? { consent: nested.consent } : {}),
+        ...(nested.error ? { error: nested.error } : {}),
+    };
+}
+async function runTurnInner(opts, control, _runtime, nestedTurn) {
     const { config, appName, userId, sessionId, sessionService } = opts;
     const ev = opts.events ?? {};
     // Nested references load from the definition's bundle when it has one
@@ -322,11 +383,13 @@ async function runTurnInner(opts, control, _runtime) {
     const nativeOf = (spec) => ({ runtime: 'native', agent: compileNative(spec), adapterFor: nativeAdapterFor(compileOpts, spec) });
     /** The orchestrator (a DELEGATE root, or a dispatch classifier). */
     const compileRoot = async () => nativeOf(await compileSpec(config, compileOpts));
-    /** A dispatch route: one agent, or a nested workflow's whole graph (ADR 0106). */
+    /** A dispatch route: one agent, a nested workflow's whole graph (ADR 0106), or a nested dispatch syndicate's own turn (ADR 0120). */
     const compileRoute = async (routeCfg) => {
         const entry = await compileEntrySpec(routeCfg, compileOpts);
         if (entry.kind === 'workflow')
             return { ...nativeWorkflowAgent(entry.workflow, compileOpts), workflow: entry.workflow };
+        if (entry.kind === 'dispatch')
+            return { dispatch: entry.dispatch };
         return nativeOf(entry.spec);
     };
     // Self-correction (ADR 0075): one per turn, from the YAML's retries:.
@@ -374,14 +437,27 @@ async function runTurnInner(opts, control, _runtime) {
     const delegationKey = { sessions: sessionService, userId, sessionId, appName };
     /** The first pause waiting below an open delegated call in this conversation, `author`'s calls only when given. */
     const pauseBelow = async (events, author) => isWorkflowSyndicate(config) ? undefined : (await delegatedPauses(delegationKey, events, author))[0];
+    // Pauses inside nested workflows run as a dispatch route or a workflow node (ADR 0119).
+    const pauseKey = { ...delegationKey, appName };
+    /** A request a workflow's own session holds, raised by a node that is a nested workflow: the one its walk waits on, with the path. */
+    const deepen = (pending) => deepestPause(pauseKey, pending);
+    /** A dispatch route that is a nested workflow, its walk paused: the conversation's last event is its pause record. */
+    const routePaused = isDispatchSyndicate(config) ? await routePause(pauseKey, existing?.events ?? [], subagentNames) : undefined;
     let resumingBelow;
+    let resumingRoute;
     let resuming;
     if (decision) {
         resuming = pendingApproval(existing?.events ?? []);
+        if (resuming && isWorkflowSyndicate(config))
+            resuming = await deepen(resuming);
         if (!resuming) {
             resumingBelow = await pauseBelow(existing?.events ?? []);
             resuming = resumingBelow?.approval;
         }
+        if (!resuming && routePaused?.approval) {
+            resumingRoute = routePaused;
+            resuming = routePaused.approval;
+        }
         if (!resuming || resuming.id !== decision.id) {
             result.status = 'failed';
             result.error = { code: 'NO_PENDING_APPROVAL', message: `No approval ${decision.id} is waiting in this conversation.` };
@@ -394,17 +470,38 @@ async function runTurnInner(opts, control, _runtime) {
     // While a call waits for an OAuth grant, the next message resumes it once
     // the callback has stored the grant; until then it repeats the request and
     // runs nothing.
-    const credentialStore = opts.toolCredentials ? pinnedCredentialStore(opts.toolCredentials.store, appName) : undefined;
+    // A nested dispatch syndicate's turn reads and stores grants under the root's app, as a delegated subagent does (ADR 0118, ADR 0120).
+    const credentialApp = nestedTurn?.credentialApp ?? appName;
+    const credentialStore = opts.toolCredentials ? pinnedCredentialStore(opts.toolCredentials.store, credentialApp) : undefined;
+    const consentStep = opts.toolCredentials?.consent
+        ? nestedTurn
+            ? consentPinnedTo(opts.toolCredentials.consent, credentialApp)
+            : opts.toolCredentials.consent
+        : undefined;
     const consentPause = (pending) => {
         result.status = 'input-required';
         result.consent = pending;
         result.text = `Authorization needed: ${describeConsent(pending)}. Open the authorization link, then send any message to continue.`;
-        ev.log?.(`⏸ Authorization needed: ${pending.agent} → ${pending.provider}`);
+        ev.log?.(`⏸ Authorization needed: ${(pending.path ?? [pending.agent]).join(' → ')} → ${pending.provider}`);
         return finish();
     };
     let granting;
+    // A call waiting for a grant inside a delegated subagent (ADR 0118): the grant's answer is stored here, and the open call carries it down.
+    let grantingBelow;
+    // A dispatch route that is a nested dispatch syndicate, waiting for a grant (ADR 0120): its own turn checks the grant, then resumes or asks again.
+    let consentRoute;
     if (!decision && !isWorkflowSyndicate(config)) {
-        const open = pendingConsent(existing?.events ?? []);
+        let open = pendingConsent(existing?.events ?? []);
+        if (!open && config.subagents?.length) {
+            const below = await pauseBelow(existing?.events ?? []);
+            if (below?.consent) {
+                grantingBelow = below;
+                open = below.consent;
+            }
+        }
+        const routeWaits = !open && !!routePaused?.consent;
+        if (routeWaits)
+            open = routePaused.consent;
         if (open) {
             if (!credentialStore) {
                 result.status = 'failed';
@@ -413,16 +510,21 @@ async function runTurnInner(opts, control, _runtime) {
             }
             let granted = false;
             try {
-                granted = !!open.provider && !!(await credentialStore.get({ appName, userId, provider: open.provider }));
+                granted = !!open.provider && !!(await credentialStore.get({ appName: credentialApp, userId, provider: open.provider }));
             }
             catch {
                 // Expired or unreadable: not granted. The request stands.
             }
             if (!granted)
                 return consentPause(open);
-            granting = open;
-            parts = [credentialResponsePart(open.id, open.provider)];
-            ev.log?.(`✓ Authorization granted: ${open.agent} → ${open.provider}`);
+            // The route's own turn carries the grant's answer down to its call; the message goes to it as it came.
+            if (routeWaits)
+                consentRoute = routePaused;
+            else {
+                granting = open;
+                parts = [credentialResponsePart(open.id, open.provider)];
+            }
+            ev.log?.(`✓ Authorization granted: ${(open.path ?? [open.agent]).join(' → ')} → ${open.provider}`);
         }
     }
     // ── Questions (lib/runtime/questions.ts) ───────────────────────────────────
@@ -433,12 +535,21 @@ async function runTurnInner(opts, control, _runtime) {
     // A question asked inside a delegated subagent (ADR 0110) is answered the same way: the answer is stored here, and the
     // open call that leads to the asker carries it down; `answering` names that call and the agent that made it.
     let answering;
-    if (!decision && !granting && !isWorkflowSyndicate(config)) {
+    /** The parts a paused workflow route's walk resumes on, when the message answers its question: the answer as the explicit reply to its `adk_request_input` call (ADR 0119). */
+    let routeAnswer;
+    if (!decision && !granting && !consentRoute && !isWorkflowSyndicate(config)) {
         const plainText = parts.length > 0 && parts.every((p) => typeof p.text === 'string');
         const own = plainText ? pendingQuestion(existing?.events ?? []) : undefined;
         const below = plainText && !own ? await pauseBelow(existing?.events ?? []) : undefined;
         const question = own ?? below?.question;
-        if (question) {
+        if (!question && plainText && routePaused?.question) {
+            // The conversation stores the person's words; the route's walk reads them as the reply to the node that asked.
+            const waiting = routePaused.question;
+            answering = { agent: routePaused.route, id: waiting.id };
+            routeAnswer = [{ functionResponse: { id: waiting.id, name: INPUT_REQUEST, response: { result: messageText } } }];
+            ev.log?.(`✓ Answer to ${(waiting.path ?? [waiting.node]).join(' → ')}'s question`);
+        }
+        else if (question) {
             answering = below ? { agent: below.path[0], id: below.callIds[0] } : { agent: question.node, id: question.id };
             parts = [questionAnswerPart(question.id, messageText)];
             ev.log?.(`✓ Answer to ${(question.path ?? [question.node]).join(' → ')}'s question`);
@@ -447,13 +558,19 @@ async function runTurnInner(opts, control, _runtime) {
     /** The agent a dispatch turn must resume, and the call its interrupted turn holds. */
     const resumeTarget = resumingBelow
         ? { agent: resumingBelow.path[0], id: resumingBelow.callIds[0], why: 'resuming an approval' }
-        : resuming
-            ? { agent: resuming.agent, id: resuming.id, why: 'resuming an approval' }
-            : granting
-                ? { agent: granting.agent, id: granting.id, why: 'resuming after an authorization' }
-                : answering
-                    ? { ...answering, why: 'answering its question' }
-                    : undefined;
+        : resumingRoute
+            ? { agent: resumingRoute.route, id: resuming.id, why: 'resuming an approval' }
+            : consentRoute
+                ? { agent: consentRoute.route, id: consentRoute.consent.id, why: 'resuming after an authorization' }
+                : grantingBelow
+                    ? { agent: grantingBelow.path[0], id: grantingBelow.callIds[0], why: 'resuming after an authorization' }
+                    : resuming
+                        ? { agent: resuming.agent, id: resuming.id, why: 'resuming an approval' }
+                        : granting
+                            ? { agent: granting.agent, id: granting.id, why: 'resuming after an authorization' }
+                            : answering
+                                ? { ...answering, why: 'answering its question' }
+                                : undefined;
     /** After the answering run: is a call now waiting for a grant? */
     const awaitingConsent = async (agentName) => {
         if (!opts.toolCredentials?.consent)
@@ -476,7 +593,7 @@ async function runTurnInner(opts, control, _runtime) {
         result.status = 'input-required';
         result.input = input;
         result.text = input.message;
-        ev.log?.(`⏸ Input needed: ${describeInput(input)}`);
+        ev.log?.(`⏸ Input needed: ${describeInputForLog(input)}`);
         return finish();
     };
     /** After the answering run: does a pause wait inside a delegated call `agentName` left open (ADR 0110)? */
@@ -485,11 +602,13 @@ async function runTurnInner(opts, control, _runtime) {
         const below = await pauseBelow(after?.events ?? [], agentName);
         if (below?.approval)
             return pause(below.approval);
+        if (below?.consent)
+            return consentPause(below.consent);
         if (below?.question) {
             result.status = 'input-required';
             result.input = below.question;
             result.text = below.question.message;
-            ev.log?.(`⏸ Input needed: ${describeInput(below.question)} (${below.path.join(' → ')})`);
+            ev.log?.(`⏸ Input needed: ${describeInputForLog({ node: below.question.node, path: below.path })}`);
             return finish();
         }
         return undefined;
@@ -501,6 +620,16 @@ async function runTurnInner(opts, control, _runtime) {
         ev.log?.(`⏸ Approval needed: ${(pending.path ?? [pending.agent]).join(' → ')} → ${pending.tool}`);
         return finish();
     };
+    /** The turn waits on what a question asks. */
+    const question = (input) => {
+        result.status = 'input-required';
+        result.input = input;
+        result.text = input.message;
+        ev.log?.(`⏸ Input needed: ${describeInputForLog(input)}`);
+        return finish();
+    };
+    /** A nested workflow's walk, or a nested dispatch syndicate's turn, paused below a route (ADR 0119, ADR 0120): its approval request, its consent request, else its question. */
+    const pausedWalk = (paused) => paused.approval ? pause(paused.approval) : paused.consent ? consentPause(paused.consent) : question(paused.question);
     /** Run ONE agent against ONE session, under the turn's controls. */
     const runAgent = async (params) => {
         let stream;
@@ -541,7 +670,7 @@ async function runTurnInner(opts, control, _runtime) {
                 ...(selfCorrection ? { selfCorrection } : {}),
                 // Tool credentials and the consent step (ADR 0072, ADR 0085); the classifier's lane lists no tools.
                 ...(credentialStore ? { credentials: credentialStore } : {}),
-                ...(opts.toolCredentials?.consent && params.stage !== 'classify' ? { consent: opts.toolCredentials.consent } : {}),
+                ...(consentStep && params.stage !== 'classify' ? { consent: consentStep } : {}),
                 ...(compileOpts.log ? { log: compileOpts.log } : {}),
             });
         }
@@ -588,15 +717,27 @@ async function runTurnInner(opts, control, _runtime) {
     };
     /**
      * A dispatch route that is a workflow syndicate (ADR 0106): its whole graph
-     * walked on the child session filed under the route's name (`{ <route>,
-     * userId, sessionId }`, created from the conversation's state the first
-     * time, `temp:` keys dropped, and kept), as a delegated nested workflow
-     * walks (ADR 0098), and drained by the reader a workflow turn uses, so the
-     * route's answer is what the workflow would answer as its own syndicate.
-     * The conversation stores the message and the answer, one event authored
-     * by the route that carries the walk's state writes, so the classifier and
-     * the next route read the exchange as they read any route's. A node that
-     * gave up fails the turn NODE_FAILED, as a workflow turn does.
+     * walked on the child session filed under the agent path and its kind
+     * (`{ <app>/route:<route>, userId, sessionId }`, ADR 0119, ADR 0120; the
+     * one filed under an older key is continued when the route ran in the
+     * conversation before, entrySession),
+     * created from the conversation's state the first time, `temp:` keys
+     * dropped, and kept, as a delegated nested workflow walks (ADR 0098), and
+     * drained by the reader a workflow turn uses, so the route's answer is what
+     * the workflow would answer as its own syndicate. The conversation stores
+     * the message and the answer, one event authored by the route that carries
+     * the walk's state writes, so the classifier and the next route read the
+     * exchange as they read any route's. A node that gave up fails the turn
+     * NODE_FAILED, as a workflow turn does.
+     *
+     * A walk that ends paused (ADR 0119) stores the route's pause record in
+     * place of the answer: authored by the route at its own path, no content,
+     * the walk's open interrupts in `longRunningToolIds`, its state writes so
+     * far. While it is the conversation's last event the route waits: the
+     * turn reports the request or question with the path from the route down
+     * to the node that asked (interrupts.ts routePause), a decision or a
+     * plain-text answer resumes the route without classifying, and the walk
+     * reads the answer as its explicit reply (`routeAnswer`).
      */
     const runWorkflowRoute = async (route, agent, resolution) => {
         const store = sessionService;
@@ -605,14 +746,21 @@ async function runTurnInner(opts, control, _runtime) {
         if (!shared)
             throw new Error(`Session not found: ${sessionId} (appName=${appName}, userId=${userId})`);
         const kept = (state) => Object.fromEntries(Object.entries(state ?? {}).filter(([k]) => !k.startsWith(TEMP_STATE_PREFIX)));
-        const childKey = { appName: route, userId, sessionId };
-        const child = (await store.get(childKey)) ?? (await store.create({ ...childKey, state: kept(shared.state) }));
+        // Filed under the agent path (ADR 0119), else continued under the route's name alone where ADR 0106 filed it.
+        const resumingWalk = resumingRoute !== undefined || routeAnswer !== undefined;
+        const child = await entrySession(store, { appName, userId, sessionId, events: shared.events }, route, 'route', kept(shared.state), resumingWalk);
+        const childKey = { appName: child.appName, userId, sessionId };
         const before = new Map(Object.entries(kept(child.state)).map(([k, v]) => [k, JSON.stringify(v)]));
         const invocationId = `e-${randomUUID()}`;
         await store.append(shared, createTurnEvent({ invocationId, author: 'user', content: { role: 'user', parts } }));
+        /** The walk's state writes this turn, `temp:` keys aside: what the conversation's event for the route carries. */
+        const written = async () => {
+            const after = kept((await store.get(childKey))?.state);
+            return Object.fromEntries(Object.entries(after).filter(([k, v]) => before.get(k) !== JSON.stringify(v)));
+        };
         let walked;
         try {
-            walked = await runAgent({ agent, sid: sessionId, appName: route, userParts: parts, sessions: sessionService, stage: 'dispatch', route: resolution, publishToolStatus: true, errorPolicy: 'collect' });
+            walked = await runAgent({ agent, sid: sessionId, appName: child.appName, userParts: routeAnswer ?? parts, sessions: sessionService, stage: 'dispatch', route: resolution, publishToolStatus: true, errorPolicy: 'collect' });
         }
         catch (err) {
             const last = control.stopReason ? undefined : err;
@@ -623,9 +771,22 @@ async function runTurnInner(opts, control, _runtime) {
             result.error = { code: last instanceof UnsupportedWorkflowResumeError ? 'RESUME_UNSUPPORTED' : last instanceof NodeRunLimitError ? NODE_RUN_LIMIT : 'NODE_FAILED', message: last.message };
             return { failed: finish() };
         }
+        if (!walked.error && !control.stopReason) {
+            // A walk that ended paused (ADR 0119): the conversation stores the route's pause record, which names the walk's
+            // open interrupts and carries its state writes so far; the next message finds the walk through it.
+            const walkEnd = (await store.get(childKey))?.events.at(-1);
+            const paused = walkEnd?.author === route && walkEnd.nodeInfo?.path === route && !walkEnd.content?.parts?.length ? await nestedWorkflowPause(pauseKey, route, 'route') : undefined;
+            if (paused) {
+                const record = workflowPauseEvent({ name: route, invocationId, input: null, interruptIds: [...(walkEnd.longRunningToolIds ?? [])] });
+                const stateDelta = await written();
+                if (Object.keys(stateDelta).length)
+                    record.actions.stateDelta = stateDelta;
+                await store.append((await store.get(key)) ?? shared, record);
+                return { answer: walked, paused };
+            }
+        }
         if (walked.text && !walked.error && !control.stopReason) {
-            const after = kept((await store.get(childKey))?.state);
-            const stateDelta = Object.fromEntries(Object.entries(after).filter(([k, v]) => before.get(k) !== JSON.stringify(v)));
+            const stateDelta = await written();
             const answered = createTurnEvent({
                 invocationId,
                 author: route,
@@ -636,6 +797,77 @@ async function runTurnInner(opts, control, _runtime) {
         }
         return { answer: walked };
     };
+    /**
+     * A dispatch route that is a nested dispatch syndicate (ADR 0120): its own
+     * turn (runNestedDispatch: its classifier picks one of its routes, the
+     * route answers), on the child session filed under the route's kind
+     * (`<app>/route:<route>`, entrySession), created from the conversation's
+     * state the first time, `temp:` keys dropped, and kept. The conversation
+     * stores the message and, as for a workflow route, one event authored by
+     * the route: its answer (the inner route's final text) with the state
+     * writes, or, when its turn ends paused, the route's pause record naming
+     * the one request it waits on. The turn reports that request with the
+     * path from the route down (routePause, which follows the record into the
+     * nested conversation), and the next message that answers it resumes the
+     * route without classifying: the nested turn reads it as a message at the
+     * top reads an answer (an approval decision as it came, a question's
+     * answer as the person's text, any message once a grant is stored).
+     */
+    const runDispatchRoute = async (route, dispatch) => {
+        const store = sessionService;
+        const key = { appName, userId, sessionId };
+        const shared = await store.get(key);
+        if (!shared)
+            throw new Error(`Session not found: ${sessionId} (appName=${appName}, userId=${userId})`);
+        const kept = (state) => Object.fromEntries(Object.entries(state ?? {}).filter(([k]) => !k.startsWith(TEMP_STATE_PREFIX)));
+        const resumingTurn = resumingRoute !== undefined || routeAnswer !== undefined || consentRoute !== undefined;
+        const child = await entrySession(store, { appName, userId, sessionId, events: shared.events }, route, 'route', kept(shared.state), resumingTurn);
+        const invocationId = `e-${randomUUID()}`;
+        await store.append(shared, createTurnEvent({ invocationId, author: 'user', content: { role: 'user', parts } }));
+        // A question's answer goes in as the person's words; anything else as it came.
+        const nestedParts = routeAnswer ? [{ text: messageText }] : parts;
+        const end = await runNestedDispatch(opts, control, _runtime, {
+            config: dispatch.config,
+            compile: dispatch.compile,
+            name: route,
+            sessions: store,
+            appName: child.appName,
+            userId,
+            sessionId,
+            parts: nestedParts,
+        });
+        if (control.stopReason)
+            return { failed: finish() };
+        if (end.status === 'failed') {
+            result.status = 'failed';
+            result.failedStage = 'dispatch';
+            result.error = end.error ?? { code: 'ROUTE_FAILED', message: `${route} failed.` };
+            return { failed: finish() };
+        }
+        const delta = Object.keys(end.stateDelta).length ? { actions: { stateDelta: end.stateDelta } } : {};
+        const answer = emptyRun();
+        answer.agents.add(route);
+        if (end.status === 'input-required' && end.interruptId) {
+            const record = workflowPauseEvent({ name: route, invocationId, input: null, interruptIds: [end.interruptId] });
+            if (delta.actions)
+                record.actions.stateDelta = delta.actions.stateDelta;
+            await store.append((await store.get(key)) ?? shared, record);
+            const stored = (await store.get(key))?.events ?? [];
+            const paused = await routePause(pauseKey, stored, subagentNames);
+            if (!paused)
+                throw new Error(`${route}: its turn paused on ${end.interruptId}, which its conversation does not hold.`);
+            return { answer, paused };
+        }
+        answer.text = end.text;
+        if (end.text) {
+            await store.append((await store.get(key)) ?? shared, createTurnEvent({ invocationId, author: route, content: { role: 'model', parts: [{ text: end.text }] }, ...delta }));
+        }
+        return { answer };
+    };
+    // While a route's walk waits on a gated call (ADR 0119), a message that is not its decision repeats the request: the
+    // walk cannot move past the waiting node, so nothing is stored and nothing runs, as a workflow turn answers it.
+    if (!decision && routePaused?.approval)
+        return pause(routePaused.approval);
     let answer;
     if (isDispatchSyndicate(config)) {
         // ══ PLAN ═════════════════════════════════════════════════════════════
@@ -651,7 +883,7 @@ async function runTurnInner(opts, control, _runtime) {
                 throw new Error(`Call ${resumeTarget.id} was raised by '${resumeTarget.agent}', which is not a route of this syndicate.`);
             }
             resolution = { route: resumeTarget.agent, reason: resumeTarget.why, fellBack: false, fallbackReason: '', viaOverride: false };
-            decidedBy = resuming ? 'approval' : granting ? 'consent' : 'answer';
+            decidedBy = resuming ? 'approval' : granting || consentRoute ? 'consent' : 'answer';
         }
         else if (resolution) {
             ev.log?.(`⇄ Route pinned by override: ${resolution.route}`);
@@ -703,7 +935,8 @@ async function runTurnInner(opts, control, _runtime) {
             throw new Error(`Dispatch failed: no subagent named '${resolution.route}' is declared.`);
         result.route = { ...resolution, decidedBy };
         const routeNote = resolution.reason ? ` — ${resolution.reason}` : '';
-        ev.log?.(`⇄ Route: ${resolution.route}${routeNote}`);
+        // The classifier's reason can paraphrase the person: progress (to the caller) carries it, the log does not.
+        ev.log?.(`⇄ Route: ${resolution.route}`);
         ev.onProgress?.(`Routed to ${resolution.route}${routeNote}`);
         // ══ DISPATCH ═════════════════════════════════════════════════════════
         if (routeCfg.a2a_agent_url) {
@@ -716,12 +949,29 @@ async function runTurnInner(opts, control, _runtime) {
             // projection: other agents' turns would otherwise read as user speech
             // mixed with their tool payloads (lib/session/transcript.ts).
             const routeAgent = await compileRoute(routeCfg);
-            if (routeAgent.workflow) {
+            if ('dispatch' in routeAgent) {
+                // A nested dispatch syndicate runs as its own turn on its own conversation (ADR 0120).
+                const ran = await runDispatchRoute(routeCfg.name, routeAgent.dispatch);
+                if ('failed' in ran)
+                    return ran.failed;
+                answer = ran.answer;
+                // Its turn paused: the turn waits on what it waits on, with the path from the route down.
+                if (ran.paused) {
+                    result.answer = answer;
+                    return pausedWalk(ran.paused);
+                }
+            }
+            else if (routeAgent.workflow) {
                 // A workflow route walks its whole graph on its own child session (ADR 0106).
                 const walked = await runWorkflowRoute(routeCfg.name, routeAgent, resolution);
                 if ('failed' in walked)
                     return walked.failed;
                 answer = walked.answer;
+                // Its walk paused (ADR 0119): the turn waits on the node that asked, with the path from the route down to it.
+                if (walked.paused) {
+                    result.answer = answer;
+                    return pausedWalk(walked.paused);
+                }
             }
             else
                 answer = await runAgent({
@@ -732,13 +982,15 @@ async function runTurnInner(opts, control, _runtime) {
                     // is replayed raw, so the loop finds the call the message answers.
                     sessions: new ProjectedSessionService(sessionService, routeCfg.name, resumingBelow
                         ? { rawFrom: (events) => turnStartOfCall(events, resumingBelow.callIds[0]) }
-                        : resuming
-                            ? { rawFrom: (events) => interruptedTurnStart(events, resuming.id) }
-                            : answering
-                                ? { rawFrom: (events) => turnStartOfCall(events, answering.id) }
-                                : granting
-                                    ? { rawFrom: (events) => turnStartOfCall(events, granting.id) }
-                                    : {}),
+                        : grantingBelow
+                            ? { rawFrom: (events) => turnStartOfCall(events, grantingBelow.callIds[0]) }
+                            : resuming
+                                ? { rawFrom: (events) => interruptedTurnStart(events, resuming.id) }
+                                : answering
+                                    ? { rawFrom: (events) => turnStartOfCall(events, answering.id) }
+                                    : granting
+                                        ? { rawFrom: (events) => turnStartOfCall(events, granting.id) }
+                                        : {}),
                     stage: 'dispatch',
                     route: resolution,
                     publishToolStatus: true,
@@ -788,10 +1040,11 @@ async function runTurnInner(opts, control, _runtime) {
         // resumes the graph where it waited.
         // While a gated call waits, a message that is not its decision repeats the request: the walk cannot move past
         // the waiting node, so nothing is stored and nothing runs, as the A2A server answers it (ADR 0098).
-        if (!decision && declaresApprovals(config)) {
+        // A node that is a nested workflow raised its walk's request again on the walk's own session (ADR 0119), wherever the gate is declared.
+        if (!decision) {
             const open = pendingApproval(existing?.events ?? []);
             if (open)
-                return pause(open);
+                return pause(await deepen(open));
         }
         const workflowAgent = await compileNativeWorkflowAgent(config, compileOpts);
         try {
@@ -828,21 +1081,14 @@ async function runTurnInner(opts, control, _runtime) {
             result.error = answer.error;
             return finish();
         }
-        // A gated call paused its node, and the walk with it (ADR 0098): the next message answers it.
-        if (declaresApprovals(config)) {
-            const after = await sessionService.get({ appName, userId, sessionId });
-            const pending = pendingApproval(after?.events ?? []);
-            if (pending)
-                return pause(pending);
-        }
-        if (answer.inputRequests.length) {
-            const input = answer.inputRequests[answer.inputRequests.length - 1];
-            result.status = 'input-required';
-            result.input = input;
-            result.text = input.message;
-            ev.log?.(`⏸ Input needed: ${describeInput(input)}`);
-            return finish();
-        }
+        // A gated call paused its node, and the walk with it (ADR 0098): the next message answers it. A node that is a
+        // nested workflow pauses on its walk's request, reported with the path down to the node that asked (ADR 0119).
+        const after = await sessionService.get({ appName, userId, sessionId });
+        const pending = pendingApproval(after?.events ?? []);
+        if (pending)
+            return pause(await deepen(pending));
+        if (answer.inputRequests.length)
+            return question(await deepen(answer.inputRequests[answer.inputRequests.length - 1]));
         result.text = answer.text;
         if (!result.text) {
             const failed = answer.nodeErrors[answer.nodeErrors.length - 1];
@@ -907,7 +1153,8 @@ async function runTurnInner(opts, control, _runtime) {
     // Named in the syndicate's `guards:` list (and any nested syndicate's). They
     // REWRITE rather than retry, on the answering turn's text with every tool
     // result it produced. The classifier never reaches here.
-    const guardNames = collectGuards(config, compileOpts.loadNested);
+    // A nested dispatch syndicate's guards run once, on the turn's answer at the top, which lists them (ADR 0120).
+    const guardNames = nestedTurn ? [] : collectGuards(config, compileOpts.loadNested);
     if (result.text && guardNames.length) {
         const inputs = answer.toolResultTexts;
         for (const guard of resolveGuards(guardNames, (n) => ev.warn?.(`Unknown guard '${n}' — ignored`))) {