melchizedek-agents 1.0.3 → 1.2.0

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

@@ -0,0 +1,359 @@
+/**
+ * lib/runtime/native/checkpoint.ts — durable long runs: the run's sessions
+ * snapshotted at every step boundary, and a run restored from the last
+ * snapshot taking the next step (ADR 0113, ADR 0015).
+ *
+ * WHY this file exists:
+ *   A background job (ADR 0015) runs as one turn on an in-process session
+ *   store. A worker that stopped mid-job lost everything the job had done,
+ *   and the next claim started again from the first model call. The turn
+ *   runner's signature is pinned by every surface and the boundary suite
+ *   (ADR 0024), so durability lives at the one seam the runner already
+ *   takes: the SessionService. checkpointingSessions wraps the in-process
+ *   store a run writes, hands a snapshot of every session to a sink at each
+ *   step boundary, and restores a snapshot into a fresh store so that the
+ *   runner, unchanged, continues where the snapshot stood. runDurableTurn
+ *   is runSyndicateTurn with that store and a sink.
+ *
+ * A STEP BOUNDARY is an append that carries function responses after which
+ * every function call any session of the run holds has its response (calls
+ * listed in their event's longRunningToolIds, which wait on a person, aside).
+ * So a parent waiting on a delegated subagent is never at a boundary, the
+ * subagent's own steps are not either, and a final answer never is: a
+ * resumed run redoes the step that was in flight, and the last one.
+ *
+ * WHAT IT GUARANTEES:
+ *   - A resumed run's stored events equal an uninterrupted run's, ids and
+ *     times of the steps run after the resume aside: restored events keep
+ *     their ids, times and invocation ids, and their state deltas are
+ *     applied again in order (InProcessSessionService.append, applyEvent).
+ *   - The opening message is stored once. A session whose first event is
+ *     the run's own message (the run's session, a workflow route's child)
+ *     is held back on restore: it does not exist until the runner creates
+ *     it, so `resumedSession` reads as on a fresh run, and the runner's
+ *     append of the message is answered with the stored events, the
+ *     opening one returned in its place, onto the caller's own session
+ *     object. Every other session (a delegated subagent's) is restored at
+ *     once, before the runner starts.
+ *   - A checkpoint is used only by the run that wrote it, for the message
+ *     it was written for: its runId and the sha256 of the message's parts
+ *     must match, and its events must parse (parseTurnEvents). Otherwise
+ *     the run starts fresh.
+ *   - The sink's save resolving false means the run no longer holds its
+ *     claim (the job was cancelled or leased elsewhere): runDurableTurn
+ *     aborts the run and reports lostClaim. A save that throws is reported
+ *     to onSaveError and the run goes on; a later attempt resumes from the
+ *     older checkpoint.
+ *
+ * LIMITS:
+ *   - A dispatch syndicate's route classifier runs in a throwaway store, so
+ *     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. 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
+ *     survive a resume.
+ *   - A workflow walk resumes through its own rules (ADR 0094); its
+ *     checkpoint is the sessions it walks.
+ *   - A checkpoint holds the run's sessions, so it carries the user's text,
+ *     model output and tool results: it lives only where the run's record
+ *     lives, under the same owner, and is deleted with it. This module never
+ *     clears one; the caller does when the run finishes.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { getFunctionCalls, getFunctionResponses, parseTurnEvents } from '../events.js';
+import { InProcessSessionService } from '../sessions.js';
+import { runSyndicateTurn } from '../syndicateTurn.js';
+// ── Shapes ───────────────────────────────────────────────────────────────────
+export const CHECKPOINT_VERSION = 1;
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** The parts as runSyndicateTurn stores them: a bare string becomes `{ text }`. */
+function normalizedParts(parts) {
+    return parts.map((p) => (typeof p === 'string' ? { text: p } : p));
+}
+/** sha256 hex of the message's parts, as a checkpoint names its run's message. */
+export function openingHashOf(parts) {
+    return createHash('sha256').update(JSON.stringify(normalizedParts(parts))).digest('hex');
+}
+const keyOf = (appName, userId, id) => JSON.stringify([appName, userId, id]);
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * The checkpoint, checked, when it belongs to this run and this message;
+ * null otherwise. A stored checkpoint is data read back from a table or a
+ * file, so every field the restore reads is checked before it is trusted.
+ */
+export function usableCheckpoint(cp, runId, parts) {
+    if (!isRecord(cp) || cp.version !== CHECKPOINT_VERSION)
+        return null;
+    if (cp.runId !== runId || cp.openingHash !== openingHashOf(parts))
+        return null;
+    if (typeof cp.sessionId !== 'string' || !cp.sessionId)
+        return null;
+    if (typeof cp.steps !== 'number' || !Number.isInteger(cp.steps) || cp.steps < 0)
+        return null;
+    if (!Array.isArray(cp.sessions))
+        return null;
+    try {
+        for (const [i, s] of cp.sessions.entries()) {
+            if (!isRecord(s))
+                return null;
+            if (typeof s.appName !== 'string' || typeof s.userId !== 'string' || typeof s.id !== 'string')
+                return null;
+            if (!isRecord(s.createdState) || typeof s.opening !== 'boolean')
+                return null;
+            parseTurnEvents(s.events, `sessions[${i}].events`);
+            if (s.opening && s.events.length === 0)
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return cp;
+}
+/** Content compared as stored JSON. */
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+class CheckpointingStore {
+    inner;
+    opts;
+    openingParts;
+    tracked = new Map();
+    /** Call ids with no response yet, across every session. */
+    openCalls = new Set();
+    seq = 0;
+    /** The order of the first event an agent wrote; -1 when a restored run already had one. */
+    firstAgentSeq;
+    savesLost = false;
+    saving = Promise.resolve();
+    stepCount = 0;
+    /** The eager restore; every method waits on it first. */
+    ready = Promise.resolve();
+    runSessionId;
+    restored;
+    constructor(opts) {
+        this.opts = opts;
+        this.inner = opts.inner ?? new InProcessSessionService();
+        this.openingParts = JSON.stringify(normalizedParts(opts.parts));
+        this.runSessionId = opts.sessionId;
+        const from = opts.from ? usableCheckpoint(opts.from, opts.runId, opts.parts) : null;
+        this.restored = !!from && from.sessionId === opts.sessionId;
+        if (this.restored && from)
+            this.load(from);
+    }
+    get steps() {
+        return this.stepCount;
+    }
+    /** Records the checkpoint: subagent sessions restored now, opening sessions held for the runner. */
+    load(from) {
+        this.stepCount = from.steps;
+        const copy = structuredClone(from.sessions);
+        if (copy.some((s) => s.events.some((e) => e.author !== 'user')))
+            this.firstAgentSeq = -1;
+        const eager = [];
+        for (const s of copy) {
+            const t = { appName: s.appName, userId: s.userId, id: s.id, createdState: s.createdState, opening: s.opening };
+            if (s.opening)
+                t.held = s.events;
+            else
+                eager.push(s);
+            this.tracked.set(keyOf(s.appName, s.userId, s.id), t);
+            for (const e of s.events)
+                this.track(e);
+        }
+        this.ready = (async () => {
+            for (const s of eager) {
+                const session = await this.inner.create({ appName: s.appName, userId: s.userId, sessionId: s.id, state: s.createdState });
+                for (const e of s.events)
+                    await this.inner.append(session, e);
+            }
+        })();
+    }
+    /** Keeps the set of unanswered calls up to date with one stored event. */
+    track(event) {
+        const waiting = new Set(event.longRunningToolIds ?? []);
+        for (const call of getFunctionCalls(event))
+            if (call.id && !waiting.has(call.id))
+                this.openCalls.add(call.id);
+        for (const response of getFunctionResponses(event))
+            if (response.id)
+                this.openCalls.delete(response.id);
+    }
+    async create(request) {
+        await this.ready;
+        const session = await this.inner.create(request);
+        const key = keyOf(session.appName, session.userId, session.id);
+        const known = this.tracked.get(key);
+        if (!known) {
+            this.tracked.set(key, { appName: session.appName, userId: session.userId, id: session.id, createdState: structuredClone(session.state) });
+        }
+        else if (known.held && session.events.length === 0) {
+            known.createdState = structuredClone(session.state);
+        }
+        return session;
+    }
+    async get(key, options) {
+        await this.ready;
+        return this.inner.get(key, options);
+    }
+    async list(request) {
+        await this.ready;
+        return this.inner.list(request);
+    }
+    async delete(key) {
+        await this.ready;
+        this.tracked.delete(keyOf(key.appName, key.userId, key.sessionId));
+        return this.inner.delete(key);
+    }
+    async append(session, event) {
+        await this.ready;
+        if (event.partial)
+            return this.inner.append(session, event);
+        const key = keyOf(session.appName, session.userId, session.id);
+        let t = this.tracked.get(key);
+        if (!t) {
+            // A session the store holds but this run did not create (not expected): tracked from here.
+            t = { appName: session.appName, userId: session.userId, id: session.id, createdState: structuredClone(session.state) };
+            this.tracked.set(key, t);
+        }
+        if (t.held) {
+            const held = t.held;
+            delete t.held;
+            const opening = held[0];
+            if (opening && event.author === 'user' && sameJson(event.content, opening.content)) {
+                // The runner stores the message again: the stored events answer it, onto the caller's session.
+                let first;
+                for (const e of held) {
+                    const stored = await this.inner.append(session, e);
+                    first ??= stored;
+                }
+                return first;
+            }
+            // Some other first write: the hold is dropped and the session starts as the runner writes it.
+            t.opening = undefined;
+        }
+        const stored = await this.inner.append(session, event);
+        const order = this.seq++;
+        t.firstSeq ??= order;
+        if (stored.author !== 'user' && this.firstAgentSeq === undefined)
+            this.firstAgentSeq = order;
+        this.track(stored);
+        if (getFunctionResponses(stored).length > 0 && this.openCalls.size === 0)
+            await this.boundary();
+        return stored;
+    }
+    /** A session is the run's opening one when its first event is the run's message, stored before any agent wrote. */
+    openingOf(t, events) {
+        if (t.opening !== undefined)
+            return t.opening;
+        const first = events[0];
+        if (!first || first.author !== 'user')
+            return false;
+        if (JSON.stringify(first.content?.parts ?? null) !== this.openingParts)
+            return false;
+        if (this.firstAgentSeq === -1)
+            return false;
+        return this.firstAgentSeq === undefined || (t.firstSeq !== undefined && t.firstSeq < this.firstAgentSeq);
+    }
+    async snapshot() {
+        const sessions = [];
+        for (const t of this.tracked.values()) {
+            const events = t.held ?? (await this.inner.get({ appName: t.appName, userId: t.userId, sessionId: t.id }))?.events;
+            if (!events)
+                continue;
+            sessions.push(structuredClone({ appName: t.appName, userId: t.userId, id: t.id, createdState: t.createdState, events, opening: this.openingOf(t, events) }));
+        }
+        return {
+            version: CHECKPOINT_VERSION,
+            runId: this.opts.runId,
+            sessionId: this.runSessionId,
+            openingHash: openingHashOf(this.opts.parts),
+            steps: this.stepCount,
+            savedAt: new Date().toISOString(),
+            sessions,
+        };
+    }
+    /** One step boundary: counted, snapshotted, saved; saves run one after another. */
+    async boundary() {
+        if (this.savesLost)
+            return;
+        this.stepCount += 1;
+        const checkpoint = await this.snapshot();
+        const run = this.saving.then(async () => {
+            if (this.savesLost)
+                return;
+            try {
+                const kept = await this.opts.save(checkpoint);
+                if (kept === false) {
+                    this.savesLost = true;
+                    this.opts.onLost?.();
+                }
+            }
+            catch (err) {
+                this.opts.onSaveError?.(err);
+            }
+        });
+        this.saving = run;
+        await run;
+    }
+}
+/**
+ * A session store that checkpoints a run: the in-process store `inner`,
+ * restored from `from` when it is this run's checkpoint for this message,
+ * saving a snapshot of every session at each step boundary (see the header).
+ */
+export function checkpointingSessions(opts) {
+    return new CheckpointingStore(opts);
+}
+/**
+ * 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
+ * message, and checkpointed at every step boundary. A save that resolves
+ * false aborts the run (`lostClaim`). The caller clears the checkpoint when
+ * the run finishes; this never does.
+ */
+export async function runDurableTurn(opts) {
+    const { runId, checkpoints, onLost, onSaveError, sessions: inner, signal, ...turn } = opts;
+    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);
+    if (signal?.aborted)
+        forward();
+    else
+        signal?.addEventListener('abort', forward, { once: true });
+    let lostClaim = false;
+    const sessionService = checkpointingSessions({
+        runId,
+        sessionId,
+        parts: turn.parts,
+        from,
+        save: (cp) => checkpoints.save(cp),
+        onLost: () => {
+            lostClaim = true;
+            onLost?.();
+            controller.abort(new Error('the run no longer holds its claim'));
+        },
+        ...(onSaveError ? { onSaveError } : {}),
+        ...(inner ? { inner } : {}),
+    });
+    try {
+        const result = await runSyndicateTurn({ ...turn, sessionId, sessionService, signal: controller.signal });
+        return { ...result, resumedFromStep: sessionService.restored && from ? from.steps : 0, lostClaim, sessionId };
+    }
+    finally {
+        signal?.removeEventListener('abort', forward);
+    }
+}

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

@@ -13,12 +13,21 @@
  *
  * ONE CALL, AS ADK'S AgentTool RAN IT:
  *   1. The message: `{ role: 'user', parts: [{ text: args.request }] }`.
- *   2. The subagent's session: the one under the subagent's own name as the
- *      app name, with the caller's user id and session id. It is created on
- *      the first call, with the caller's state as it stands (the session's,
- *      then this call's writes; `temp:` keys dropped), and kept: a later
- *      call, in this turn or another, continues it. This is not a branch of
- *      the caller's session; ADK's AgentTool runs a Runner of its own.
+ *   2. The subagent's session: filed under the agent path (childAppName,
+ *      ADR 0111), with the caller's user id and session id: the caller's
+ *      app name, the caller's name and the subagent's at the top
+ *      (`<app>/<caller>/<subagent>`), the caller's app name and the
+ *      subagent's below it (`<app>/<caller>/<subagent>/<inner>`). It is
+ *      created on the first call, with the caller's state as it stands (the
+ *      session's, then this call's writes; `temp:` keys dropped), and kept:
+ *      a later call, in this turn or another, continues it. This is not a
+ *      branch of the caller's session; ADK's AgentTool runs a Runner of its
+ *      own. ADK filed it under the subagent's name alone, so two syndicates
+ *      with a same-named subagent on one conversation shared it. A session
+ *      stored under that old key is still read (legacyChild): when no
+ *      session exists under the path and the caller has called the
+ *      subagent before (or is resuming a pause found there), the old one is
+ *      continued, so a stored conversation resumes where it stopped.
  *   3. A turn already stopped answers an empty text, before or after the
  *      message is stored.
  *   4. The message is stored as a user event under a fresh invocation id
