agentfootprint 10.9.0 → 11.0.0

package/dist/esm/core/consentRequest.d.ts

@@ -0,0 +1,488 @@
+/**
+ * consentRequest — the request a consent gate puts to a person: how it is
+ * named, what it is bound to, and how a decision is held to it, once.
+ *
+ * Role:   the ONE owner of that law. A consent gate (a tool's `checkIn`, a
+ *         middleware's `ask`) pauses the run; `mintConsentRequest` mints the request
+ *         at the pause, and `heldDecision` + `spendDecision` hold a resume's
+ *         decision to it. The dispatch loop (`agent/stages/toolCalls.ts`) is
+ *         the only writer and the only place a decision is used; `Agent.resume`
+ *         asks the same pure question earlier, so a mismatch is refused before
+ *         anything moves.
+ * Reads:  the call about to pause; at a resume, the paused run's own state
+ *         (`gatedCallOf`) and the decision.
+ * Writes: nothing — the dispatch loop writes what `mintConsentRequest` returns.
+ *
+ * ── WHY THE ID IS A COMMITMENT, NOT ONLY A NAME ─────────────────────────────
+ * `id = sha256(domain ‖ nonce ‖ canonicalJson(call))`, where the call is
+ * everything that runs on approval: the gate, the tool, the call id, the
+ * served party, the arguments and — for an ask — the middleware, where the
+ * chain resumes and the names of the rules from the asking one on (a resume
+ * refuses an agent whose chain no longer runs those rules, and a rule after
+ * the ask that hands back other arguments than the ones approved — the tool
+ * does not run). The nonce is 128 random bits kept in the paused run's state.
+ *
+ *   - A random nonce makes every pause's id unique and unguessable, so a
+ *     decision for one pause can never answer another — even two pauses of
+ *     the same tool, with the same model-chosen call id and the same
+ *     arguments.
+ *   - Re-deriving the id from the state at resume binds the decision to the
+ *     exact call: a checkpoint whose arguments, tool, call id, party or chain
+ *     position changed after the person was asked derives a different id, and
+ *     no nonce makes it derive the old one (that would be a SHA-256 preimage).
+ *     The person's decision quotes the id they were shown, so a checkpoint
+ *     changed after the ask cannot be made to match it.
+ *   - What it does NOT stop is a hostile writer of the checkpoint store: one
+ *     who rewrites the call, the nonce and the request shown together BEFORE
+ *     the person decides (they then approve what they were shown), or who
+ *     switches the pause into a kind whose resume takes no decision (a
+ *     credential-consent pause). The binding detects drift and replay, not
+ *     that writer; a host that does not trust its store signs checkpoints or
+ *     keeps them server-side.
+ *   - The id carries no run value. The nonce does unlock it — whoever holds
+ *     the nonce can confirm a guess of the arguments — so the state key that
+ *     carries it (`pausedRequest`) is named with the arguments in the
+ *     conversation redaction vocabulary (`redaction/conversation.ts`).
+ *
+ * ── THE DOMAIN ─────────────────────────────────────────────────────────────
+ * The call is fingerprinted as JSON, because JSON is what a person is shown and
+ * what a stored checkpoint holds. A call JSON cannot write down faithfully (a
+ * `Date`, a `Map`, `Infinity` — `lib/jsonFaithful.ts`) cannot be bound, and
+ * `mintConsentRequest` says so instead of fingerprinting a value two different calls
+ * would share. JSON's own equivalences hold: a property whose value is
+ * `undefined` is the property absent, and `-0` is `0`.
+ *
+ * ── ONCE ───────────────────────────────────────────────────────────────────
+ * A request is spent the moment a resume uses a decision for it, approved or
+ * declined (`DecisionLedger`), and "once" holds PER LEDGER. The default is one
+ * ledger in this process's memory, shared by every agent that names none — a
+ * pool that rebuilds an evicted instance, a host that builds a runner per
+ * request, a composition's nested agents all spend in it. It is gone after a
+ * restart and no other process sees it: where more than one process (or a
+ * restart) can resume the same paused run, every agent that can resume it is
+ * given one ledger in a store they all reach (`Agent.create({ decisionLedger })`).
+ * The process's ledger and everything below that is process-wide live on
+ * `globalThis` under one versioned key, so an app that loads both builds of
+ * this package (CJS and ESM) still has ONE (`processState`).
+ *
+ * ── WAS IT USED? ───────────────────────────────────────────────────────────
+ * A host that keeps the pause asks this after a resume of it failed: the call
+ * may have run only if the decision reached a ledger. `spendDecision` is the
+ * one place a decision does, so it reports every attempt to whoever watches
+ * that request (`watchDecisionUse`), and the ledger it went to is asked when
+ * the attempt's own answer was lost. A resume this library took up and never
+ * took to a ledger used nothing; one it never took up cannot be told apart
+ * from a use (`hosting/answeredPause.ts`).
+ *
+ * ── DID IT NEVER RUN? ──────────────────────────────────────────────────────
+ * A watch sees one resume. A host closing a pause no answer can reach asks a
+ * stronger question — can ANY decision for it have been used, by any resume,
+ * before this process started included — and says "did not run" only on
+ * proof (`proveNeverRan`): the ledger the request was MINTED under (its
+ * identity rides the pause, `PendingRequest.ledger`) spends the request
+ * itself, atomically. `true` means no decision had reached it, and none ever
+ * can now — the spend is a tombstone, not a read that a resume elsewhere
+ * could overtake. Anything else is not proof.
+ */
+import type { FlowchartCheckpoint } from 'footprintjs';
+import { type CheckInDecision } from './checkin.js';
+import { type ConsentGate, type ConsentGateKind } from './pause.js';
+/**
+ * The call a consent gate asked a person about — what runs on approval. Read
+ * loosely (`unknown`) because at a resume it comes from a checkpoint: whatever
+ * the state holds is what would run, and that is what gets fingerprinted.
+ */
+export interface GatedCall {
+    readonly gate: ConsentGateKind;
+    /** The tool's name. */
+    readonly tool: unknown;
+    /** The model's id for the call. */
+    readonly toolCallId: unknown;
+    /** The party the tool resolves against (`AgentState.pausedToolParty`), when one was recorded. */
+    readonly party?: unknown;
+    /** The arguments the call runs with. */
+    readonly args: unknown;
+    /** `'ask'` only — the middleware that asked. */
+    readonly middleware?: unknown;
+    /** `'ask'` only — the asking link's index; the chain resumes after it. */
+    readonly askIndex?: unknown;
+    /**
+     * `'ask'` only — the names of the asking link and of every link after it,
+     * in chain order: the rules the call still passes once the person answers.
+     * A position alone would let a redeploy that removed or moved a later rule
+     * resume past it; the names make that a refusal (`'chain-changed'`).
+     */
+    readonly chain?: unknown;
+}
+/** A consent gate's request as the paused run's state carries it (`AgentState.pausedRequest`). */
+export interface PendingRequest {
+    /** The id a decision quotes — 64 hex characters. */
+    readonly id: string;
+    /** 128 random bits, hex — the commitment's key. Never served on the request. */
+    readonly nonce: string;
+    /**
+     * The identity of the ledger the request was minted under — the agent's
+     * `decisionLedger` (`store:` + its `storeId`) or this process's default
+     * (`process:` + a per-process random id). Only that ledger can prove the
+     * paused call never ran ({@link proveNeverRan}). Absent when the ledger has
+     * no stable identity, and on a pause stored before it was recorded: such a
+     * pause can never be proven.
+     */
+    readonly ledger?: string;
+}
+/** What {@link mintConsentRequest} hands the dispatch loop. */
+export interface BoundRequest {
+    readonly request: PendingRequest;
+    /**
+     * The detached copy of the arguments the request is bound to. The call
+     * carries THIS copy from here on — on the request the person is shown, in
+     * the paused run's state, and into the tool on approval — so nothing that
+     * still holds the original can change what was approved.
+     */
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/**
+ * Where the consent requests that have been answered are recorded, so one
+ * decision runs one call — once per LEDGER.
+ *
+ * By default every agent that names none spends in one ledger in this
+ * process's memory: "once" holds across this process's agents — a pool that
+ * rebuilds an evicted instance, a server that builds an agent per request —
+ * and only there. A restart forgets it, and another process never saw it.
+ * When more than one process can resume the same paused run, or a restart
+ * must not forget, give every agent that can resume it one ledger backed by a
+ * store they all reach (`Agent.create({ decisionLedger })`).
+ */
+export interface DecisionLedger {
+    /**
+     * OPTIONAL — the identity of the store this ledger records into. A host that
+     * closes a pause no answer can reach asks the ledger the pause was minted
+     * under — and only that one — to prove its call never ran
+     * ({@link DecisionLedger.spend}); a ledger without a `storeId` never proves,
+     * and the call is recorded as possibly run.
+     *
+     * The contract this library cannot check, and that the proof rests on:
+     *
+     *  - unique per BACKING STORE: one value for one table (or collection, or
+     *    key space) and every process that writes it — never copied from
+     *    staging to production, never shared by per-tenant tables;
+     *  - permanent: the same for the life of that store;
+     *  - changed on any migration to a new store — a request spent in the old
+     *    store is not in the new one, and must not be read as never spent there.
+     *    Pending approvals are then asked again: a decision is spent only in the
+     *    ledger its request was asked under (`'ledger-changed'`).
+     *
+     * Spends in it are permanent too (no expiry) — see `spend`.
+     */
+    readonly storeId?: string;
+    /**
+     * Record `requestId` as answered. Resolve `true` when THIS call recorded it
+     * and `false` when it was already recorded — atomically per id: of two
+     * concurrent calls for one id, exactly one may see `true`. Anything other
+     * than `true` refuses the decision; a throw fails the resume. Both fail
+     * closed: the tool does not run.
+     *
+     * A recorded id stays recorded: for a ledger that is to prove a paused call
+     * never ran (one with a {@link DecisionLedger.storeId}), the result is
+     * permanent — no expiry. A host closing a pause spends its request here as
+     * the proof (`true`: no decision had reached it, and none ever can), then
+     * `closed-proven:<requestId>` to record that IT closed it; a key that expired
+     * would let a spent request read as never spent.
+     */
+    spend(requestId: string): boolean | Promise<boolean>;
+    /**
+     * OPTIONAL — whether `requestId` is recorded as answered, without recording
+     * it. Asked only after a {@link DecisionLedger.spend} for it failed, so a
+     * host can tell a spend that never landed (the call did not run; the pause
+     * stays answerable) from one that did. A ledger without it, or one that
+     * throws or answers anything but `false`, counts as spent: the host stops
+     * offering the pause. Asked, too, whether a host recorded closing a request
+     * (`closed-proven:<requestId>`) — so a retried close keeps the verdict the
+     * first one proved, and a person whose answer arrives after the close is
+     * told the host closed it. Never asked whether the REQUEST is unspent as a
+     * proof that its call did not run: a read can be overtaken by a resume
+     * elsewhere; only `spend` proves.
+     */
+    isSpent?(requestId: string): boolean | Promise<boolean>;
+}
+/**
+ * A NEW {@link DecisionLedger} in this process's memory. Grows by one id per
+ * answered request.
+ *
+ * Agents that name no ledger already share one of these per process, so this
+ * is for a ledger of their own: agents given different ledgers spend
+ * separately, and a decision spent in one is not known to the others.
+ */
+export declare function inMemoryDecisionLedger(): DecisionLedger;
+/**
+ * Register the rules `agent` holds an ask's approval to — its `toolMiddleware`
+ * chain by link name, read each time it is asked — for a host that keeps its
+ * pauses ({@link consentRulesOf}). Called by every `Agent` it builds.
+ */
+export declare function registerConsentRules(agent: object, rules: () => readonly string[]): void;
+/**
+ * The rules `runner` holds an ask's approval to, when it is an agent this
+ * library built — `undefined` for any other runner (a composition, an app's
+ * own), whose nested agents' rules a host cannot see.
+ */
+export declare function consentRulesOf(runner: unknown): readonly string[] | undefined;
+/**
+ * This process's ledger — where an agent that names no `decisionLedger`
+ * spends. One per process, so a decision runs once across every agent
+ * instance this process builds (and every copy of this package it loaded),
+ * not once per instance. It lives as long as the process and grows by one id
+ * per answered request; request ids are unique per pause, so sharing it never
+ * makes one agent's answer collide with another's.
+ */
+export declare function processDecisionLedger(): DecisionLedger;
+/**
+ * Register the ledger `agent` spends its decisions in — `undefined` for the
+ * process's ({@link processDecisionLedger}) — so a host that closes one of its
+ * pauses can ask it for the proof ({@link proveNeverRan}). Called by every
+ * `Agent` it builds.
+ */
+export declare function registerConsentLedger(agent: object, ledger: DecisionLedger | undefined): void;
+/**
+ * The ledger `runner` spends decisions in, when it is an agent this library
+ * built — `undefined` for any other runner (a composition, an app's own).
+ */
+export declare function consentLedgerOf(runner: unknown): DecisionLedger | undefined;
+/**
+ * The identity a pause records for the ledger its request is minted under
+ * ({@link PendingRequest.ledger}), or `undefined` for one that has none:
+ *
+ *  - this process's default ledger: `process:` + an id drawn when the process
+ *    first asked. A restart draws another, so it never answers for a pause an
+ *    earlier process stored — that process took its ledger with it;
+ *  - a ledger naming its store (`DecisionLedger.storeId`): `store:` + that id;
+ *  - any other — an app's own `inMemoryDecisionLedger()`, a ledger without a
+ *    `storeId` — none: it may be one agent's alone, and nothing tells it
+ *    apart from another.
+ */
+export declare function ledgerIdentityOf(ledger: DecisionLedger): string | undefined;
+/** What {@link proveNeverRan} needs to know about a pause being closed, and the door closing it. */
+export interface NeverRanQuestion {
+    /** Every id the paused request is known by — the state's and the question's. */
+    readonly requestIds: readonly string[];
+    /** The identity of the ledger the request was minted under ({@link PendingRequest.ledger}). */
+    readonly mintedUnder: string | undefined;
+    /** The runner serving the session — an agent this library built names its ledger. */
+    readonly runner: unknown;
+    /**
+     * The door keeps its pauses in this process's memory, so no other process
+     * can have answered one. Asked only of this process's default ledger.
+     */
+    readonly storeIsProcessLocal: boolean;
+}
+/**
+ * The key a closer spends, after it won a request, to record that IT closed it
+ * ({@link proveNeverRan}). Request ids are 64 hex characters, so no request id
+ * is ever one of these.
+ */
+export declare function closedProvenKey(requestId: string): string;
+/**
+ * Prove that no decision for a paused request can ever run its call — or say
+ * that it cannot be proven. Spending is the one way a decision reaches a call
+ * (`spendDecision` runs before the tool, on every door), so the proof is the
+ * ledger the request was MINTED under spending the request itself: `true`
+ * there means no decision had reached it and — in the same atomic step — that
+ * none ever can (a later resume is refused). A read (`isSpent`) of the request
+ * would not do: a resume on another replica could spend and run the call
+ * between the read and the close, and a ledger may expire what it reads.
+ *
+ * IDEMPOTENT. Having won the request, the closer spends a second key,
+ * {@link closedProvenKey}, to record that it closed it. The closed pause is
+ * stored only afterwards, and that can fail (the store's write, the run that
+ * goes on from it); a retried close finds the request spent and reads the
+ * marker (`isSpent`) — present: the verdict the first close proved; absent
+ * (a crash between the two spends, a ledger without `isSpent`): not proven, the
+ * safe direction. A request a DECISION spent never has the marker.
+ *
+ * CONSUMES the request: asked only for a pause being closed.
+ *
+ * Fails closed — `false` — whenever the proof cannot be had:
+ *
+ *  - the pause names no request, or no minting ledger (one stored before
+ *    either was recorded, or minted under a ledger with no identity);
+ *  - `runner` is not an agent this library built (a composition, an app's
+ *    own), so its ledger is unknown;
+ *  - its ledger is not the one the request was minted under: a redeploy that
+ *    switched ledgers, or a restart (this process's ledger is a new one) —
+ *    that ledger never saw the spends;
+ *  - the request was minted under this process's default ledger and the
+ *    door's session store is not this process's memory: another replica, on
+ *    its own default ledger, may have spent it and run the call;
+ *  - a spend throws, or answers anything but `true` with no close recorded.
+ */
+export declare function proveNeverRan(question: NeverRanQuestion): Promise<boolean>;
+/**
+ * Whether a host already closed this paused request with the proof that its
+ * call never ran — read, never spent: the ledger it was minted under holds the
+ * close marker for every id ({@link closedProvenKey}). Asked by a door whose
+ * answer to the pause failed because the request was already spent, so a pause
+ * closed elsewhere (whose closed conversation was never stored) is closed as
+ * not run rather than marked as possibly run.
+ */
+export declare function closedByAHost(question: NeverRanQuestion): Promise<boolean>;
+/**
+ * Mint the request for a call about to pause, over a detached copy of its
+ * arguments. `undefined` when the call cannot be bound — its arguments cannot
+ * be copied, are not an object, or are not values JSON writes down faithfully
+ * — and the gate must refuse the call instead of pausing.
+ *
+ * @param ledger the ledger a decision for it will be spent in — its identity
+ *   rides the request ({@link PendingRequest.ledger}), so only that ledger can
+ *   later prove the call never ran.
+ */
+export declare function mintConsentRequest(call: GatedCall, ledger?: DecisionLedger): BoundRequest | undefined;
+/**
+ * The paused call as the paused run's state records it — the one reading both
+ * the resume's early check and the dispatch loop take, so they cannot disagree
+ * about what the request was bound to.
+ */
+export declare function gatedCallOf(read: (key: string) => unknown, gate: ConsentGateKind): GatedCall;
+/**
+ * Hold a resume's input to the request the run is paused on. Pure: it spends
+ * nothing (see {@link spendDecision}).
+ *
+ * @param recorded the paused run's `pausedRequest`, as read — never trusted.
+ * @param call     the paused call, as read ({@link gatedCallOf}).
+ * @param rules    the resuming agent's own `toolMiddleware` chain, by link
+ *   name — an ask's approval holds only for the rules it was asked under.
+ * @param ledger   the ledger the resuming agent spends decisions in — a
+ *   request minted under a ledger that can prove is spent only there.
+ * @returns a detached copy of the decision.
+ * @throws DecisionRequiredError when the input is not a decision at all.
+ * @throws ResumeDecisionError (`'no-request'`, `'request-not-recorded'`,
+ *   `'other-request'`, `'call-changed'`, `'chain-changed'`,
+ *   `'ledger-changed'`) when it cannot answer this request.
+ */
+export declare function heldDecision(input: unknown, gate: ConsentGate, recorded: unknown, call: GatedCall, rules: readonly string[], ledger?: DecisionLedger): CheckInDecision;
+/**
+ * The refusals no decision can change — a paused request that can never be
+ * answered by the agent whose rules are `rules`. See {@link unanswerableReason}.
+ */
+export type UnanswerableReason = 'request-not-recorded' | 'call-changed' | 'chain-changed' | 'ledger-changed';
+/**
+ * Why the request a checkpoint's paused stage records can never be answered —
+ * by any decision — or `undefined` when it can, or when that cannot be told
+ * from the checkpoint (its paused state is not where it should be).
+ *
+ * Read by a host that keeps the pause, so a session is not held by a question
+ * nobody can answer any more: one paused before requests were named
+ * (`'request-not-recorded'`), one whose call changed after the ask
+ * (`'call-changed'`), an ask made under rules the resuming agent no longer
+ * runs (`'chain-changed'` — told only when `rules` are known), or a request
+ * minted under a proving ledger the resuming agent no longer spends in
+ * (`'ledger-changed'` — told only when `ledger` is known).
+ */
+export declare function unanswerableReason(checkpoint: FlowchartCheckpoint, gate: ConsentGateKind, rules: readonly string[] | undefined, ledger?: DecisionLedger): UnanswerableReason | undefined;
+/**
+ * Whether `wouldRun` are the arguments the paused request was minted over —
+ * decided by re-deriving the request's id with them in place of the recorded
+ * ones: the call that runs must be the call the id the person was shown
+ * commits to. Key order and JSON's own equivalences do not count; a value
+ * JSON cannot write down faithfully never matches.
+ *
+ * Held to the REQUEST, never to a copy: an ask's resume hands the rest of the
+ * chain a copy of the approved arguments, and a link that edited that copy in
+ * place would make any comparison against it agree with itself.
+ *
+ * @param recorded the paused run's `pausedRequest`, as read.
+ * @param call     the paused call, as read ({@link gatedCallOf}); its own
+ *   `args` are replaced by `wouldRun`.
+ */
+export declare function runsAsAsked(recorded: unknown, call: GatedCall, wouldRun: unknown): boolean;
+/**
+ * The same question as {@link heldDecision}, asked of a checkpoint before a
+ * resume starts — so a mismatch is refused while nothing has moved. Reads the
+ * paused stage's own state (the root's, or the innermost subflow's on the
+ * pause path). A state it cannot find is left to the dispatch loop, which asks
+ * again where the decision is used.
+ */
+export declare function checkDecisionAgainst(checkpoint: FlowchartCheckpoint, gate: ConsentGate, input: unknown, rules: readonly string[], ledger?: DecisionLedger): void;
+/**
+ * Spend the decision's request in `ledger` — the one place a decision reaches
+ * a ledger, so every attempt is reported to whoever watches the request
+ * ({@link watchDecisionUse}).
+ *
+ * @param signal the resumed run's signal. The engine stops waiting on a stage
+ *   when its run is aborted, but the stage goes on running: a resume whose run
+ *   was aborted takes nothing to a ledger, and one aborted while its ledger
+ *   answered is refused after the spend — spent, and its call never run.
+ * @throws ResumeDecisionError `'already-answered'` when a resume already spent
+ *   it, or `'closed-by-host'` when a host closed it and recorded that its call
+ *   never ran (`closedProvenKey`).
+ */
+export declare function spendDecision(ledger: DecisionLedger, decision: CheckInDecision, gate: ConsentGateKind, signal?: AbortSignal): Promise<void>;
+/**
+ * What an aborted run ended with — the signal's own reason, as the engine
+ * reports it — or `undefined` while the run goes on. Asked before the spend,
+ * after it, and by the dispatch loop once more at the last moment before an
+ * approved call runs (`toolCalls.ts` · `resolveCredentialAndExecute`): the
+ * engine stops waiting on an aborted run's stage, but the stage goes on, and
+ * nothing may run for a caller who was already told the run ended.
+ */
+export declare function runEndedBy(signal: AbortSignal | undefined): Error | undefined;
+/**
+ * A resume of this library has taken up the request `requestId` names: from
+ * here every use of its decision passes through {@link spendDecision}, where a
+ * watch sees it. Called by every runner's resume (`RunnerBase` ·
+ * `emitPauseResume`, and `Agent.resume` before its first check) and by the
+ * dispatch loop where it takes the decision up.
+ */
+export declare function noteDecisionTakenUp(requestId: string | undefined): void;
+/** What a door that keeps a pause learns, for one resume, about its request ({@link watchDecisionUse}). */
+export interface DecisionUseWatch {
+    /**
+     * Whether the request's decision may have been used while watched — by
+     * this resume, or by any other in this process:
+     *
+     *  - taken to a ledger that spent it, refused it (an earlier resume had)
+     *    or has not answered yet → `true`;
+     *  - taken to a ledger whose spend failed → asked again of that ledger
+     *    (`DecisionLedger.isSpent`): `false` there means the spend never landed;
+     *    no answer, a throw, or a ledger that cannot be asked → `true`;
+     *  - never taken to a ledger, by a resume this library took up → `false`;
+     *  - never taken up by this library at all → `true`: that cannot be told
+     *    apart from a use.
+     */
+    mayHaveBeenUsed(): Promise<boolean>;
+    /**
+     * Whether a ledger SPENT the request for a decline while watched, and no
+     * approval of it was taken to a ledger meanwhile: the decline won the
+     * ledger, so no approval can have run the call there. Only then does a door
+     * record the paused call as declined. A decline the ledger refused (an
+     * earlier resume — an approval, perhaps in another process — had spent the
+     * request) is not one: that call may have run.
+     */
+    spentAsDecline(): boolean;
+    /** Stop watching. A door releases its watch once it has decided. */
+    release(): void;
+}
+/**
+ * Watch the request `requestId` names for the length of one resume — opened
+ * by a door that keeps the pause, before it hands the decision over, and
+ * released once it has decided what a failure means for the stored pause.
+ * Keyed by the request, never by the decision object a door may copy or wrap.
+ */
+export declare function watchDecisionUse(requestId: string): DecisionUseWatch;
+/** The id of the request a paused run's state records (`pausedRequest`), or `undefined`. */
+export declare function recordedRequestId(recorded: unknown): string | undefined;
+/**
+ * The id of the call a checkpoint's paused stage records as paused
+ * (`pausedToolCallId`), or `undefined` — never a throw, whatever the
+ * checkpoint holds.
+ */
+export declare function pausedCallIdOf(checkpoint: FlowchartCheckpoint): string | undefined;
+/**
+ * The identity of the ledger the request a checkpoint's paused stage records
+ * was minted under ({@link PendingRequest.ledger}), or `undefined` — never a
+ * throw, whatever the checkpoint holds.
+ */
+export declare function pausedRequestLedgerOf(checkpoint: FlowchartCheckpoint): string | undefined;
+/**
+ * The id of the request a checkpoint's paused stage records, or `undefined`
+ * — never a throw, whatever the checkpoint holds.
+ */
+export declare function pausedRequestIdOf(checkpoint: FlowchartCheckpoint): string | undefined;