melchizedek-agents 1.3.1 → 1.5.0

package/dist/lib/observability/supabaseSpanExporter.js

@@ -43,6 +43,7 @@ const { ExportResultCode } = core;
 import { hasSupabaseCredentials } from '../persistence/supabaseProvider.js';
 import { TELEMETRY_SCHEMA_VERSION, isModelCallSpan } from './lineage.js';
 import { redactRow, telemetryRedactor } from './redact.js';
+import { outputsDir } from '../paths.js';
 /**
  * TELEMETRY_PAYLOADS: off | errors | sample (default) | all
  * TELEMETRY_PAYLOAD_SAMPLE: 0..1, default 0.10
@@ -300,7 +301,42 @@ export function telemetrySinkEnabled() {
     return process.env.TELEMETRY_SUPABASE === 'true' && hasSupabaseCredentials();
 }
 export function deadLetterPath() {
-    return join(process.env.OUTPUTS_DIR ?? join(process.cwd(), 'outputs'), 'telemetry-deadletter.ndjson');
+    return join(outputsDir(), 'telemetry-deadletter.ndjson');
+}
+/** The tables the exporter writes; nothing else is ever named in its SQL. */
+export const LEDGER_TABLES = ['adk_telemetry', 'adk_turns', 'adk_payloads'];
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+/**
+ * The ledger over a direct Postgres connection (ADR 0131): the same rows the
+ * Supabase sink writes, through one parameterised statement per batch. The
+ * rows go in as one JSON array and `jsonb_populate_recordset` gives each
+ * value its column's type, so JSON, arrays and timestamps need no mapping
+ * here. Only the columns the rows carry are named, so the rest keep their
+ * defaults. The table must be one of LEDGER_TABLES and every column name
+ * comes from the row builders above, never from span content.
+ */
+export function postgresLedgerClient(pool) {
+    return {
+        from(table) {
+            return {
+                async insert(rows) {
+                    if (!LEDGER_TABLES.includes(table))
+                        return { error: { message: `not a ledger table: ${table}` } };
+                    const columns = [...new Set(rows.flatMap((r) => Object.entries(r).filter(([, v]) => v !== undefined).map(([k]) => k)))];
+                    if (!columns.length)
+                        return { error: null };
+                    const list = columns.map(quoteIdent).join(', ');
+                    try {
+                        await pool.query(`INSERT INTO ${quoteIdent(table)} (${list}) SELECT ${list} FROM jsonb_populate_recordset(NULL::${quoteIdent(table)}, $1::jsonb)`, [JSON.stringify(rows)]);
+                        return { error: null };
+                    }
+                    catch (err) {
+                        return { error: { message: err instanceof Error ? err.message : String(err) } };
+                    }
+                },
+            };
+        },
+    };
 }
 const PENDING_TTL_MS = 10 * 60 * 1000;
 const DECISION_TTL_MS = 30 * 60 * 1000;

package/dist/lib/observability/tracer.d.ts

@@ -3,6 +3,7 @@ import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { LlmResponse } from '../models/genaiMapping.ts';
 import type { TurnEvent as Event } from '../runtime/events.ts';
 import type { ModelRequest } from '../models/contract.ts';
+import type { ExporterOptions, LedgerClient } from './supabaseSpanExporter.ts';
 /**
  * Optional OTLP export for a live trace viewer (Phoenix, Langfuse, Grafana
  * Tempo, Jaeger — anything that speaks OTLP/HTTP). Set
@@ -15,6 +16,14 @@ import type { ModelRequest } from '../models/contract.ts';
  * Supabase stays the system of record; this is a viewer.
  */
 export declare function otlpEndpoint(): string | undefined;
