melchizedek-agents 1.3.1 → 1.6.0

package/dist/lib/runtime/native/delegate.js

@@ -104,6 +104,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { resolveAdapter } from '../../models/registry.js';
+import { credentialRequestCall } from '../credentials.js';
 import { createTurnEvent } from '../events.js';
 import { TEMP_STATE_PREFIX } from '../sessions.js';
 import { REQUEST_INPUT_CALL } from './history.js';
@@ -393,9 +394,31 @@ export function runSubagent(agent, args, context, scope) {
 export function resumeSubagent(agent, answer, context, scope) {
     return runChild(agent, { role: 'user', parts: answer }, context, scope, true);
 }
+/**
+ * Where a delegated call's run sits (ADR 0135): the path below the caller's,
+ * `name` last, and the call's id. A top-level caller's path is its name.
+ */
+function branchOf(name, context, scope) {
+    const path = [...(scope.ctx.agentPath ?? [scope.caller]), name];
+    return { agent: name, path, ...(context.functionCallId ? { callId: context.functionCallId } : {}) };
+}
+/** Hands one event to the turn's observer (ADR 0135). An observer that throws never breaks the run. */
+function observe(sink, event, branch) {
+    if (!sink)
+        return;
+    try {
+        sink(event, branch);
+    }
+    catch {
+        /* the observer is the caller's; the turn goes on */
+    }
+}
 async function runChild(agent, content, context, scope, resuming) {
     const { ctx, signal } = scope;
     const { sessions } = ctx;
+    // With an observer the child streams, so its thinking and text reach it as partials (ADR 0135); partials are stored nowhere.
+    const sink = currentTurnControl()?.agentEvents;
+    const branch = branchOf(agent.name, context, scope);
     const session = await childSession(agent.name, context, scope, resuming);
     if (signal?.aborted)
         return '';
@@ -408,9 +431,10 @@ async function runChild(agent, content, context, scope, resuming) {
         sessions,
         invocationId,
         userContent: content,
-        stream: false,
+        stream: sink !== undefined,
         // Its own delegations are filed below its path (childAppName, ADR 0111).
         delegated: true,
+        agentPath: branch.path,
         // ADK's AgentTool builds its sub-runner without the reflect-and-retry
         // plugins, so a subagent's own errors are not retried (ADR 0075).
         selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
@@ -437,6 +461,9 @@ async function runChild(agent, content, context, scope, resuming) {
             await loop.return(undefined);
             break;
         }
+        observe(sink, next.value, branch);
+        if (next.value.partial)
+            continue;
         recordState(next.value, context);
         last = next.value;
     }
@@ -468,6 +495,8 @@ export function resumeWorkflowSubagent(workflow, answer, context, scope) {
 }
 async function walkChild(workflow, userParts, context, scope, resuming) {
     const { ctx, signal } = scope;
+    const sink = currentTurnControl()?.agentEvents;
+    const branch = branchOf(workflow.name, context, scope);
     const session = await childSession(workflow.name, context, scope, resuming);
     if (signal?.aborted)
         return '';
@@ -484,6 +513,8 @@ async function walkChild(workflow, userParts, context, scope, resuming) {
         ...(ctx.memory ? { memory: ctx.memory } : {}),
         ...(ctx.log ? { log: ctx.log } : {}),
         ...(ctx.credentials ? { credentials: ctx.credentials } : {}),
+        // A node that needs a grant pauses the walk, and the pause reaches the turn through the open call (ADR 0128).
+        ...(ctx.consent ? { consent: consentPinnedTo(ctx.consent, ctx.session.appName) } : {}),
     });
     let last;
     for (;;) {
@@ -500,6 +531,7 @@ async function walkChild(workflow, userParts, context, scope, resuming) {
             break;
         }
         const event = next.value;
+        observe(sink, event, branch);
         if (event.partial)
             continue;
         recordState(event, context);
@@ -528,8 +560,9 @@ function dispatchParts(parts) {
 /**
  * The request call a paused nested dispatch syndicate's turn waits on, as a
  * workflow node raises it again on its caller's walk: an approval request
- * pinned to the gated call, or an input request carrying the question.
- * Undefined for a consent request, which a walk cannot raise (ADR 0119).
+ * pinned to the gated call, an input request carrying the question, or a
+ * credential request rebuilt from the consent request (credentialRequestCall,
+ * ADR 0128), under the nested request's id.
  */
 function requestCallOf(end) {
     const id = end.interruptId;
@@ -556,6 +589,9 @@ function requestCallOf(end) {
             },
         };
     }
+    const consent = end.consent;
+    if (consent && consent.id === id)
+        return credentialRequestCall(consent);
     return undefined;
 }
 /**

package/dist/lib/runtime/native/interrupts.d.ts

@@ -58,7 +58,9 @@
  * grantedCalls is that preprocessor, check for check, with one difference
  * in what the answer carries:
  *   1. The answers: the function responses named `adk_request_credential`
- *      in the last event with content, which must be the user's. None:
+ *      in the latest user event, provided this agent has stored nothing
+ *      with content since (at the top that is the last event with content;
+ *      in a walk another node's events may come between, ADR 0128). None:
  *      nothing happens.
  *   2. The requests they answer: `adk_request_credential` calls this agent
  *      made, by id. An answer naming no such request is ignored, as ADK
@@ -102,7 +104,8 @@
  * workflow under the call's name) makes an approval request an agent node
  * raised, or an ask_user node's question, the pause, with the node that
  * asked at the end of the path. The walk stops there: a pause inside a
- * workflow node's own delegation does not run (lib/workflow/agentNode.ts).
+ * workflow node's own delegation does not run (lib/workflow/agentNode.ts),
+ * except an OAuth consent request, which does (ADR 0128, below).
  *
  * NESTED WORKFLOWS AS A ROUTE OR A NODE (ADR 0119). A workflow node that is
  * a nested workflow raises its walk's open requests again on its caller's
@@ -126,6 +129,19 @@
  * call, the route's pause record or the node's raised request, and the
  * nested turn reads it as a message at the top.
  *
+ * CONSENT INSIDE A WALK (ADR 0128). An agent node's own consent request
+ * is an interrupt of the walk like its approval request: the walk's pause
+ * record names it, and walkConsents finds it there for the turn. A node
+ * whose request waits below it (in a call its agent left open, in a nested
+ * walk, in a nested dispatch syndicate's conversation) raises a copy of it
+ * on the walk under the same id (lib/workflow/agentNode.ts,
+ * lib/workflow/turn.ts), and consentBelow follows the copy down to the
+ * agent that asked; workflowPause reads a credential request as it reads
+ * an approval or a question, so a walk nested below a route, a node or a
+ * delegated call is followed the same way. grantedCalls reads the latest
+ * user event unless the agent has written since, so another node's events
+ * between the grant's answer and the node's resume do not hide it.
+ *
  * CONSENT AND SKILL SCRIPTS INSIDE DELEGATED SUBAGENTS (ADR 0118). A skill
  * script run asks for approval through the same `adk_request_confirmation`
  * call a gated tool stores, so the walk and the resume above carry it with
@@ -230,6 +246,20 @@ export declare function openCalls(events: readonly TurnEvent[], author?: string)
     author: string;
     call: TurnFunctionCall;
 }>;
+/**
+ * The OAuth consent requests a walk waits on (ADR 0128): the credential
+ * requests among the open interrupts its pause record names (the session's
+ * last event, authored by the workflow at its own path, no content), each
+ * followed down to the agent that asked. A node's own request comes back as
+ * it is, `agent` the node and no `path`, as a node's own approval request
+ * does; one a node raised again on the walk (a delegated subagent's, a
+ * nested walk's, a nested dispatch syndicate's) carries the `path` from the
+ * node down. `key.appName` is the walk session's app. Empty when the walk is
+ * not paused, or waits on no grant.
+ */
+export declare function walkConsents(key: DelegationKey & {
+    appName: string;
+}, events: readonly TurnEvent[], depth?: number): Promise<PendingConsent[]>;
 /** A pause a nested workflow's walk holds: the path from the workflow down to the node that asked, and what it asks. */
 export interface NestedWorkflowPause {
     /** From the workflow (the route, the node, the subagent) down to the node that asked: `[workflow, …, node]`. */
@@ -238,7 +268,7 @@ export interface NestedWorkflowPause {
     approval?: PendingApproval;
     /** The question, its `node` the node that asked and its `path` set. */
     question?: PendingInput;
-    /** The OAuth consent request, inside a nested dispatch syndicate's route (ADR 0120); its `path` set. */
+    /** The OAuth consent request, inside a nested dispatch syndicate's route (ADR 0120) or a node of the walk (ADR 0128); its `path` set. */
     consent?: PendingConsent;
 }
 /**

package/dist/lib/runtime/native/interrupts.js

@@ -58,7 +58,9 @@
  * grantedCalls is that preprocessor, check for check, with one difference
  * in what the answer carries:
  *   1. The answers: the function responses named `adk_request_credential`
- *      in the last event with content, which must be the user's. None:
+ *      in the latest user event, provided this agent has stored nothing
+ *      with content since (at the top that is the last event with content;
+ *      in a walk another node's events may come between, ADR 0128). None:
  *      nothing happens.
  *   2. The requests they answer: `adk_request_credential` calls this agent
  *      made, by id. An answer naming no such request is ignored, as ADK
@@ -102,7 +104,8 @@
  * workflow under the call's name) makes an approval request an agent node
  * raised, or an ask_user node's question, the pause, with the node that
  * asked at the end of the path. The walk stops there: a pause inside a
- * workflow node's own delegation does not run (lib/workflow/agentNode.ts).
+ * workflow node's own delegation does not run (lib/workflow/agentNode.ts),
+ * except an OAuth consent request, which does (ADR 0128, below).
  *
  * NESTED WORKFLOWS AS A ROUTE OR A NODE (ADR 0119). A workflow node that is
  * a nested workflow raises its walk's open requests again on its caller's
@@ -126,6 +129,19 @@
  * call, the route's pause record or the node's raised request, and the
  * nested turn reads it as a message at the top.
  *
+ * CONSENT INSIDE A WALK (ADR 0128). An agent node's own consent request
+ * is an interrupt of the walk like its approval request: the walk's pause
+ * record names it, and walkConsents finds it there for the turn. A node
+ * whose request waits below it (in a call its agent left open, in a nested
+ * walk, in a nested dispatch syndicate's conversation) raises a copy of it
+ * on the walk under the same id (lib/workflow/agentNode.ts,
+ * lib/workflow/turn.ts), and consentBelow follows the copy down to the
+ * agent that asked; workflowPause reads a credential request as it reads
+ * an approval or a question, so a walk nested below a route, a node or a
+ * delegated call is followed the same way. grantedCalls reads the latest
+ * user event unless the agent has written since, so another node's events
+ * between the grant's answer and the node's resume do not hide it.
+ *
  * CONSENT AND SKILL SCRIPTS INSIDE DELEGATED SUBAGENTS (ADR 0118). A skill
  * script run asks for approval through the same `adk_request_confirmation`
  * call a gated tool stores, so the walk and the resume above carry it with
@@ -144,7 +160,7 @@ import { nativeToolOf } from '../../models/schemaNormalize.js';
 import { instructionToolOf, isTool, toolOf } from '../../tools/tool.js';
 import { inputRequestFrom } from '../../workflowConfig.js';
 import { approvalRequestOf, pendingApproval } from '../approvals.js';
-import { pendingConsent } from '../credentials.js';
+import { consentFrom, pendingConsent } from '../credentials.js';
 import { getFunctionCalls, getFunctionResponses } from '../events.js';
 import { ASK_USER, pendingQuestion } from '../questions.js';
 import { childAppName, entryAppName, legacyChild, legacyEntry } from './delegate.js';
@@ -308,11 +324,17 @@ export async function grantedCalls(agent, scope) {
     const events = scope.session.events;
     if (events.length === 0)
         return undefined;
+    // The latest user event, unless this agent has written since (ADR 0128): in a walk, another node's events may
+    // follow the person's answer before this node reads it; at the top only this agent writes after the message.
     let last;
-    for (let i = events.length - 1; i >= 0 && !last; i--)
-        if (events[i]?.content !== undefined)
-            last = events[i];
-    if (!last || last.author !== 'user')
+    for (let i = events.length - 1; i >= 0 && !last; i--) {
+        const event = events[i];
+        if (event.author === agent.name && event.content !== undefined)
+            return undefined;
+        if (event.author === 'user' && event.content !== undefined)
+            last = event;
+    }
+    if (!last)
         return undefined;
     const answers = new Map();
     for (const r of getFunctionResponses(last))
@@ -427,6 +449,7 @@ async function pauseBelow(key, caller, call, depth, seen) {
             callIds: [id],
             ...(walked.approval ? { approval: { ...walked.approval, path } } : {}),
             ...(walked.question ? { question: { ...walked.question, path } } : {}),
+            ...(walked.consent ? { consent: { ...walked.consent, path } } : {}),
         };
     }
     const approval = pendingApproval(child.events);
@@ -540,8 +563,9 @@ function workflowPause(events, name, id) {
     const open = new Set((record.longRunningToolIds ?? []).filter((x) => id === undefined || x === id));
     if (open.size === 0)
         return undefined;
-    // The latest open request the record names, an approval first: the walk stores node inputs as user turns, so a later one may follow it.
-    for (const kind of [REQUEST_CONFIRMATION_CALL, REQUEST_INPUT_CALL]) {
+    // The latest open request the record names, an approval first, then a question, then a consent request (ADR 0128):
+    // the walk stores node inputs as user turns, so a later one may follow it.
+    for (const kind of [REQUEST_CONFIRMATION_CALL, REQUEST_INPUT_CALL, REQUEST_CREDENTIAL_CALL]) {
         for (let i = events.length - 2; i >= 0; i--) {
             const event = events[i];
             if (!event.author || event.author === 'user')
@@ -551,6 +575,12 @@ function workflowPause(events, name, id) {
                     continue;
                 if (kind === REQUEST_CONFIRMATION_CALL)
                     return { asker: event.author, approval: approvalRequestOf(event, call) };
+                if (kind === REQUEST_CREDENTIAL_CALL) {
+                    const consent = consentFrom(event.author, call);
+                    if (consent)
+                        return { asker: event.author, consent };
+                    continue;
+                }
                 const question = inputRequestFrom(event.author, call);
                 if (question && question.id === call.id)
                     return { asker: event.author, question };
@@ -559,6 +589,58 @@ function workflowPause(events, name, id) {
     }
     return undefined;
 }
+/** Whether `asker` made the call `functionCallId` itself in `events`: its consent request is its own, not one it raised again. */
+function madeCall(events, asker, functionCallId) {
+    return events.some((event) => event.author === asker && getFunctionCalls(event).some((call) => call.id === functionCallId && call.name !== REQUEST_CREDENTIAL_CALL));
+}
+/**
+ * The consent request `id` waiting below the node `asker` of a walk whose
+ * session holds `events` (filed under `key.appName`), when the node raised
+ * it again on the walk (ADR 0128): inside the node's own child session (a
+ * nested workflow, or a nested dispatch syndicate's conversation,
+ * nestedWorkflowPause), else inside a call the node left open (a delegated
+ * subagent, delegatedPauses). Its `path` runs from `asker` down to the
+ * agent that asked. Undefined when nothing below holds it.
+ */
+async function consentBelow(key, events, asker, id, depth) {
+    if (depth >= MAX_DELEGATION_DEPTH)
+        return undefined;
+    const nested = await nestedWorkflowPause(key, asker, 'node', id, depth + 1);
+    if (nested?.consent?.id === id)
+        return nested.consent;
+    const below = await delegatedPauses({ ...key, delegated: false }, events, asker, depth + 1);
+    return below.find((pause) => pause.consent?.id === id)?.consent;
+}
+/**
+ * The OAuth consent requests a walk waits on (ADR 0128): the credential
+ * requests among the open interrupts its pause record names (the session's
+ * last event, authored by the workflow at its own path, no content), each
+ * followed down to the agent that asked. A node's own request comes back as
+ * it is, `agent` the node and no `path`, as a node's own approval request
+ * does; one a node raised again on the walk (a delegated subagent's, a
+ * nested walk's, a nested dispatch syndicate's) carries the `path` from the
+ * node down. `key.appName` is the walk session's app. Empty when the walk is
+ * not paused, or waits on no grant.
+ */
+export async function walkConsents(key, events, depth = 0) {
+    const record = events[events.length - 1];
+    const name = record?.author;
+    if (!record || !name || name === 'user' || (record.content?.parts ?? []).length > 0 || record.nodeInfo?.path !== name)
+        return [];
+    const out = [];
+    for (const id of record.longRunningToolIds ?? []) {
+        const walked = workflowPause(events, name, id);
+        const consent = walked?.consent;
+        if (!walked || !consent)
+            continue;
+        if (madeCall(events, walked.asker, consent.functionCallId)) {
+            out.push(consent);
+            continue;
+        }
+        out.push((await consentBelow(key, events, walked.asker, id, depth)) ?? consent);
+    }
+    return out;
+}
 /**
  * The pause the walk of `name` holds in `child` (its child session), with
  * `id` the only interrupt that counts when given: the node that asked, or,
@@ -569,6 +651,14 @@ async function workflowPauseIn(key, child, name, id, depth = 0) {
     const walked = workflowPause(child.events, name, id);
     if (!walked)
         return undefined;
+    if (walked.consent) {
+        // A node's own consent request, else one it raised again: followed down to the agent that asked (ADR 0128).
+        const below = madeCall(child.events, walked.asker, walked.consent.functionCallId)
+            ? undefined
+            : await consentBelow({ ...key, appName: child.appName }, child.events, walked.asker, walked.consent.id, depth + 1);
+        const path = [name, ...(below?.path ?? [walked.asker])];
+        return { path, consent: { ...(below ?? walked.consent), path } };
+    }
     const found = (walked.approval?.id ?? walked.question?.id);
     const deeper = await nestedWorkflowPause({ ...key, appName: child.appName }, walked.asker, 'node', found, depth + 1);
     const path = deeper ? [name, ...deeper.path] : [name, walked.asker];

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

@@ -64,7 +64,8 @@ export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.ts';
 import type { PendingApproval } from './approvals.ts';
 export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.ts';
 export type { PendingApproval } from './approvals.ts';
-import type { TurnStopReason } from './turnControl.ts';
+import type { AgentBranch, TurnStopReason } from './turnControl.ts';
+export type { AgentBranch } from './turnControl.ts';
 /** One part of the user's message. Text is the common case; the genai part
  *  shapes (inlineData, fileData) pass through to the model unchanged. */
 export type MessagePart = {
@@ -86,6 +87,18 @@ export interface TurnEvents {
     onTextDelta?(delta: string): void;
     /** The text streamed so far was narration before a tool call: discard it. */
     onTextReset?(): void;
+    /**
+     * Every event of a delegated run, live, with where it runs (ADR 0135): a
+     * subagent's thinking and text as partial events, then each event it
+     * stores (its tool calls, their results, its answer), and a nested
+     * workflow's events; at any depth, parallel calls interleaved and told
+     * apart by `branch.callId` and `branch.path`. The answering agent's
+     * events stay on onEvent and onTextDelta, which this does not change.
+     * Passing it makes each delegated run stream; what the sessions store is
+     * the same. Fires for a syndicate with guards too: a delegated run's text
+     * is never the answer a guard rewrites. An observer that throws is ignored.
+     */
+    onAgentEvent?(event: TurnEvent, branch: AgentBranch): void;
     /** Diagnostic lines (the server prefixes and prints them). */
     log?(message: string): void;
     warn?(message: string): void;

package/dist/lib/runtime/syndicateTurn.js

@@ -70,7 +70,7 @@ 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 { deepestPause, delegatedPauses, nestedWorkflowPause, routePause, walkConsents } from './native/interrupts.js';
 import { consentPinnedTo, entrySession } from './native/delegate.js';
 import { workflowPauseEvent } from '../workflow/pause.js';
 import { INPUT_REQUEST } from '../workflowConfig.js';
@@ -299,6 +299,10 @@ export async function runSyndicateTurn(opts) {
     });
     // 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);
+    // Delegated runs report to the caller as they run (ADR 0135).
+    const onAgentEvent = opts.events?.onAgentEvent;
+    if (onAgentEvent)
+        control.agentEvents = (event, branch) => onAgentEvent.call(opts.events, event, branch);
     try {
         const run = () => runWithTurnControl(control, () => runTurnInner(opts, control, runtime));
         // A span a library opens through OpenTelemetry's own API (not the
@@ -485,6 +489,15 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         ev.log?.(`⏸ Authorization needed: ${(pending.path ?? [pending.agent]).join(' → ')} → ${pending.provider}`);
         return finish();
     };
+    /** Whether the grant a consent request waits for is stored (an expired or unreadable one is not). */
+    const grantStored = async (open) => {
+        try {
+            return !!open.provider && !!(await credentialStore?.get({ appName: credentialApp, userId, provider: open.provider }));
+        }
+        catch {
+            return false;
+        }
+    };
     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;
@@ -508,14 +521,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
                 result.error = { code: 'CONSENT_UNAVAILABLE', message: `A call waits for a ${open.provider} authorization, but this turn has no credential store.` };
                 return finish();
             }
-            let granted = false;
-            try {
-                granted = !!open.provider && !!(await credentialStore.get({ appName: credentialApp, userId, provider: open.provider }));
-            }
-            catch {
-                // Expired or unreadable: not granted. The request stands.
-            }
-            if (!granted)
+            if (!(await grantStored(open)))
                 return consentPause(open);
             // The route's own turn carries the grant's answer down to its call; the message goes to it as it came.
             if (routeWaits)
@@ -527,6 +533,28 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
             ev.log?.(`✓ Authorization granted: ${(open.path ?? [open.agent]).join(' → ')} → ${open.provider}`);
         }
     }
+    // A walk waiting for grants (ADR 0128): a node's own consent request, or one a node raised again from below it. Once every
+    // grant is stored, the message becomes their answers and the walk resumes those nodes; until then it repeats the first
+    // request still missing and stores nothing, as at the top.
+    if (!decision && isWorkflowSyndicate(config)) {
+        const waiting = await walkConsents(pauseKey, existing?.events ?? []);
+        if (waiting.length > 0) {
+            if (!credentialStore) {
+                result.status = 'failed';
+                result.error = { code: 'CONSENT_UNAVAILABLE', message: `A call waits for a ${waiting[0].provider} authorization, but this turn has no credential store.` };
+                return finish();
+            }
+            for (const open of waiting)
+                if (!(await grantStored(open)))
+                    return consentPause(open);
+            granting = waiting[0];
+            parts = waiting.map((open) => credentialResponsePart(open.id, open.provider));
+            for (const open of waiting)
+                ev.log?.(`✓ Authorization granted: ${(open.path ?? [open.agent]).join(' → ')} → ${open.provider}`);
+        }
+    }
+    /** The parts a paused workflow route's walk resumes on once its grant is stored (ADR 0128): the grant's answer to its credential request. */
+    const routeGrant = consentRoute?.consent ? [credentialResponsePart(consentRoute.consent.id, consentRoute.consent.provider)] : undefined;
     // ── Questions (lib/runtime/questions.ts) ───────────────────────────────────
     // While an agent's `ask_user` call is open, a plain-text message is its
     // answer: it becomes that call's response, and the agent that asked
@@ -651,6 +679,8 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
                 memory: nativeMemory(opts.memoryService),
                 ...(selfCorrection ? { selfCorrection } : {}),
                 ...(credentialStore ? { credentials: credentialStore } : {}),
+                // The consent step, its flows bound to the app the grants are read under, wherever the walk's session is filed (ADR 0128).
+                ...(consentStep ? { consent: consentPinnedTo(consentStep, credentialApp) } : {}),
                 ...(compileOpts.log ? { log: compileOpts.log } : {}),
             });
         }
