melchizedek-agents 1.1.0 → 1.2.0

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

@@ -50,11 +50,18 @@
  *     its model call is not checkpointed and runs again on resume.
  *   - A dispatch route that is an agent answers through the transcript
  *     projection (ProjectedSessionService, lib/session/transcript.ts), which
- *     copies the session when the route opens it and applies only the
- *     route's own appends to that copy. Restored events cannot reach that
- *     copy through the store, so a checkpoint taken inside such a route is
- *     not resumed: runDurableTurn starts that run fresh. A workflow route
- *     writes its own child session and resumes.
+ *     copies the session when the route opens it. The held opening session
+ *     is empty at that open, so the copy is too; the route's append of the
+ *     message is answered with the stored events, and the projection takes
+ *     every event the real session gained, unprojected (the current turn),
+ *     so the route resumes like a single agent. A workflow route writes its
+ *     own child session and resumes. Checkpoints saved before this, which
+ *     1.1.0 set aside, restore the same way.
+ *   - A task backend stores a checkpoint only up to its cap
+ *     (TaskBackendOptions.checkpointMaxBytes, lib/tools/taskTools.ts,
+ *     default 5 MiB of JSON); a save above it keeps the previous checkpoint
+ *     and still answers whether the claim holds, so a huge run resumes from
+ *     an older boundary.
  *   - Each resumed attempt has its own step budget (max_steps, the loop's
  *     call ceiling); attempts are bounded by the queue's MAX_ATTEMPTS.
  *   - `temp:` state lasts one invocation and is never stored, so it does not

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

@@ -50,11 +50,18 @@
  *     its model call is not checkpointed and runs again on resume.
  *   - A dispatch route that is an agent answers through the transcript
  *     projection (ProjectedSessionService, lib/session/transcript.ts), which
- *     copies the session when the route opens it and applies only the
- *     route's own appends to that copy. Restored events cannot reach that
- *     copy through the store, so a checkpoint taken inside such a route is
- *     not resumed: runDurableTurn starts that run fresh. A workflow route
- *     writes its own child session and resumes.
+ *     copies the session when the route opens it. The held opening session
+ *     is empty at that open, so the copy is too; the route's append of the
+ *     message is answered with the stored events, and the projection takes
+ *     every event the real session gained, unprojected (the current turn),
+ *     so the route resumes like a single agent. A workflow route writes its
+ *     own child session and resumes. Checkpoints saved before this, which
+ *     1.1.0 set aside, restore the same way.
+ *   - A task backend stores a checkpoint only up to its cap
+ *     (TaskBackendOptions.checkpointMaxBytes, lib/tools/taskTools.ts,
+ *     default 5 MiB of JSON); a save above it keeps the previous checkpoint
+ *     and still answers whether the claim holds, so a huge run resumes from
+ *     an older boundary.
  *   - Each resumed attempt has its own step budget (max_steps, the loop's
  *     call ceiling); attempts are bounded by the queue's MAX_ATTEMPTS.
  *   - `temp:` state lasts one invocation and is never stored, so it does not
@@ -67,7 +74,6 @@
  *     clears one; the caller does when the run finishes.
  */
 import { createHash, randomUUID } from 'node:crypto';
-import { isDispatchSyndicate } from '../../dispatch.js';
 import { getFunctionCalls, getFunctionResponses, parseTurnEvents } from '../events.js';
 import { InProcessSessionService } from '../sessions.js';
 import { runSyndicateTurn } from '../syndicateTurn.js';