@@ -34,13 +43,34 @@
  *      schema it is parsed as JSON; text that does not parse fails the call
  *      with the parser's message, as on ADK.
  *
- * A PAUSE INSIDE A SUBAGENT (an ask_user call, an approval request) cannot
- * reach the caller, exactly as under ADK (ADR 0028): the child run ends
- * paused, its last event carries no text, the call answers '', and the gated
- * tool never runs. WS6-2a lifts this.
+ * A PAUSE INSIDE A SUBAGENT (an ask_user call, an approval request, or a
+ * pause inside its own delegated call) reaches the caller (ADR 0110, which
+ * lifts ADR 0028's refusal). The child run ends paused; the call resolves to
+ * a SubagentPause naming the ids it waits on, and the caller stores no
+ * response to it: the call stays open, and the caller's run ends paused too
+ * (agentLoop.ts). The turn finds the pause by walking down the open calls
+ * (interrupts.ts delegatedPauses) and reports it with the agent path. The
+ * answer comes back as the caller's next user message; the caller resumes
+ * the open call (resumeSubagent), which stores the same answer parts as
+ * the child's next message, under a fresh invocation id, and runs the
+ * child's loop on: it reads the answer from its own session as a top-level
+ * 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 one after another, in call order, as
- * ADK runs them; running them concurrently is WS6.
+ * CALLS TO SUBAGENTS IN ONE STEP RUN CONCURRENTLY (ADR 0116), under the
+ * caller's `max_concurrency` (the syndicate's root key, default
+ * DEFAULT_MAX_CONCURRENCY): agentLoop.ts runs each delegated call through
+ * the step's DelegationGate, which starts them in call order as slots free
+ * up, and runs two calls to the same subagent (one child session) one after
+ * the other. The step's responses are stored once every call has answered,
+ * in call order, whatever order the children finished in; a child that
+ * pauses leaves its call open while the others finish and are stored. ADK
+ * ran them one after another; `max_concurrency: 1` keeps that order.
  *
  * NESTED SYNDICATES: a `yaml_reference` subagent is the nested syndicate's
  * orchestrator, named as the entry, listing its own subagent tools. It runs