@@ -747,7 +777,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
             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)));
         // 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 resumingWalk = resumingRoute !== undefined || routeAnswer !== undefined || consentRoute !== 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)]));
@@ -760,7 +790,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         };
         let walked;
         try {
-            walked = await runAgent({ agent, sid: sessionId, appName: child.appName, userParts: routeAnswer ?? parts, sessions: sessionService, stage: 'dispatch', route: resolution, publishToolStatus: true, errorPolicy: 'collect' });
+            walked = await runAgent({ agent, sid: sessionId, appName: child.appName, userParts: routeAnswer ?? routeGrant ?? parts, sessions: sessionService, stage: 'dispatch', route: resolution, publishToolStatus: true, errorPolicy: 'collect' });
         }
         catch (err) {
             const last = control.stopReason ? undefined : err;
@@ -1087,6 +1117,10 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         const pending = pendingApproval(after?.events ?? []);
         if (pending)
             return pause(await deepen(pending));
+        // A node waiting for a grant (ADR 0128): its own request, or one from below it, with the path from the node down.
+        const [consent] = await walkConsents(pauseKey, after?.events ?? []);
+        if (consent)
+            return consentPause(consent);
         if (answer.inputRequests.length)
             return question(await deepen(answer.inputRequests[answer.inputRequests.length - 1]));
         result.text = answer.text;

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

@@ -22,6 +22,7 @@
  *   to their provider SDK and a cancel or a deadline stops the HTTP call in
  *   flight, not just the loop around it.
  */
+import type { TurnEvent } from './events.ts';
 /** Why a turn was stopped before it finished on its own. */
 export type TurnStopReason = 'canceled' | 'deadline' | 'step_limit';
 export interface TurnControl {
@@ -53,6 +54,32 @@ export interface TurnControl {
      * which sit below the turn runner and cannot import it.
      */
     nestedDispatch?: (run: NestedDispatchRun) => Promise<NestedDispatchEnd>;
+    /**
+     * Receives every event a delegated run yields, as it yields it, with
+     * where that run sits (ADR 0135): set by the turn runner when the caller
+     * passed `events.onAgentEvent`, read where a delegated call runs
+     * (lib/runtime/native/delegate.ts), which sits below the turn runner.
+     * Its presence also makes each delegated run stream, so its thinking and
+     * text arrive as partial events.
+     */
+    agentEvents?: (event: TurnEvent, branch: AgentBranch) => void;
+}
+/**
+ * Where a delegated run sits in the turn (ADR 0135): the agent, the
+ * delegation path from the agent that took the call down to it, and the id
+ * of the call that started it.
+ */
+export interface AgentBranch {
+    /** The delegated agent: a subagent, or a nested workflow's name for an event its walk yielded. */
+    agent: string;
+    /**
+     * The agents from the caller at the top of the delegation down to this
+     * one, itself last: `['Boss', 'Researcher']`, `['Boss', 'Researcher',
+     * 'Fetcher']`. Below a nested workflow it starts again at the node's agent.
+     */
+    path: readonly string[];
+    /** The id of the function call, in the caller's event, that started this run: what pairs it with the caller's tool call. */
+    callId?: string;
 }
 /** One run of a nested dispatch syndicate (ADR 0120): what it is, where its conversation is filed, and the message. */
 export interface NestedDispatchRun {

package/dist/lib/storage/postgres/index.d.ts

@@ -19,6 +19,7 @@ import { PostgresSessionService } from './sessionService.ts';
 import { PostgresTaskStore } from './taskStore.ts';
 import type { CredentialStoreOptions } from '../../tools/credentialStore.ts';
 import type { CredentialStore } from '../../tools/auth.ts';
+import type { PayloadPolicy } from '../../observability/supabaseSpanExporter.ts';
 import type { AuditSink } from '../../observability/audit.ts';
 import type { RlsHardeningStatus } from '../rlsStatus.ts';
 import type { TaskBackend, TaskBackendOptions } from '../../tools/taskTools.ts';
@@ -28,6 +29,8 @@ export { PostgresSessionService } from './sessionService.ts';
 export { PostgresTaskStore } from './taskStore.ts';
 export { postgresMemoryStore } from './memoryStore.ts';
 export { postgresCredentialRows, postgresCredentialStore } from './credentialStore.ts';
+export { inProcessTurnLock } from '../../a2a/turnLock.ts';
+export type { TurnLock } from '../../a2a/turnLock.ts';
 export interface PostgresStorageOptions {
     /** A Postgres URL. Ignored when `pool` is given. */
     connectionString?: string;
@@ -54,6 +57,28 @@ export interface PostgresStorageOptions {
     };
     /** Owner of an A2A call, for the task store. Default: the SDK's user scope. */
     taskOwner?: PostgresTaskStoreOptions['ownerResolver'];
+    /**
+     * The turn lock to use instead of the advisory lock below. The advisory
+     * lock is what makes several instances on one database take turns; it
+     * needs a database that gives each connection its own session. Embedded
+     * Postgres (PGlite behind pglite-socket) runs every connection in ONE
+     * session, where an advisory lock is re-entrant and so excludes nothing:
+     * there, one process owns the database, and `inProcessTurnLock()`
+     * (exported here) is the correct lock. When given, no turn-lock
+     * pool is opened.
+     */
+    turnLock?: TurnLock;
+    /**
+     * Write the telemetry ledger (adk_turns, adk_telemetry, adk_payloads) to
+     * this database (ADR 0131): the rows the Supabase sink writes, with the
+     * same payload policy (TELEMETRY_PAYLOADS, or `policy`) and redaction.
+     * Needs db/telemetry.sql applied. `close()` flushes and detaches it.
+     * Default off.
+     */
+    ledger?: boolean | {
+        policy?: PayloadPolicy;
+        deadLetterFile?: string;
+    };
     /**
      * Connections reserved for turn locks: each running turn holds one for its
      * length, apart from the main pool so a long turn never starves queries.

package/dist/lib/storage/postgres/index.js

@@ -22,12 +22,16 @@ import { postgresCredentialStore } from './credentialStore.js';
 import { searchPathOption } from '../schema.js';
 import { POSTGRES_RLS_QUERY, evaluatePostgresRls } from '../rlsStatus.js';
 import { postgresAuditSink } from '../../observability/audit.js';
+import { attachLedger } from '../../observability/tracer.js';
+import { postgresLedgerClient } from '../../observability/supabaseSpanExporter.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 export { PostgresSessionService } from './sessionService.js';
 export { PostgresTaskStore } from './taskStore.js';
 export { postgresMemoryStore } from './memoryStore.js';
 export { postgresCredentialRows, postgresCredentialStore } from './credentialStore.js';
+// The single-process turn lock, for an embedded database (`turnLock` below).
+export { inProcessTurnLock } from '../../a2a/turnLock.js';
 /**
  * A pool emits 'error' when an idle connection dies (a database restart, a
  * failover, an administrator's terminate); unhandled, that event crashes the
@@ -69,7 +73,7 @@ export function postgresStorage(options) {
         ...(options.pool ? options.pool.options : { connectionString: options.connectionString, ...options.poolConfig }),
         max: options.lockPoolMax ?? 20,
     }), 'turn-lock pool'));
-    const turnLock = async (key, { waitMs, signal }) => {
+    const advisoryTurnLock = async (key, { waitMs, signal }) => {
         const lockId = advisoryLockId(key);
         const client = await locks().connect();
         const deadline = Date.now() + Math.max(0, waitMs);
@@ -105,6 +109,10 @@ export function postgresStorage(options) {
         };
         return release;
     };
+    const turnLock = options.turnLock ?? advisoryTurnLock;
+    const detachLedger = options.ledger
+        ? attachLedger(postgresLedgerClient(pool), options.ledger === true ? {} : options.ledger)
+        : undefined;
     const audit = postgresAuditSink(pool);
     const credentials = options.credentials ? postgresCredentialStore(pool, { ...options.credentials, audit }) : undefined;
     return {
@@ -160,6 +168,7 @@ export function postgresStorage(options) {
             return counts;
         },
         async close() {
+            await detachLedger?.();
             if (lockPool)
                 await lockPool.end();
             if (owned)