agentfootprint 7.18.0 → 7.19.0

package/dist/esm/hosting/standingAgent.js

@@ -5,17 +5,26 @@
  *     agent,
  *     sessions: memorySessions(),
  *     host: nodeHost({ port: 8080 }),
+ *     durability: 'sync',          // optional; 'exit' is the default
  *   });
  *
  * One request at a time it does four things: wake and hydrate the session,
- * resume that conversation or start a fresh one, persist what the run leaves
+ * continue that session or start a fresh one, persist what the run leaves
  * behind, then reply. Everything else is somebody else's job — the host carries
  * bytes, the store keeps them, the agent thinks.
  *
- * ── Resuming is a REPLAY, and that has a cost you must know about ────────────
- * A stored conversation is restored through `agent.resumeOnError(...)`, and
- * this is its caveat, stated here in the words the Agent states it in, because
- * a composition that hides the caveat of the thing it composes is worse than no
+ * ── A run has three ends, and this composer honours all three ────────────────
+ * It answered, it asked a person something, or it failed. An answer completes
+ * the reply and stores a conversation. A QUESTION stores the paused run as
+ * `'flowchart-v1'` and leaves through `reply.awaiting(...)` — its own terminal,
+ * never `fail`, because a pause is unfinished work and reporting it as a failure
+ * tells every dashboard downstream something untrue. A later request for that
+ * session carrying `decision` continues the run from exactly where it stopped.
+ *
+ * ── Resuming a CONVERSATION is a REPLAY, and that has a cost ─────────────────
+ * A stored conversation is restored through `agent.resumeOnError(...)`, and this
+ * is its caveat, stated here in the words the Agent states it in, because a
+ * composition that hides the caveat of the thing it composes is worse than no
  * composition at all:
  *
  *   > **Tool re-execution / idempotency**: tool side effects from the FAILED
@@ -25,6 +34,10 @@
  *   > emails, DB writes) must be idempotent — key on stable call content, not
  *   > `ctx.toolCallId` (a re-issued call gets a new id).
  *
+ * `durability` is the dial that bounds how much of that a crash can cost you.
+ * Resuming a PAUSED run is different in kind: it is not a replay at all — the
+ * engine continues from its own checkpoint, and no earlier tool call re-runs.
+ *
  * ── Why one run at a time ───────────────────────────────────────────────────
  * An Agent instance holds per-run state on itself, and this composer shares ONE
  * instance across every session. Two runs overlapping on it do not crash —
@@ -43,14 +56,16 @@
  * mechanism of its own.
  */
 import { isPaused } from '../core/pause.js';
-import { toEnvelope, readEnvelope } from './envelope.js';
-import { ConcurrentRunError, PauseNotCarriedError } from './errors.js';
+import { durableWriter } from './durability.js';
+import { readEnvelope, readPausedRun, toEnvelope, toPausedEnvelope } from './envelope.js';
+import { AwaitingDecisionError, ConcurrentRunError, NoPendingAskError, PauseNotCarriedError, } from './errors.js';
 /**
  * Serve one agent, with per-session conversation memory, on any
  * {@link AgentHost}.
  *
- * Resolves once the host is live. Closing the returned handle closes the host
- * and detaches the listeners this composer added to the agent.
+ * Resolves once the host is live. Closing the returned handle closes the host,
+ * detaches the listeners this composer added to the agent, and removes its
+ * durability wiring.
  *
  * @example
  *   const handle = await standingAgent({
@@ -58,17 +73,21 @@ import { ConcurrentRunError, PauseNotCarriedError } from './errors.js';
  *     sessions: memorySessions(),
  *     host: nodeHost({ port: 0 }),
  *     onConcurrentInvoke: 'enqueue',
+ *     durability: 'sync',
  *   });
  *   process.on('SIGTERM', () => void handle.close());
  */
 export async function standingAgent(options) {
     const { agent, sessions, host } = options;
     const policy = options.onConcurrentInvoke ?? 'reject';
+    const durability = options.durability ?? 'exit';
     // Runs are serialized, so at any moment there is at most one active reply and
     // at most one active run to name in a refusal.
     let activeReply;
     let activeRunId;
     let activeSession;
+    /** The REAL session id of the active run — never the anonymous placeholder. */
+    let activeSessionId;
     const queued = [];
     let chain = Promise.resolve();
     let anonymous = 0;
@@ -82,6 +101,19 @@ export async function standingAgent(options) {
         if (typeof content === 'string' && content.length > 0)
             activeReply?.emit?.(content);
     });