@@ -49,6 +79,13 @@
  *
  * A NESTED WORKFLOW (ADR 0098): a `yaml_reference` to a workflow syndicate
  * is a workflowSubagentTool, holding the whole graph as a WorkflowSubagent.
+ * A walk that ends paused (an ask_user node's question, an agent node's
+ * approval request) leaves the call open as a child loop's pause does
+ * (ADR 0111): the call resolves to a SubagentPause naming the walk's open
+ * interrupts, and resumeWorkflowSubagent walks the graph again on the
+ * answer, which the walk's own resume (lib/workflow/resume.ts) reads as it
+ * reads a top-level workflow's. An `ask_user` answer reaches the walk as
+ * ADK's explicit reply to its `adk_request_input` call.
  * A call runs as steps 1 to 6 say, with the walk in place of the loop: the
  * graph's walk (lib/workflow/turn.ts, runNativeWorkflow, which
  * lib/compileNative.ts hands over) stores the message itself and yields the
@@ -67,8 +104,8 @@
  */
 import type { ModelAdapter } from '../../models/contract.ts';
 import type { Tool, ToolContext } from '../../tools/tool.ts';
-import type { TurnEvent } from '../events.ts';
-import type { SessionService } from '../sessions.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';
 import { SelfCorrection } from './selfCorrection.ts';