+/**
+ * Writes the ledger (adk_turns, adk_telemetry, adk_payloads) through
+ * `client`, batched off the turn's path, with the same rows, payload policy
+ * and redaction as the Supabase sink. One ledger is attached at a time;
+ * attaching another replaces it. Returns a detach that flushes what is
+ * buffered first.
+ */
+export declare function attachLedger(client: LedgerClient, options?: Omit<ExporterOptions, 'client'>): () => Promise<void>;
 /**
  * Flushes buffered span processors (console is synchronous; the Supabase
  * batch sink is not). Call before process exit in short-lived scripts so

package/dist/lib/observability/tracer.js

@@ -51,6 +51,49 @@ function otlpProcessor() {
 let isOtelInitialized = false;
 let tracerProvider;
 let telemetryExporter;
+/**
+ * The ledger an embedding application attaches at run time (ADR 0131):
+ * `attachLedger` (or `postgresStorage({ ledger: true })`) sets it, before or
+ * after tracing starts. The processor below is always registered and does
+ * nothing until then.
+ */
+let attachedLedger;
+class AttachedLedgerProcessor {
+    onStart() { }
+    onEnd(span) {
+        attachedLedger?.processor.onEnd(span);
+    }
+    forceFlush() {
+        return attachedLedger ? attachedLedger.processor.forceFlush().then(() => attachedLedger?.exporter.forceFlush()) : Promise.resolve();
+    }
+    shutdown() {
+        return this.forceFlush();
+    }
+}
+/**
+ * Writes the ledger (adk_turns, adk_telemetry, adk_payloads) through
+ * `client`, batched off the turn's path, with the same rows, payload policy
+ * and redaction as the Supabase sink. One ledger is attached at a time;
+ * attaching another replaces it. Returns a detach that flushes what is
+ * buffered first.
+ */
+export function attachLedger(client, options = {}) {
+    if (telemetrySinkEnabled()) {
+        console.warn('[TELEMETRY] ⚠ a ledger is attached while TELEMETRY_SUPABASE=true: every row is written twice. Use one sink.');
+    }
+    const exporter = new SupabaseSpanExporter({ ...options, client });
+    const entry = { exporter, processor: new sdkBase.BatchSpanProcessor(exporter) };
+    const previous = attachedLedger;
+    attachedLedger = entry;
+    void previous?.processor.shutdown();
+    initializeTracing();
+    return async () => {
+        if (attachedLedger === entry)
+            attachedLedger = undefined;
+        await entry.processor.forceFlush();
+        await entry.exporter.shutdown();
+    };
+}
 /**
  * Flushes buffered span processors (console is synchronous; the Supabase
  * batch sink is not). Call before process exit in short-lived scripts so
@@ -59,6 +102,7 @@ let telemetryExporter;
 export async function flushTracing() {
     await tracerProvider?.forceFlush?.();
     await telemetryExporter?.forceFlush?.();
+    await attachedLedger?.exporter.forceFlush();
 }
 // ── In-process span listeners ────────────────────────────────────────────────
 // Lets a script (e.g. scripts/demo_model_optionality.ts) read finished spans
@@ -231,6 +275,7 @@ export function initializeTracing() {
     const spanProcessors = [
         new SpanLineageProcessor(),
         new SimpleSpanProcessor(new JsonConsoleExporter()),
+        new AttachedLedgerProcessor(),
     ];
     // Optional durable sink (TELEMETRY_SUPABASE=true + Supabase credentials):
     // llm.request and Syndicate Execution spans also land in adk_telemetry.

package/dist/lib/paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * lib/paths.ts — where the engine writes on disk (ADR 0134).
+ *
+ * Each location keeps its own variable, which wins. Without one, the
+ * default is under MELCHIZEDEK_DATA_DIR when that is set, so an embedding
+ * application points every location at its own data directory with one
+ * variable; with neither, the defaults are the historical ones (the working
+ * directory's outputs/, and ~/.melchizedek for the ChatGPT sign-in).
+ *
+ *   location               own variable                     with MELCHIZEDEK_DATA_DIR   default
+ *   generated files, spool OUTPUTS_DIR                      <data>/outputs              <cwd>/outputs
+ *   task lists and jobs    MELCHIZEDEK_TASKS_FILE           <data>/outputs/tasks.json   <cwd>/outputs/tasks.json
+ *   ChatGPT sign-in        MELCHIZEDEK_CHATGPT_SIGNIN_FILE  <data>/chatgpt-signin.json  ~/.melchizedek/chatgpt-signin.json
+ *
+ * Read at each call, never cached. Imports only node built-ins.
+ */
+export declare const DATA_DIR_ENV = "MELCHIZEDEK_DATA_DIR";
+/** MELCHIZEDEK_DATA_DIR, resolved; undefined when unset. */
+export declare function dataDir(env?: NodeJS.ProcessEnv): string | undefined;
+/** Where generated files (images) and the telemetry spool go. */
+export declare function outputsDir(env?: NodeJS.ProcessEnv): string;
+/** The task tools' JSON file, when tasks are not in Postgres. */
+export declare function tasksFile(env?: NodeJS.ProcessEnv): string;
+/** The local Sign in with ChatGPT credential file. */
+export declare function chatGptSignInFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * The engine's own package root (the directory of its package.json named
+ * melchizedek-agents), found from this module's location, whatever the
+ * working directory is; undefined if it cannot be found.
+ */
+export declare function enginePackageRoot(from?: string): string | undefined;