+    // Under 'exit' NOTHING is built: no observer on the agent, no barrier, no
+    // per-commit work. That is what "the default is byte-identical" means here —
+    // not a mode that happens to write once, but wiring that is never installed.
+    const writer = durability === 'exit'
+        ? undefined
+        : durableWriter({
+            mode: durability,
+            session: () => activeSessionId,
+            runId: () => activeRunId,
+            write: (sessionId, conversation) => sessions.persist(sessionId, toEnvelope(conversation)),
+        });
+    const detachWriter = writer ? agent.attach(writer.recorder) : undefined;
+    const uninstallBarrier = writer?.install(agent);
     /** Queue `work` behind everything already waiting, FIFO. */
     function serialize(sessionKey, work) {
         if (policy === 'reject' && (activeSession === sessionKey || queued.includes(sessionKey))) {
@@ -119,40 +151,101 @@ export async function standingAgent(options) {
     };
     async function answerOne(runner, store, request, reply, sessionId) {
         activeReply = reply;
+        // The writer only ever writes for the run it is inside; an anonymous
+        // request has nowhere to write to and gets nothing.
+        activeSessionId = sessionId;
         try {
             let prior;
+            let paused;
             if (sessionId !== undefined) {
-                await store.onWake?.(sessionId, 'invoke');
+                // A request carrying a decision is waking this session to CONTINUE a
+                // run, which is a different thing to ask a store to be ready for.
+                await store.onWake?.(sessionId, request.decision !== undefined ? 'resume' : 'invoke');
                 const stored = await store.hydrate(sessionId);
-                // Throws by name on a format this runtime cannot read — better a loud
-                // refusal than an agent answering from half a conversation.
-                if (stored !== undefined)
-                    prior = readEnvelope(stored);
+                if (stored !== undefined) {
+                    // Both readers throw by name on a format this runtime cannot read —
+                    // better a loud refusal than an agent answering from half a session.
+                    if (stored.format === 'flowchart-v1')
+                        paused = readPausedRun(stored);
+                    else
+                        prior = readEnvelope(stored);
+                }
             }
             // The signal reaches tool execution, tool discovery and skill-entry
             // scoring. It does NOT currently reach the LLM call, so a caller who
             // hangs up mid-generation stops the tools, not the token stream.
             const runOptions = request.signal ? { env: { signal: request.signal } } : undefined;
-            const output = prior
-                ? await runner.resumeOnError(continueConversation(prior, request.input), runOptions)
-                : await runner.run({ message: request.input }, runOptions);
-            if (isPaused(output)) {
-                reply.fail(new PauseNotCarriedError(pausedToolName(runner), sessionId));
+            // ── The one discriminant ─────────────────────────────────────────
+            // A request carrying `decision` answers a pending question; a request
+            // without one is a new message. Never inferred from the text: reading
+            // approval out of prose is a guess, and a consent gate may not be built
+            // on a guess.
+            if (request.decision !== undefined) {
+                if (!paused) {
+                    reply.fail(new NoPendingAskError(sessionId ?? '(anonymous)'));
+                    return;
+                }
+                await deliver(await runner.resume(paused.checkpoint, request.decision, runOptions), runner, store, reply, sessionId);
                 return;
             }
-            if (sessionId !== undefined) {
-                const conversation = runner.checkpoint();
-                // Persist BEFORE answering: the caller learns the answer only once the
-                // conversation that produced it is durable, so a queued next turn can
-                // never read state older than the answer already given.
-                if (conversation)
-                    await store.persist(sessionId, toEnvelope(conversation));
+            if (paused && sessionId !== undefined) {
+                // The message is not run and the pause is not discarded. Both of the
+                // other options lose something a person cared about.
+                reply.fail(new AwaitingDecisionError(sessionId, paused.pending));
+                return;
             }
-            reply.complete(typeof output === 'string' ? output : String(output));
+            const output = prior
+                ? await runner.resumeOnError(continueConversation(prior, request.input), runOptions)
+                : await runner.run({ message: request.input }, runOptions);
+            await deliver(output, runner, store, reply, sessionId);
+        }
+        catch (err) {
+            // A run that threw still has to drain. A write left in flight would race
+            // the NEXT turn's terminal write and could land after it. The drain's own
+            // failure is swallowed here and only here: the caller is already being
+            // told about the run's error, and replacing it with a storage error would
+            // hide the thing that actually went wrong.
+            await writer?.settle().catch(() => undefined);
+            throw err;
         }
         finally {
             activeReply = undefined;
+            activeSessionId = undefined;
+        }
+    }
+    /** Store what the run left behind, then end the reply with the right terminal. */
+    async function deliver(output, runner, store, reply, sessionId) {
+        // Mid-run writes settle FIRST. Ordering, not tidiness: an 'async' write
+        // still in flight would otherwise land after the terminal envelope and
+        // overwrite it — a stored pause quietly demoted back to a conversation,
+        // and the question a person was asked gone with it. It also rethrows a
+        // store that refused this run's progress, so a broken store fails the
+        // request rather than being reported as a clean answer.
+        await writer?.settle();
+        if (isPaused(output)) {
+            const pending = describePause(output, sessionId);
+            const conversation = sessionId === undefined ? undefined : runner.checkpoint();
+            if (sessionId !== undefined && conversation) {
+                await store.persist(sessionId, toPausedEnvelope({ checkpoint: output.checkpoint, conversation, pending }));
+                if (reply.awaiting) {
+                    reply.awaiting(pending);
+                    return;
+                }
+            }
+            // Either there was nowhere to store it, or the host cannot describe a
+            // question. Both are refusals about THIS reply, not about the run.
+            reply.fail(new PauseNotCarriedError(pending.tool, sessionId, conversation !== undefined));
+            return;
+        }
+        if (sessionId !== undefined) {
+            const conversation = runner.checkpoint();
+            // Persist BEFORE answering: the caller learns the answer only once the
+            // conversation that produced it is durable, so a queued next turn can
+            // never read state older than the answer already given.
+            if (conversation)
+                await store.persist(sessionId, toEnvelope(conversation));
         }
+        reply.complete(typeof output === 'string' ? output : String(output));
     }
     const handle = await host.serve(handler);
     // Keep whatever the adapter put on its own handle (nodeHost's bound `url`,
@@ -165,6 +258,8 @@ export async function standingAgent(options) {
             await handle.close();
             offTurnStart();
             offToken();
+            uninstallBarrier?.();
+            detachWriter?.();
         },
     };
 }
@@ -183,10 +278,27 @@ function continueConversation(prior, input) {
         checkpointedAt: Date.now(),
     };
 }
-/** Which tool asked for a human, when the paused run recorded one. */
-function pausedToolName(runner) {
-    const state = runner.getLastSnapshot()?.sharedState;
-    const name = state?.pausedToolName;
-    return typeof name === 'string' && name.length > 0 ? name : undefined;
+/**
+ * Project a paused run into the part that is safe to hand back: the question,
+ * never the state.
+ *
+ * Every field is read from what the run actually recorded — the tool name and
+ * question the dispatch loop stamps on `pauseData`, the typed `checkIn`, the
+ * middleware `ask`. A field the run did not record is simply absent. Nothing
+ * here infers, summarises or invents, which is why the raw `pauseData` rides
+ * along untouched: the tool's author chose those words.
+ */
+function describePause(outcome, sessionId) {
+    const data = outcome.pauseData;
+    const tool = typeof data?.toolName === 'string' ? data.toolName : undefined;
+    const question = typeof data?.question === 'string' ? data.question : undefined;
+    return {
+        ...(sessionId !== undefined && { sessionId }),
+        ...(tool !== undefined && { tool }),
+        ...(question !== undefined && { question }),
+        ...(outcome.checkIn !== undefined && { checkIn: outcome.checkIn }),
+        ...(outcome.ask !== undefined && { ask: outcome.ask }),
+        pauseData: outcome.pauseData,
+    };
 }
 //# sourceMappingURL=standingAgent.js.map

package/dist/esm/hosting/standingAgent.js.map

@@ -1 +1 @@
-{"version":3,"file":"standingAgent.js","sourceRoot":"","sources":["../../../src/hosting/standingAgent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"standingAgent.js","sourceRoot":"","sources":["../../../src/hosting/standingAgent.ts"],"names":[],"mappings":"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"}

package/dist/esm/hosting/types.d.ts

@@ -17,7 +17,10 @@
  *
  * Pattern: Ports & adapters (hexagonal). Role: the port side, exclusively.
  */
+import type { FlowchartCheckpoint } from 'footprintjs';
 import type { Agent } from '../core/Agent.js';
+import type { CheckInRequest } from '../core/checkin.js';
+import type { MiddlewareAsk } from '../core/pause.js';
 import type { AgentRunCheckpoint } from '../core/runCheckpoint.js';
 /**
  * Something a host can do BEYOND the baseline of "accept a request, deliver one
@@ -37,6 +40,24 @@ export type HostCapability = 'streaming';
 export interface HostRequest {
     /** What the caller is asking. */
     readonly input: string;
+    /**
+     * A person's answer to an outstanding {@link PendingAsk} — and **the one
+     * thing that distinguishes a resume from a new message.**
+     *
+     * Present ⇒ this request answers the run that paused on this session. Absent
+     * ⇒ this request is a new message. That is the whole contract, and it is a
+     * FIELD rather than an inference on purpose: reading approval out of prose
+     * ("yes, go ahead") is a guess, and a guess is not something a consent gate
+     * may be built on.
+     *
+     * The port never interprets it. It is handed to `agent.resume(checkpoint,
+     * decision)` exactly as it arrived — a {@link CheckInRequest} or a middleware
+     * `ask` is answered with the shipped `checkInApproved()` / `checkInDeclined()`
+     * vocabulary; a plain `askHuman` pause is answered with whatever that tool's
+     * author documented. Typed `unknown` because the library does not get to
+     * decide what a tool asked for.
+     */
+    readonly decision?: unknown;
     /**
      * The conversation this request CLAIMS to belong to — caller data, exactly as
      * the transport declared it (a JSON field, a header, a path segment).
@@ -57,13 +78,37 @@ export interface HostRequest {
     readonly signal?: AbortSignal;
 }
 /**
- * The one reply a request gets. Exactly one of {@link HostReply.complete} or
- * {@link HostReply.fail} ends it; a second call is ignored rather than allowed
- * to corrupt the wire.
+ * The one reply a request gets. Exactly one of {@link HostReply.complete},
+ * {@link HostReply.awaiting} or {@link HostReply.fail} ends it; a second call is
+ * ignored rather than allowed to corrupt the wire.
+ *
+ * Three terminals, because a run has three ends and only three: it answered, it
+ * stopped to ask a person something, or it failed. Before `'flowchart-v1'` there
+ * was nowhere to keep a paused run, so the middle one was delivered through
+ * `fail` — an error standing in for unfinished work. It is a terminal of its own
+ * now, and a pause is never reported as a failure again.
  */
 export interface HostReply {
     /** Deliver the final answer and end the reply. */
     complete(output: string): void;
+    /**
+     * End the reply with **unfinished work**: the run stopped to ask a person
+     * something, the paused run is stored, and a later request carrying
+     * {@link HostRequest.decision} continues it.
+     *
+     * This is not a failure and must not be reported as one. The agent did not
+     * break, no work was lost, and there is nothing to retry — there is a question
+     * outstanding. An adapter that maps this onto a 5xx, an error counter or a
+     * dead-letter queue is telling every dashboard it feeds something that is not
+     * true.
+     *
+     * Optional on the TYPE for the same reason {@link HostReply.emit} is: a
+     * minimal adapter need not implement it. Every shipped adapter does. When it
+     * is absent the composer still STORES the paused run — the store is not the
+     * transport's business — and ends the reply with a named refusal instead, so
+     * the pause is never lost merely because the wire could not describe it.
+     */
+    awaiting?(pending: PendingAsk): void;
     /**
      * A piece of the answer, as it is produced.
      *
@@ -114,37 +159,156 @@ export interface AgentHost {
     serve(handler: HostHandler): Promise<HostHandle>;
 }
 /**
- * A conversation packed for storage.
+ * A session packed for storage.
  *
  * `format` names WHAT is inside, so a reader that does not know the shape
- * refuses BY NAME instead of restoring a conversation it cannot actually read.
+ * refuses BY NAME instead of restoring a session it cannot actually read.
  * Formats are ADDED, never redefined: an old runtime meeting a new format says
  * so and stops, which is the only safe thing it can do with a payload it cannot
- * interpret.
- *
- * `'conversation-v1'` stores a conversation and only a conversation. A run that
- * paused mid-flow is a conversation PLUS an engine checkpoint, and this format
- * has nowhere to put the second half — which is why `standingAgent` refuses to
- * store a paused run rather than storing half of it. Carrying a pause would be
- * a NEW format name in this same envelope, read by a runtime that knows it and
- * refused by name everywhere else. That is what the version field is for.
+ * interpret. Two exist:
+ *
+ *   • `'conversation-v1'` — a conversation and only a conversation. Every turn
+ *     that ran to an answer stores this.
+ *   • `'flowchart-v1'` — a run that stopped mid-flow to ask a person something:
+ *     the engine's own checkpoint, the conversation as of the pause, and the
+ *     outstanding ask. 7.14 shipped the version field for exactly this day, and
+ *     said so; this is that day.
+ *
+ * The union is discriminated on `format`, so a reader that switches on it is
+ * exhaustive by construction and a third format tomorrow breaks the switch at
+ * compile time rather than at 3am.
  */
-export interface CheckpointEnvelope {
+export type CheckpointEnvelope = ConversationEnvelope | PausedRunEnvelope;
+/** A conversation packed for storage — what a turn that ANSWERED leaves behind. */
+export interface ConversationEnvelope {
     /** Names the shape of `data`. Unknown values are refused, never guessed at. */
     readonly format: 'conversation-v1';
-    /** The conversation itself — an `AgentRunCheckpoint` for `'conversation-v1'`. */
+    /** The conversation itself. */
     readonly data: AgentRunCheckpoint;
     /** Wall-clock when it was packed. Diagnostic. */
     readonly savedAt: number;
 }
+/** A paused run packed for storage — what a turn that ASKED leaves behind. */
+export interface PausedRunEnvelope {
+    /** Names the shape of `data`. Unknown values are refused, never guessed at. */
+    readonly format: 'flowchart-v1';
+    /** The paused run. */
+    readonly data: PausedRun;
+    /** Wall-clock when it was packed. Diagnostic. */
+    readonly savedAt: number;
+}
+/**
+ * A run that stopped to ask a person something, in the three pieces a session
+ * actually needs: what continues it, what it has said so far, and what it is
+ * waiting on.
+ *
+ * ── JSON, honestly ───────────────────────────────────────────────────────────
+ * A `FlowchartCheckpoint` is **JSON-safe to resume from, and not byte-identical
+ * through JSON.** `JSON.stringify` drops any property whose value is
+ * `undefined`, and a real paused agent run has a dozen of them. Every one
+ * measured sits in `executionTree` / `subflowResults` — the diagnostic halves
+ * the engine keeps for narrative and BTS. `sharedState`, which is the half
+ * `agent.resume()` actually reads, round-trips unchanged, because footprintjs's
+ * TypedScope already JSON-round-trips every object write on its way into
+ * committed state.
+ *
+ * So: store it anywhere that speaks JSON and resume works. Do not assert that
+ * what came back deep-equals what went in — `key: undefined` comes back as no
+ * key at all, and a test written to expect otherwise is testing `JSON`, not
+ * this library.
+ */
+export interface PausedRun {
+    /** The engine checkpoint — everything `agent.resume(checkpoint, decision)` needs. */
+    readonly checkpoint: FlowchartCheckpoint;
+    /**
+     * The conversation as of the pause, in the same shape every other turn stores.
+     *
+     * Kept alongside the checkpoint so a session that is waiting on a person is
+     * still a readable conversation: a support view can show what was said, and a
+     * runtime that cannot resume this run can still see the turn that led to the
+     * question.
+     */
+    readonly conversation: AgentRunCheckpoint;
+    /** What the run is waiting on, as data. */
+    readonly pending: PendingAsk;
+}
+/**
+ * The question a paused run is waiting on — the part of a pause that is safe to
+ * hand to whoever asked.
+ *
+ * **It deliberately carries no checkpoint.** The engine checkpoint holds the
+ * entire shared state of the run: the system prompt, the whole conversation,
+ * every tool result. That belongs in the store, which the operator chose and
+ * controls, and not in a reply to whoever posted the request. The caller gets
+ * the question; the store gets the state.
+ */
+export interface PendingAsk {
+    /** The session holding the paused run — where the decision has to be sent back. */
+    readonly sessionId?: string;
+    /** The tool that asked, when the run recorded which one it was. */
+    readonly tool?: string;
+    /** The question in plain words, when the pause carried one. */
+    readonly question?: string;
+    /**
+     * Present ONLY when a tool declared `checkIn` — the typed ask plus its
+     * evidence pack (what the tool will do, what context the run read, which
+     * context drove the choice, the run so far). Answer with `checkInApproved()`
+     * / `checkInDeclined()`.
+     */
+    readonly checkIn?: CheckInRequest;
+    /**
+     * Present ONLY when a `toolMiddleware` answered `ask` — the question and the
+     * middleware that put it. Answered with the same decision vocabulary a
+     * check-in uses, deliberately: a person approving is a person approving.
+     */
+    readonly ask?: MiddlewareAsk;
+    /**
+     * Exactly what the tool passed to `askHuman()` / `pauseHere()`, uninterpreted.
+     * For a plain pause this is the whole of what the tool's author chose to say,
+     * and the library is not entitled to summarise it.
+     */
+    readonly pauseData: unknown;
+}
+/**
+ * How often a run's progress is written to the session store — the trade
+ * between latency and how much a crash can cost you.
+ *
+ *  - `'exit'` (default) — one write, when the run finishes. The behaviour every
+ *    release before 7.19 had, spelled out rather than implied. A crash mid-run
+ *    loses the whole turn.
+ *  - `'async'` — a write is STARTED whenever the conversation changes and never
+ *    waited on. The run never slows down; the store is behind by however much
+ *    the newest un-landed write carried. At most one write is in flight and the
+ *    newest snapshot supersedes any queued one, so what a crash leaves is always
+ *    a PREFIX of the run, never a mixture.
+ *  - `'sync'` — persist-then-proceed. The same trigger, but **iteration N's
+ *    tools do not execute until iteration N-1's write has landed**, and the
+ *    answer is not delivered until the last write has landed. You pay the
+ *    store's latency once per iteration, knowingly, and in exchange the amount
+ *    of work a crash can re-run has a number: **the current iteration, and
+ *    nothing before it.**
+ *
+ * ── The bound, stated exactly ────────────────────────────────────────────────
+ * A commit boundary is a whole stage, and the agent dispatches ALL of one
+ * iteration's tool calls inside one stage body. So under `'sync'` a crash
+ * re-executes the tools of the iteration that was in flight — never an earlier
+ * one. That is the same idempotency requirement `resumeOnError` has always
+ * carried, now with a boundary instead of a warning: mutating tools must be
+ * idempotent, keyed on stable call content rather than `ctx.toolCallId`.
+ */
+export type DurabilityMode = 'exit' | 'async' | 'sync';
 /**
  * Why a session is being woken.
  *
- * One member, because one thing in this release can actually fire it: a request
- * arrived for that session. Naming reasons nothing can produce would be an
- * interface describing a system that does not exist.
+ *  - `'invoke'` — a request arrived for that session.
+ *  - `'resume'` — that request carries a person's decision for a run which
+ *    paused earlier.
+ *
+ * `'resume'` was absent until 7.19 because nothing could produce it: naming
+ * reasons nothing fires would be an interface describing a system that does not
+ * exist. Something produces it now.
  */
-export type WakeReason = 'invoke';
+export type WakeReason = 'invoke' | 'resume';
 /**
  * The port: where a conversation lives between requests.
  *
@@ -203,4 +367,14 @@ export interface StandingAgentOptions<TH extends HostHandle = HostHandle> {
     };
     /** Default `'reject'`. See {@link ConcurrentInvokePolicy}. */
     readonly onConcurrentInvoke?: ConcurrentInvokePolicy;
+    /**
+     * How often a run's progress becomes crash-survivable. Default `'exit'` —
+     * one write when the run finishes, which is what every release before this
+     * one did. See {@link DurabilityMode} for what the other two buy and cost.
+     *
+     * Under `'exit'` nothing is attached to the agent at all: no observer, no
+     * per-commit work, no barrier. An agent served this way behaves and performs
+     * exactly as it did in 7.18.
+     */
+    readonly durability?: DurabilityMode;
 }