melchizedek-agents 1.0.3 → 1.2.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';
@@ -63,10 +63,17 @@ import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from '../dispat
 import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from '../grounding.js';
 import { resolveGuards } from '../guards/index.js';
 import { collectGuards, nestedLoader } from '../loadSyndicate.js';
+import { context } from '@opentelemetry/api';
+import core from '@opentelemetry/core';
+const { suppressTracing } = core;
 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 { 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';
@@ -274,9 +281,17 @@ export async function runSyndicateTurn(opts) {
         maxLlmCalls: opts.maxLlmCalls ?? config.max_steps ?? DEFAULT_MAX_STEPS,
         deadlineMs: opts.deadlineMs,
         signal: opts.signal,
+        // `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 {
-        return await runWithTurnControl(control, () => runTurnInner(opts, control, runtime));
+        const run = () => runWithTurnControl(control, () => runTurnInner(opts, control, runtime));
+        // A span a library opens through OpenTelemetry's own API (not the
+        // engine's, which read control.untraced) is suppressed too, while a
+        // registered tracer is there to read the suppression.
+        return await (control.untraced ? context.with(suppressTracing(context.active()), run) : run());
     }
     finally {
         control.dispose();
@@ -297,7 +312,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
@@ -312,11 +370,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:.
@@ -360,32 +420,75 @@ async function runTurnInner(opts, control, _runtime) {
     // A message answering an approval resumes the agent that asked; the answer
     // must name the request still open in this conversation.
     const decision = approvalDecisionIn(parts);
+    // Pauses inside delegated subagents (ADR 0110): what waits below a call an agent of this conversation left open.
+    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.` };
             return finish();
         }
         // The log names the call, not its arguments: they are user content.
-        ev.log?.(`✓ Approval ${decision.approved ? 'granted' : 'refused'}: ${resuming.agent} → ${resuming.tool}`);
+        ev.log?.(`✓ Approval ${decision.approved ? 'granted' : 'refused'}: ${(resuming.path ?? [resuming.agent]).join(' → ')} → ${resuming.tool}`);
     }
     // ── Consent (lib/runtime/credentials.ts, ADR 0085) ────────────────────────
     // 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';
@@ -394,16 +497,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) ───────────────────────────────────
@@ -411,24 +519,45 @@ async function runTurnInner(opts, control, _runtime) {
     // answer: it becomes that call's response, and the agent that asked
     // resumes its own tool loop (the loop reads the response from its history;
     // ADR 0079). A workflow's pauses are its walk's own business.
+    // 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)) {
-        const question = pendingQuestion(existing?.events ?? []);
+    /** 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');
-        if (question && plainText) {
-            answering = { agent: question.node, id: question.id };
+        const own = plainText ? pendingQuestion(existing?.events ?? []) : undefined;
+        const below = plainText && !own ? await pauseBelow(existing?.events ?? []) : undefined;
+        const question = own ?? below?.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.node}'s question`);
+            ev.log?.(`✓ Answer to ${(question.path ?? [question.node]).join(' → ')}'s question`);
         }
     }
     /** The agent a dispatch turn must resume, and the call its interrupted turn holds. */
-    const resumeTarget = 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;
+    const resumeTarget = resumingBelow
+        ? { agent: resumingBelow.path[0], id: resumingBelow.callIds[0], why: 'resuming an approval' }
+        : 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)
@@ -454,13 +583,40 @@ async function runTurnInner(opts, control, _runtime) {
         ev.log?.(`⏸ Input needed: ${describeInput(input)}`);
         return finish();
     };
+    /** After the answering run: does a pause wait inside a delegated call `agentName` left open (ADR 0110)? */
+    const pausedBelow = async (agentName) => {
+        const after = await sessionService.get({ appName, userId, sessionId });
+        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(' → ')})`);
+            return finish();
+        }
+        return undefined;
+    };
     const pause = (pending) => {
         result.status = 'input-required';
         result.approval = pending;
         result.text = `Approval needed: ${describeApproval(pending)}.`;
-        ev.log?.(`⏸ Approval needed: ${pending.agent} → ${pending.tool}`);
+        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: ${describeInput(input)}${input.path ? ` (${input.path.join(' → ')})` : ''}`);
         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;
@@ -501,7 +657,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 } : {}),
             });
         }
@@ -548,15 +704,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;
@@ -565,14 +733,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;
@@ -583,9 +758,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,
@@ -596,6 +784,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 ═════════════════════════════════════════════════════════════
@@ -611,7 +870,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}`);
@@ -676,12 +935,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({
@@ -690,13 +966,17 @@ async function runTurnInner(opts, control, _runtime) {
                     userParts: parts,
                     // Resuming an approval or answering a question: the interrupted turn
                     // is replayed raw, so the loop finds the call the message answers.
-                    sessions: new ProjectedSessionService(sessionService, routeCfg.name, resuming
-                        ? { rawFrom: (events) => interruptedTurnStart(events, resuming.id) }
-                        : answering
-                            ? { rawFrom: (events) => turnStartOfCall(events, answering.id) }
-                            : granting
-                                ? { rawFrom: (events) => turnStartOfCall(events, granting.id) }
-                                : {}),
+                    sessions: new ProjectedSessionService(sessionService, routeCfg.name, resumingBelow
+                        ? { rawFrom: (events) => turnStartOfCall(events, resumingBelow.callIds[0]) }
+                        : 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,
@@ -709,11 +989,16 @@ async function runTurnInner(opts, control, _runtime) {
             result.error = answer.error;
             return finish();
         }
-        if (!routeCfg.a2a_agent_url && agentGates(routeCfg)) {
+        if (!routeCfg.a2a_agent_url && (agentGates(routeCfg) || routeCfg.yaml_reference)) {
             const pending = await awaitingApproval(routeCfg.name);
             if (pending)
                 return pause(pending);
         }
+        if (!routeCfg.a2a_agent_url) {
+            const below = await pausedBelow(routeCfg.name);
+            if (below)
+                return below;
+        }
         if (!routeCfg.a2a_agent_url) {
             const consent = await awaitingConsent(routeCfg.name);
             if (consent)
@@ -741,10 +1026,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 {
@@ -781,21 +1067,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];
@@ -835,6 +1114,11 @@ async function runTurnInner(opts, control, _runtime) {
         const consent = await awaitingConsent(config.orchestrator.name);
         if (consent)
             return consentPause(consent);
+        if (config.subagents?.length) {
+            const below = await pausedBelow(config.orchestrator.name);
+            if (below)
+                return below;
+        }
         const askedOrchestrator = asked(answer);
         if (askedOrchestrator)
             return askedOrchestrator;
@@ -855,7 +1139,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`))) {