package/dist/lib/paths.js

@@ -0,0 +1,76 @@
+/**
+ * lib/paths.ts — where the engine writes on disk (ADR 0134).
+ *
+ * Each location keeps its own variable, which wins. Without one, the
+ * default is under MELCHIZEDEK_DATA_DIR when that is set, so an embedding
+ * application points every location at its own data directory with one
+ * variable; with neither, the defaults are the historical ones (the working
+ * directory's outputs/, and ~/.melchizedek for the ChatGPT sign-in).
+ *
+ *   location               own variable                     with MELCHIZEDEK_DATA_DIR   default
+ *   generated files, spool OUTPUTS_DIR                      <data>/outputs              <cwd>/outputs
+ *   task lists and jobs    MELCHIZEDEK_TASKS_FILE           <data>/outputs/tasks.json   <cwd>/outputs/tasks.json
+ *   ChatGPT sign-in        MELCHIZEDEK_CHATGPT_SIGNIN_FILE  <data>/chatgpt-signin.json  ~/.melchizedek/chatgpt-signin.json
+ *
+ * Read at each call, never cached. Imports only node built-ins.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const DATA_DIR_ENV = 'MELCHIZEDEK_DATA_DIR';
+const set = (env, name) => env[name]?.trim() || undefined;
+/** MELCHIZEDEK_DATA_DIR, resolved; undefined when unset. */
+export function dataDir(env = process.env) {
+    const d = set(env, DATA_DIR_ENV);
+    return d ? resolve(d) : undefined;
+}
+/** Where generated files (images) and the telemetry spool go. */
+export function outputsDir(env = process.env) {
+    const own = set(env, 'OUTPUTS_DIR');
+    if (own)
+        return resolve(own);
+    const data = dataDir(env);
+    return data ? join(data, 'outputs') : join(process.cwd(), 'outputs');
+}
+/** The task tools' JSON file, when tasks are not in Postgres. */
+export function tasksFile(env = process.env) {
+    const own = set(env, 'MELCHIZEDEK_TASKS_FILE');
+    if (own)
+        return resolve(own);
+    const data = dataDir(env);
+    return data ? join(data, 'outputs', 'tasks.json') : join(process.cwd(), 'outputs', 'tasks.json');
+}
+/** The local Sign in with ChatGPT credential file. */
+export function chatGptSignInFile(env = process.env) {
+    const own = set(env, 'MELCHIZEDEK_CHATGPT_SIGNIN_FILE');
+    if (own)
+        return resolve(own);
+    const data = dataDir(env);
+    return data ? join(data, 'chatgpt-signin.json') : join(homedir(), '.melchizedek', 'chatgpt-signin.json');
+}
+/**
+ * The engine's own package root (the directory of its package.json named
+ * melchizedek-agents), found from this module's location, whatever the
+ * working directory is; undefined if it cannot be found.
+ */
+export function enginePackageRoot(from = fileURLToPath(import.meta.url)) {
+    let dir = dirname(from);
+    for (let i = 0; i < 6; i++) {
+        const pkg = join(dir, 'package.json');
+        if (existsSync(pkg)) {
+            try {
+                if (JSON.parse(readFileSync(pkg, 'utf-8')).name === 'melchizedek-agents')
+                    return dir;
+            }
+            catch {
+                /* not ours; keep climbing */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}

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

@@ -57,6 +57,27 @@ export declare function consentFrom(author: string | undefined, call: {
  * message a grant (as pendingQuestion reads ask_user).
  */
 export declare function pendingConsent(events: readonly Event[]): PendingConsent | undefined;
+/**
+ * The `adk_request_credential` call a pending request stands for, rebuilt
+ * from what the request carries (ADR 0128): the shape consentFrom reads,
+ * with the request's id, the paused call's id, the provider, the
+ * authorization URL, the state and the scopes. A workflow node raises it
+ * again on its caller's walk when the request itself waits below it (in a
+ * delegated call, or in a nested dispatch syndicate's conversation). It
+ * carries what the stored request carries and nothing more: no client
+ * secret, no code verifier.
+ */
+export declare function credentialRequestCall(consent: PendingConsent): {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+/**
+ * Whether `value`, a walk's answer to a credential request, is a grant's
+ * answer (credentialResponsePart's response): `{ credentialKey, granted: true }`.
+ * A plain-text message the walk read as the answer is not one.
+ */
+export declare function isGrantAnswer(value: unknown): boolean;
 /**
  * The message part that answers request `id` once the grant is stored. It
  * names the provider and carries no credential: the grant is in the

package/dist/lib/runtime/credentials.js

@@ -53,6 +53,38 @@ export function pendingConsent(events) {
     }
     return undefined;
 }
+/**
+ * The `adk_request_credential` call a pending request stands for, rebuilt
+ * from what the request carries (ADR 0128): the shape consentFrom reads,
+ * with the request's id, the paused call's id, the provider, the
+ * authorization URL, the state and the scopes. A workflow node raises it
+ * again on its caller's walk when the request itself waits below it (in a
+ * delegated call, or in a nested dispatch syndicate's conversation). It
+ * carries what the stored request carries and nothing more: no client
+ * secret, no code verifier.
+ */
+export function credentialRequestCall(consent) {
+    return {
+        id: consent.id,
+        name: CREDENTIAL_REQUEST,
+        args: {
+            function_call_id: consent.functionCallId,
+            auth_config: {
+                credentialKey: consent.provider,
+                authScheme: { type: 'oauth2', flows: { authorizationCode: { scopes: Object.fromEntries(consent.scopes.map((s) => [s, ''])) } } },
+                exchangedAuthCredential: { authType: 'oauth2', oauth2: { authUri: consent.authUri, state: consent.state } },
+            },
+        },
+    };
+}
+/**
+ * Whether `value`, a walk's answer to a credential request, is a grant's
+ * answer (credentialResponsePart's response): `{ credentialKey, granted: true }`.
+ * A plain-text message the walk read as the answer is not one.
+ */
+export function isGrantAnswer(value) {
+    return isRecord(value) && value.granted === true && typeof value.credentialKey === 'string' && value.credentialKey !== '';
+}
 /**
  * The message part that answers request `id` once the grant is stored. It
  * names the provider and carries no credential: the grant is in the

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

@@ -137,6 +137,8 @@ export interface WorkflowSubagentRun {
     log?: (message: string) => void;
     selfCorrection: SelfCorrection;
     credentials?: AgentLoopContext['credentials'];
+    /** The caller's consent step, pinned to the caller's app (consentPinnedTo, ADR 0128): a node of the walk pauses for a missing grant. */
+    consent?: AgentLoopContext['consent'];
 }
 /** How a nested workflow's walk ended, as far as a delegated call reads it (lib/workflow/turn.ts NativeWorkflowEnd). */
 export interface WorkflowSubagentEnd {

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';
@@ -484,6 +485,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 (;;) {
@@ -528,8 +531,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 +560,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];