melchizedek-agents 1.1.0 → 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';
@@ -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';
@@ -281,6 +284,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 +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
@@ -322,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:.
@@ -374,14 +424,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 +457,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 +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) ───────────────────────────────────
@@ -433,12 +522,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 +545,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)
@@ -485,6 +589,8 @@ 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;
@@ -501,6 +607,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: ${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;
@@ -541,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 } : {}),
             });
         }
@@ -588,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;
@@ -605,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;
@@ -623,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,
@@ -636,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 ═════════════════════════════════════════════════════════════
@@ -651,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}`);
@@ -716,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({
@@ -732,13 +968,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 +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 {
@@ -828,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];
@@ -907,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`))) {

package/dist/lib/runtime/turnControl.d.ts

@@ -45,6 +45,47 @@ export interface TurnControl {
     stopReason?: TurnStopReason;
     /** Stop the turn. The first reason wins. */
     stop(reason: TurnStopReason): void;
+    /**
+     * Runs a nested dispatch syndicate as its own turn on its own
+     * conversation, under this turn's controls (ADR 0120): set by the turn
+     * runner (lib/runtime/syndicateTurn.ts), read where a nested dispatch
+     * syndicate runs (a delegated call, a dispatch route, a workflow node),
+     * which sit below the turn runner and cannot import it.
+     */
+    nestedDispatch?: (run: NestedDispatchRun) => Promise<NestedDispatchEnd>;
+}
+/** One run of a nested dispatch syndicate (ADR 0120): what it is, where its conversation is filed, and the message. */
+export interface NestedDispatchRun {
+    /** The nested syndicate's config (a SyndicateYamlConfig with a `dispatch:` block). */
+    config: unknown;
+    /** The compile options it loads its routes with (CompileOptions, its nesting chain included). */
+    compile: unknown;
+    /** The entry's name: the nested syndicate as its caller lists it. */
+    name: string;
+    /** The store, and the key its conversation is filed under (already opened by the caller). */
+    sessions: unknown;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    /** The message's parts: the request, or the answer to what waits in it. */
+    parts: unknown[];
+}
+/** How a nested dispatch syndicate's turn ended (ADR 0120). */
+export interface NestedDispatchEnd {
+    status: 'completed' | 'input-required' | 'failed' | 'canceled';
+    /** The route's final text: the nested syndicate's answer. */
+    text: string;
+    /** Its conversation's state writes this run, `temp:` keys aside. */
+    stateDelta: Record<string, unknown>;
+    /** What it waits on, when paused: the request's id, and the request as the turn reports it (a PendingApproval, a PendingInput, a PendingConsent). */
+    interruptId?: string;
+    approval?: unknown;
+    input?: unknown;
+    consent?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
 }
 export interface TurnControlOptions {
     maxLlmCalls?: number;

package/dist/lib/session/transcript.d.ts

@@ -232,6 +232,15 @@ export declare class ProjectedSessionService implements SessionService {
      * The event lands in the projected session the runtime holds and, through
      * the store, in the real one `get` read. A session `get` did not hand out
      * is the real one, and the store alone applies the event to it.
+     *
+     * A store may answer an append with events of its own: a durable run's
+     * store restoring a checkpoint (lib/runtime/native/checkpoint.ts, ADR 0113)
+     * answers the opening message with the run's stored events, the stored
+     * opening returned in place of the one given. The projected session then
+     * takes, in place of the event given, every event the real session gained,
+     * unprojected: they are the current turn, which is never projected. The
+     * agent loop thereby reads the restored steps, as it would on the store's
+     * own session.
      */
     append(session: EngineSession, event: TurnEvent): Promise<TurnEvent>;
 }