@@ -311,17 +317,6 @@ class CheckpointingStore {
 export function checkpointingSessions(opts) {
     return new CheckpointingStore(opts);
 }
-/**
- * A dispatch route's checkpoint the store cannot resume: the run's own
- * session holds route events past the message, which the route reads
- * through the transcript projection (see LIMITS in the header).
- */
-function projectedRouteCheckpoint(config, cp, appName, userId) {
-    if (!isDispatchSyndicate(config))
-        return false;
-    const own = cp.sessions.find((s) => s.appName === appName && s.userId === userId && s.id === cp.sessionId);
-    return !!own && own.events.length > 1;
-}
 /**
  * runSyndicateTurn, durable: the run's sessions live in a fresh in-process
  * store, restored from the sink's checkpoint when it is this run's for this
@@ -331,8 +326,7 @@ function projectedRouteCheckpoint(config, cp, appName, userId) {
  */
 export async function runDurableTurn(opts) {
     const { runId, checkpoints, onLost, onSaveError, sessions: inner, signal, ...turn } = opts;
-    const loaded = usableCheckpoint(await checkpoints.load(), runId, turn.parts);
-    const from = loaded && !projectedRouteCheckpoint(turn.config, loaded, turn.appName, turn.userId) ? loaded : null;
+    const from = usableCheckpoint(await checkpoints.load(), runId, turn.parts);
     const sessionId = from ? from.sessionId : randomUUID();
     const controller = new AbortController();
     const forward = () => controller.abort(signal?.reason);

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

@@ -57,6 +57,10 @@
  * agent reads it (an approval runs or refuses its pinned call, a question's
  * answer is the call's response), finishes, and its answer is the open
  * call's response. A child that pauses again leaves the call open again.
+ * A skill script's approval is the same pause, and so is an OAuth consent
+ * request (ADR 0118): the child gets the caller's consent step, its flows
+ * bound to the caller's app (consentPinnedTo), and a grant's answer travels
+ * down the open call as a decision does.
  *
  * CALLS TO SUBAGENTS IN ONE STEP RUN CONCURRENTLY (ADR 0116), under the
  * caller's `max_concurrency` (the syndicate's root key, default
@@ -100,7 +104,7 @@
  */
 import type { ModelAdapter } from '../../models/contract.ts';
 import type { Tool, ToolContext } from '../../tools/tool.ts';
-import type { TurnEvent, TurnPart } from '../events.ts';
+import type { TurnEvent, TurnFunctionCall, TurnPart } from '../events.ts';
 import type { Session, SessionService } from '../sessions.ts';
 import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
 import type { NativeAgent } from './request.ts';
@@ -141,6 +145,12 @@ export interface WorkflowSubagentEnd {
         interruptIds: readonly string[];
     };
     stopped?: boolean;
+    /**
+     * The request calls it paused on, by id, when they are not in its own
+     * session: a nested dispatch syndicate's (ADR 0120) may wait in a route's
+     * delegation below it. A workflow node raises these again on its caller's walk.
+     */
+    requests?: TurnFunctionCall[];
 }
 /** A workflow syndicate delegated to as a subagent (ADR 0098): its name and description, and the walk one call runs. */
 export interface WorkflowSubagent {
@@ -228,6 +238,27 @@ export declare function childAppName(parent: {
     appName: string;
     delegated?: boolean;
 }, caller: string, name: string): string;
+/**
+ * What runs a child session filed below a route or a node (ADR 0120): a
+ * dispatch route, or a workflow node. Its segment carries the kind, so a
+ * route's or a node's session never shares a key with a delegated call's.
+ */
+export type EntryKind = 'route' | 'node';
+/**
+ * The app name a nested syndicate run as a dispatch route or a workflow
+ * node is filed under (ADR 0119, ADR 0120): the session that runs it, and
+ * the entry's name behind its kind (`<app>/route:<route>`,
+ * `<walk's app>/node:<node>`). Agent names are identifiers, so a `:` never
+ * occurs in one, and a delegated call's key (childAppName: names only)
+ * never equals a route's or a node's: a delegate orchestrator `X` calling
+ * `Y` files `<app>/X/Y`, a route `X` with a nested node `Y` files
+ * `<app>/route:X/node:Y`. F3 (ADR 0119) filed it under `<app>/<entry>`
+ * (entryAppNameF3) and ADR 0106 under the entry's name alone; entrySession
+ * and the pause walk still read both.
+ */
+export declare function entryAppName(parentAppName: string, name: string, kind: EntryKind): string;
+/** Where ADR 0119 filed a route's or a node's session before the kind segment (ADR 0120): `<app>/<entry>`. */
+export declare function entryAppNameF3(parentAppName: string, name: string): string;
 /**
  * The session a delegated call ran in before ADR 0111, filed under the
  * subagent's name alone, when it is the one to continue (`continues`): the
@@ -239,6 +270,38 @@ export declare function legacyChild(sessions: Pick<SessionService, 'get'>, key:
     userId: string;
     sessionId: string;
 }, name: string, continues: boolean): Promise<Session | undefined>;
+/**
+ * The session a route's or a node's entry ran in before the kind segment
+ * (ADR 0120), when it is the one to continue (`continues`): the one F3
+ * filed under `<app>/<entry>`, else the one ADR 0106 filed under the
+ * entry's name alone. Read only when none exists under entryAppName.
+ */
+export declare function legacyEntry(sessions: Pick<SessionService, 'get'>, key: {
+    appName: string;
+    userId: string;
+    sessionId: string;
+}, name: string, continues: boolean): Promise<Session | undefined>;
+/**
+ * The child session a nested syndicate run as a dispatch route or a
+ * workflow node runs on (ADR 0119, ADR 0120): the one filed under
+ * entryAppName, else, when the entry ran in `parent` before (an event it
+ * authored there) or a pause was found waiting below it (`resuming`), the
+ * one filed under an older key (legacyEntry), else a new one from `state`.
+ */
+export declare function entrySession(sessions: Pick<SessionService, 'get' | 'create'>, parent: {
+    appName: string;
+    userId: string;
+    sessionId: string;
+    events: readonly TurnEvent[];
+}, name: string, kind: EntryKind, state: Record<string, unknown>, resuming?: boolean): Promise<Session>;
+/**
+ * The consent step as a child run reaches it (ADR 0118): a flow it begins
+ * is bound to `appName`, the caller's app, so the callback stores the grant
+ * under the app the run's pinned credentials read (the root's), never under
+ * the child session's agent path. A grandchild pins its caller's pinned
+ * step again; the first pin is applied last, so the root's app wins.
+ */
+export declare function consentPinnedTo(consent: NonNullable<AgentLoopContext['consent']>, appName: string): NonNullable<AgentLoopContext['consent']>;
 /**
  * Runs one delegated call: `agent` on its own session with the call's
  * `request` as its message, the child's state writes recorded in `context`.
@@ -271,3 +334,21 @@ export declare function runWorkflowSubagent(workflow: WorkflowSubagent, args: Re
  * does, a SubagentPause again when the walk pauses again.
  */
 export declare function resumeWorkflowSubagent(workflow: WorkflowSubagent, answer: TurnPart[], context: ToolContext, scope: DelegationScope): Promise<unknown>;
+/** A nested dispatch syndicate as its entry runs it: its name, the loaded file, and the options its routes compile with (lib/compile.ts DispatchSpec). */
+export interface NestedDispatchEntry {
+    name: string;
+    config: unknown;
+    compile: unknown;
+}
+/**
+ * Runs a nested dispatch syndicate as a walk (ADR 0120): its own turn, on
+ * the conversation its caller opened (`run`), through the turn runner the
+ * current turn carries (TurnControl.nestedDispatch), under the turn's
+ * controls. Completed, it yields one event, never stored, that carries the
+ * route's final text and the conversation's state writes: the caller reads
+ * the answer and records the writes from it, as from a walk's last event.
+ * Paused, it ends with the request's id, and the request call itself for a
+ * workflow node to raise again. Failed, it throws the turn's error. A
+ * delegated call, a dispatch route and a workflow node all run it.
+ */
+export declare function nestedDispatchWalk(entry: NestedDispatchEntry, run: Pick<WorkflowSubagentRun, 'sessions' | 'appName' | 'userId' | 'sessionId' | 'userParts' | 'signal'>): AsyncGenerator<TurnEvent, WorkflowSubagentEnd | undefined>;

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

@@ -57,6 +57,10 @@
  * agent reads it (an approval runs or refuses its pinned call, a question's
  * answer is the call's response), finishes, and its answer is the open
  * call's response. A child that pauses again leaves the call open again.
+ * A skill script's approval is the same pause, and so is an OAuth consent
+ * request (ADR 0118): the child gets the caller's consent step, its flows
+ * bound to the caller's app (consentPinnedTo), and a grant's answer travels
+ * down the open call as a decision does.
  *
  * CALLS TO SUBAGENTS IN ONE STEP RUN CONCURRENTLY (ADR 0116), under the
  * caller's `max_concurrency` (the syndicate's root key, default
@@ -104,6 +108,7 @@ import { createTurnEvent } from '../events.js';
 import { TEMP_STATE_PREFIX } from '../sessions.js';
 import { REQUEST_INPUT_CALL } from './history.js';
 import { SelfCorrection } from './selfCorrection.js';
+import { currentTurnControl } from '../turnControl.js';
 // ── The subagent tool ────────────────────────────────────────────────────────
 /** Where a subagent tool keeps the agent it runs. A global symbol, so a second copy of this module still finds it. */
 export const SUBAGENT = Symbol.for('melchizedek.subagent');
@@ -271,6 +276,25 @@ function answerOf(agent, last) {
 export function childAppName(parent, caller, name) {
     return parent.delegated ? `${parent.appName}/${name}` : `${parent.appName}/${caller}/${name}`;
 }
+/**
+ * The app name a nested syndicate run as a dispatch route or a workflow
+ * node is filed under (ADR 0119, ADR 0120): the session that runs it, and
+ * the entry's name behind its kind (`<app>/route:<route>`,
+ * `<walk's app>/node:<node>`). Agent names are identifiers, so a `:` never
+ * occurs in one, and a delegated call's key (childAppName: names only)
+ * never equals a route's or a node's: a delegate orchestrator `X` calling
+ * `Y` files `<app>/X/Y`, a route `X` with a nested node `Y` files
+ * `<app>/route:X/node:Y`. F3 (ADR 0119) filed it under `<app>/<entry>`
+ * (entryAppNameF3) and ADR 0106 under the entry's name alone; entrySession
+ * and the pause walk still read both.
+ */
+export function entryAppName(parentAppName, name, kind) {
+    return `${parentAppName}/${kind}:${name}`;
+}
+/** Where ADR 0119 filed a route's or a node's session before the kind segment (ADR 0120): `<app>/<entry>`. */
+export function entryAppNameF3(parentAppName, name) {
+    return `${parentAppName}/${name}`;
+}
 /**
  * The session a delegated call ran in before ADR 0111, filed under the
  * subagent's name alone, when it is the one to continue (`continues`): the
@@ -283,6 +307,32 @@ export async function legacyChild(sessions, key, name, continues) {
         return undefined;
     return sessions.get({ appName: name, userId: key.userId, sessionId: key.sessionId });
 }
+/**
+ * The session a route's or a node's entry ran in before the kind segment
+ * (ADR 0120), when it is the one to continue (`continues`): the one F3
+ * filed under `<app>/<entry>`, else the one ADR 0106 filed under the
+ * entry's name alone. Read only when none exists under entryAppName.
+ */
+export async function legacyEntry(sessions, key, name, continues) {
+    if (!continues)
+        return undefined;
+    return (await sessions.get({ appName: entryAppNameF3(key.appName, name), userId: key.userId, sessionId: key.sessionId })) ?? (await legacyChild(sessions, key, name, true));
+}
+/**
+ * The child session a nested syndicate run as a dispatch route or a
+ * workflow node runs on (ADR 0119, ADR 0120): the one filed under
+ * entryAppName, else, when the entry ran in `parent` before (an event it
+ * authored there) or a pause was found waiting below it (`resuming`), the
+ * one filed under an older key (legacyEntry), else a new one from `state`.
+ */
+export async function entrySession(sessions, parent, name, kind, state, resuming = false) {
+    const key = { appName: entryAppName(parent.appName, name, kind), userId: parent.userId, sessionId: parent.sessionId };
+    const own = await sessions.get(key);
+    if (own)
+        return own;
+    const legacy = await legacyEntry(sessions, parent, name, resuming || parent.events.some((e) => e.author === name));
+    return legacy ?? (await sessions.create({ ...key, state }));
+}
 /** Whether `caller` called `name` in `events` in a call other than `callId`: the subagent ran for it before. */
 function calledBefore(events, caller, name, callId) {
     return events.some((e) => e.author === caller && (e.content?.parts ?? []).some((p) => p.functionCall?.name === name && p.functionCall.id !== callId));
@@ -304,6 +354,19 @@ async function childSession(name, context, scope, resuming) {
     const legacy = await legacyChild(sessions, key, name, resuming || calledBefore(parent.events, scope.caller, name, context.functionCallId));
     return legacy ?? (await sessions.create({ ...key, state: { ...scope.stateBase, ...context.stateDelta } }));
 }
+/**
+ * The consent step as a child run reaches it (ADR 0118): a flow it begins
+ * is bound to `appName`, the caller's app, so the callback stores the grant
+ * under the app the run's pinned credentials read (the root's), never under
+ * the child session's agent path. A grandchild pins its caller's pinned
+ * step again; the first pin is applied last, so the root's app wins.
+ */
+export function consentPinnedTo(consent, appName) {
+    return {
+        has: (provider) => consent.has(provider),
+        begin: (binding) => consent.begin({ ...binding, appName }),
+    };
+}
 /** Step 5: an event's state writes, `temp:` keys aside, into the call's state delta. */
 function recordState(event, context) {
     for (const [k, v] of Object.entries(event.actions?.stateDelta ?? {})) {
@@ -352,9 +415,10 @@ async function runChild(agent, content, context, scope, resuming) {
         // plugins, so a subagent's own errors are not retried (ADR 0075).
         selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
         ...(ctx.memory ? { memory: ctx.memory } : {}),
-        // The parent's grants, pinned to the root's app (ADR 0072). Not its consent step: an OAuth
-        // consent inside a subagent is not carried to the caller (ADR 0085, ADR 0110).
+        // The parent's grants, pinned to the root's app (ADR 0072), and its consent step: a call that
+        // needs a grant pauses the child, and the pause reaches the turn through the open call (ADR 0118).
         ...(ctx.credentials ? { credentials: ctx.credentials } : {}),
+        ...(ctx.consent ? { consent: consentPinnedTo(ctx.consent, ctx.session.appName) } : {}),
         ...(ctx.signal ? { signal: ctx.signal } : {}),
         ...(ctx.adapterFor ? { adapterFor: ctx.adapterFor } : {}),
         ...(ctx.log ? { log: ctx.log } : {}),
@@ -443,3 +507,94 @@ async function walkChild(workflow, userParts, context, scope, resuming) {
     }
     return answerOf({}, last);
 }
+/** The engine's approval request call (lib/runtime/approvals.ts APPROVAL_REQUEST). */
+const APPROVAL_REQUEST_CALL = 'adk_request_confirmation';
+/**
+ * The message a nested dispatch syndicate's turn reads (ADR 0120): the
+ * parts as they came, except an answer to a question, which comes down as
+ * an `ask_user` reply (a delegated call's resume) or an `adk_request_input`
+ * reply (a workflow node's), and goes in as the plain text it was, as a
+ * person's answer reaches a turn at the top.
+ */
+function dispatchParts(parts) {
+    return parts.map((p) => {
+        const r = p.functionResponse;
+        if (!r || (r.name !== ASK_USER_CALL && r.name !== REQUEST_INPUT_CALL))
+            return p;
+        const result = r.response?.result;
+        return { text: typeof result === 'string' ? result : JSON.stringify(result ?? '') };
+    });
+}
+/**
+ * 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).
+ */
+function requestCallOf(end) {
+    const id = end.interruptId;
+    if (!id)
+        return undefined;
+    const approval = end.approval;
+    if (approval) {
+        return {
+            id,
+            name: APPROVAL_REQUEST_CALL,
+            args: { originalFunctionCall: { name: approval.tool ?? '', args: approval.args ?? {}, ...(approval.callId ? { id: approval.callId } : {}) }, toolConfirmation: { confirmed: false } },
+        };
+    }
+    const input = end.input;
+    if (input) {
+        return {
+            id,
+            name: REQUEST_INPUT_CALL,
+            args: {
+                interruptId: id,
+                message: input.message ?? '',
+                ...(input.payload !== undefined ? { payload: input.payload } : {}),
+                ...(input.schema !== undefined ? { response_schema: input.schema } : {}),
+            },
+        };
+    }
+    return undefined;
+}
+/**
+ * Runs a nested dispatch syndicate as a walk (ADR 0120): its own turn, on
+ * the conversation its caller opened (`run`), through the turn runner the
+ * current turn carries (TurnControl.nestedDispatch), under the turn's
+ * controls. Completed, it yields one event, never stored, that carries the
+ * route's final text and the conversation's state writes: the caller reads
+ * the answer and records the writes from it, as from a walk's last event.
+ * Paused, it ends with the request's id, and the request call itself for a
+ * workflow node to raise again. Failed, it throws the turn's error. A
+ * delegated call, a dispatch route and a workflow node all run it.
+ */
+export async function* nestedDispatchWalk(entry, run) {
+    const runner = currentTurnControl()?.nestedDispatch;
+    if (!runner)
+        throw new Error(`'${entry.name}' is a nested dispatch syndicate, which runs only inside a syndicate turn (runSyndicateTurn).`);
+    const end = await runner({
+        config: entry.config,
+        compile: entry.compile,
+        name: entry.name,
+        sessions: run.sessions,
+        appName: run.appName,
+        userId: run.userId,
+        sessionId: run.sessionId,
+        parts: dispatchParts(run.userParts),
+    });
+    if (end.status === 'canceled' || run.signal?.aborted || currentTurnControl()?.stopReason)
+        return { stopped: true };
+    if (end.status === 'failed')
+        throw new Error(end.error?.message ?? `${entry.name} failed.`);
+    if (end.status === 'input-required' && end.interruptId) {
+        const request = requestCallOf(end);
+        return { run: { interruptIds: [end.interruptId] }, ...(request ? { requests: [request] } : {}) };
+    }
+    yield createTurnEvent({
+        author: entry.name,
+        content: { role: 'model', parts: [{ text: end.text }] },
+        ...(Object.keys(end.stateDelta).length ? { actions: { stateDelta: end.stateDelta } } : {}),
+    });
+    return { run: { interruptIds: [] } };
+}

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

@@ -104,14 +104,48 @@
  * 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).
  *
+ * 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
+ * walk, on one event of its own (lib/workflow/turn.ts), so the caller's
+ * walk pauses on the same ids; deepestPause follows such a request down,
+ * by id, through each child session filed under entryAppName (its kind in
+ * the key: `route:`, `node:`, ADR 0120; else an older key, legacyEntry) to
+ * the node that asked. A dispatch route that is one leaves its pause
+ * record as the conversation's last event (routePause). A delegated nested
+ * workflow's node that is one is followed the same way.
+ *
+ * NESTED DISPATCH SYNDICATES (ADR 0120). One runs as a turn of its own on
+ * its own conversation (the child session of a delegated call, a route or
+ * a node), its routes answering there as a turn's routes answer in the
+ * turn's conversation. conversationPause finds what it waits on as the
+ * turn finds it at the top: a route's pause record, a route's open
+ * request, question or consent request, else a pause inside a call a route
+ * left open (filed `<conversation>/<route>/<subagent>`). pauseBelow falls
+ * to it when the subagent's own checks find nothing; nestedWorkflowPause
+ * when the child session is not a walk. The answer goes down the open
+ * 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 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
+ * nothing of its own. An OAuth consent request (`adk_request_credential`)
+ * the subagent left open in its child session is a pause too: the walk
+ * reports it with the path (pendingConsent), the turn runner stores the
+ * grant's answer once the callback has stored the grant, and the open
+ * call carries that answer down as it carries an approval decision; the
+ * child's own grantedCalls binds it and runs its paused call again.
+ *
  * ADK stays out of this file: an ADK tool an agent still lists is asked
  * whether it gates through its own checkRequireConfirmation, by shape.
  */
 import type { ToolConfirmation } from '../../tools/tool.ts';
 import type { PendingInput } from '../../workflowConfig.ts';
 import type { PendingApproval } from '../approvals.ts';
+import type { PendingConsent } from '../credentials.ts';
 import type { TurnEvent, TurnFunctionCall, TurnPart } from '../events.ts';
 import type { Session, SessionService } from '../sessions.ts';
+import type { EntryKind } from './delegate.ts';
 import type { NativeAgent } from './request.ts';
 /** Why a confirmation does not bind to the call it pins: ADK's IntentMismatchError reasons. */
 export type IntentMismatchReason = 'untrusted_request' | 'malformed_request' | 'unknown_original_call' | 'unregistered_tool' | 'tool_name_mismatch' | 'arguments_mismatch' | 'confirmation_not_required';
@@ -168,6 +202,8 @@ export interface DelegatedPause {
     approval?: PendingApproval;
     /** The question, when the asker waits on one; its `path` is set. */
     question?: PendingInput;
+    /** The OAuth consent request, when the asker waits for a grant (ADR 0118); its `path` is set. */
+    consent?: PendingConsent;
 }
 /** Where a session's delegated calls opened their child sessions: the store, and the caller's user and session ids. */
 export interface DelegationKey {
@@ -194,6 +230,52 @@ export declare function openCalls(events: readonly TurnEvent[], author?: string)
     author: string;
     call: TurnFunctionCall;
 }>;
+/** 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]`. */
+    path: string[];
+    /** The approval request, its `agent` the node that asked and its `path` set. */
+    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. */
+    consent?: PendingConsent;
+}
+/**
+ * The pause a nested workflow run as a dispatch route or a workflow node
+ * holds (ADR 0119): `name`'s child session below the session filed under
+ * `key.appName` (delegate.ts entryAppName), else the one filed under its
+ * name alone (legacyChild), and the paused walk there, followed down to the
+ * node that asked. With `id`, only that interrupt counts: a request a node
+ * raised again on its caller's walk names the one its own walk waits on.
+ */
+export declare function nestedWorkflowPause(key: DelegationKey & {
+    appName: string;
+}, name: string, kind: EntryKind, id?: string, depth?: number): Promise<NestedWorkflowPause | undefined>;
+/**
+ * A dispatch route that is a nested workflow, paused (ADR 0119): the
+ * conversation's last event is the route's pause record (authored by the
+ * route at its own path, no content, the walk's open interrupts in
+ * `longRunningToolIds`; lib/runtime/syndicateTurn.ts stores it), and the
+ * route's child session holds the paused walk under one of those ids.
+ * Anything stored after the record closes it. `routes`, when given, are the
+ * names a record may carry.
+ */
+export declare function routePause(key: DelegationKey & {
+    appName: string;
+}, events: readonly TurnEvent[], routes?: ReadonlySet<string>, depth?: number): Promise<(NestedWorkflowPause & {
+    route: string;
+}) | undefined>;
+/**
+ * An approval request or question found in a workflow's own session, raised
+ * by a node that is a nested workflow (lib/workflow/turn.ts raises its
+ * walk's requests again on the node's event, ADR 0119): the one its walk
+ * waits on, with the path from the node down to the one that asked. Any
+ * other request comes back as it is.
+ */
+export declare function deepestPause<T extends PendingApproval | PendingInput>(key: DelegationKey & {
+    appName: string;
+}, pending: T): Promise<T>;
 /**
  * Every pause waiting inside a delegated call still open in `events` (one
  * session's events), latest call first: each open call whose child session
@@ -202,7 +284,7 @@ export declare function openCalls(events: readonly TurnEvent[], author?: string)
  * longer open, and neither is anything waiting below it.
  */
 export declare function delegatedPauses(key: DelegationKey, events: readonly TurnEvent[], author?: string, depth?: number, seen?: ReadonlySet<string>): Promise<DelegatedPause[]>;
-/** The interrupt a delegated pause waits on: the approval request's id, or the question's. */
+/** The interrupt a delegated pause waits on: the approval request's id, the question's, or the consent request's. */
 export declare function interruptIdOf(pause: DelegatedPause): string | undefined;
 /** The open delegated calls the latest user message resumes, and the ones still waiting after it. */
 export interface ResumedDelegations {
@@ -219,10 +301,11 @@ export interface ResumedDelegations {
  * The delegated calls `agent` left open that the latest user message
  * answers (ADR 0110): the message's approval decisions and question
  * answers (function responses to `adk_request_confirmation` or `ask_user`)
- * matched, by interrupt id, to the pause below each open call. Undefined
- * when the message answers none. The child binds the answer itself: an
- * approval is checked against its pinned call there (approvedCalls), as at
- * the top.
+ * and grants (to `adk_request_credential`, ADR 0118) matched, by interrupt
+ * id, to the pause below each open call. Undefined when the message answers
+ * none. The child binds the answer itself: an approval is checked against
+ * its pinned call there (approvedCalls), a grant against its request
+ * (grantedCalls), as at the top.
  */
 export declare function resumedDelegations(agent: NativeAgent, scope: Scope, sessions: Pick<SessionService, 'get'>): Promise<ResumedDelegations | undefined>;
 export {};