@@ -101,12 +138,26 @@ export interface WorkflowSubagentRun {
     selfCorrection: SelfCorrection;
     credentials?: AgentLoopContext['credentials'];
 }
+/** How a nested workflow's walk ended, as far as a delegated call reads it (lib/workflow/turn.ts NativeWorkflowEnd). */
+export interface WorkflowSubagentEnd {
+    /** The walk's result; `interruptIds` holds what it paused on. */
+    run?: {
+        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 {
     name: string;
     description?: string;
-    /** Stores the message on the child session and walks the whole graph, yielding each event ADK's Runner yields. Throws what a node gave up with. */
-    walk(run: WorkflowSubagentRun): AsyncGenerator<TurnEvent, unknown>;
+    /** Stores the message on the child session and walks the whole graph (a resume when it holds a paused walk), yielding each event ADK's Runner yields. Throws what a node gave up with. */
+    walk(run: WorkflowSubagentRun): AsyncGenerator<TurnEvent, WorkflowSubagentEnd | undefined>;
 }
 /** A nested workflow listed on its caller as a tool: the declaration ADK's AgentTool gave a Workflow, and the graph the call walks. */
 export interface WorkflowSubagentTool extends Tool {
@@ -121,19 +172,136 @@ export declare function workflowSubagentOf(tool: unknown): WorkflowSubagent | un
  * carrying SUBAGENT) holds, else undefined.
  */
 export declare function subagentOf(tool: unknown): NativeAgent | undefined;
+/**
+ * A delegated call whose child run ended paused (ADR 0110): the ids the
+ * child waits on. The caller stores no response to the call and ends its
+ * own run paused.
+ */
+export declare class SubagentPause {
+    readonly pending: readonly string[];
+    constructor(pending: readonly string[]);
+}
 /** What a delegated call needs from its caller's step. */
 export interface DelegationScope {
     /** The caller's loop context: its session, store, adapters, memory, signal. */
     ctx: AgentLoopContext;
+    /** The caller's name: a segment of the path a top-level caller's subagents are filed under (childAppName). */
+    caller: string;
     /** The caller's session state as the step left it. */
     stateBase: Readonly<Record<string, unknown>>;
     /** The turn's signal, as the step sent it. */
     signal?: AbortSignal;
     /** The loop the child runs on (agentLoop.ts passes its own runAgentLoop). */
     runLoop: (agent: NativeAgent, ctx: AgentLoopContext) => AsyncGenerator<TurnEvent, AgentLoopEnd>;
-    /** Calls sharing this key run one after another (agentLoop.ts passes the step's scope). */
-    queue: object;
 }
+/** Delegated calls one step runs at once when the syndicate sets no `max_concurrency` (ADR 0116). */
+export declare const DEFAULT_MAX_CONCURRENCY = 4;
+/** One delegated call's place in its step's DelegationGate. */
+export interface DelegationTicket {
+    /** Resolves once the call may start: a slot is free, and every earlier call under its key has released. */
+    readonly ready: Promise<void>;
+    /** Frees the slot and the key's lane. Idempotent; call it whether the call ran, failed or never started. */
+    release(): void;
+}
+/**
+ * The delegated calls of one step (ADR 0116): at most `limit` run at once,
+ * started in the order they entered (agentLoop.ts enters them in call
+ * order, synchronously, before any of them runs), and calls sharing a key
+ * (the subagent's name, so one child session) run one after another in
+ * that order. A slot is held from the call's start to its release, which
+ * comes as soon as the child's run ends: what the step does after (self-
+ * correction's bookkeeping, which waits on earlier calls) holds no slot. A
+ * call waiting on an earlier same-key call holds its slot meanwhile: the
+ * earlier call already holds one, so the wait always ends.
+ */
+export declare class DelegationGate {
+    readonly limit: number;
+    private active;
+    private readonly waiting;
+    private readonly lanes;
+    constructor(limit?: number);
+    /** Enters one call under `key`, behind every call entered before it. */
+    enter(key: string): DelegationTicket;
+    /** Runs `run` under a ticket for `key`: once ready, the ticket released when it settles. */
+    run<T>(key: string, run: () => Promise<T>): Promise<T>;
+    private pump;
+}
+/**
+ * The app name a delegated call's child session is filed under (ADR 0111):
+ * the agent path. Below a top-level agent, its app name, its name and the
+ * subagent's (`<app>/<caller>/<subagent>`); below a delegated subagent,
+ * whose own session is already filed under its path, that app name and the
+ * subagent's. Agent names are identifiers (lib/syndicateSchema.ts), so
+ * never hold a `/`.
+ */
+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
+ * caller of a stored conversation called the subagent there before, or a
+ * pause was found waiting in it. Read only when no session exists under the
+ * agent path.
+ */
+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`.
@@ -141,6 +309,14 @@ export interface DelegationScope {
  * throws, and for an output-schema answer that does not parse.
  */
 export declare function runSubagent(agent: NativeAgent, args: Record<string, unknown>, context: ToolContext, scope: DelegationScope): Promise<unknown>;
+/**
+ * Resumes a delegated call the child left paused (ADR 0110): `answer` (the
+ * caller's user message parts that answer what waits below the call) is
+ * stored as the child's next message and the child's loop runs on, as
+ * runSubagent runs it. Resolves as runSubagent does, a SubagentPause again
+ * when the child pauses again.
+ */
+export declare function resumeSubagent(agent: NativeAgent, answer: TurnPart[], context: ToolContext, scope: DelegationScope): Promise<unknown>;
 /**
  * Runs one delegated call to a nested workflow (ADR 0098): the whole graph
  * walked on the child session with the call's `request` as its message,
@@ -148,3 +324,31 @@ export declare function runSubagent(agent: NativeAgent, args: Record<string, unk
  * yielded event's text, '' for none. Throws what the walk throws.
  */
 export declare function runWorkflowSubagent(workflow: WorkflowSubagent, args: Record<string, unknown>, context: ToolContext, scope: DelegationScope): Promise<unknown>;
+/**
+ * Resumes a delegated call whose nested workflow ended paused (ADR 0111):
+ * the graph is walked again on `answer` (the caller's user message parts
+ * that answer the walk's open interrupt), which the walk's resume reads as
+ * it reads a top-level workflow's. An approval decision goes as it came; an
+ * `ask_user` answer goes as ADK's explicit reply to the `adk_request_input`
+ * call it answers, under that call's name. Resolves as runWorkflowSubagent
+ * 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>;