agentfootprint 7.18.0 → 7.19.0

package/dist/esm/hosting/durability.js

@@ -0,0 +1,174 @@
+/**
+ * hosting/durability — how often a run's progress becomes crash-survivable.
+ *
+ * A standing agent that only writes at the end of a turn is one restart away
+ * from losing everything the turn had done: the tool calls it made, the results
+ * it read, the iterations it spent. This is the dial that decides how much of
+ * that survives, and what it costs.
+ *
+ * ── Where a mid-run write can honestly come from ─────────────────────────────
+ * From the COMMIT boundary, and nowhere else. footprintjs commits a stage's
+ * writes after the stage function returns, and committed state is
+ * immutable-after-swap — so `ScopeRecorder.onCommit` is the one moment where
+ * "what the run has agreed on so far" is a real, complete, consistent thing.
+ * Reading the agent's live state at any other moment would be reading a stage's
+ * work in progress.
+ *
+ * There is no mid-run engine checkpoint to store: footprintjs builds a
+ * `FlowchartCheckpoint` only at a pause (`getCheckpoint()` is documented as "the
+ * most recent PAUSED execution"). So what a mid-run write can carry is a
+ * CONVERSATION — the same `AgentRunCheckpoint` every finished turn stores — and
+ * that is exactly enough, because that is what the next turn resumes from.
+ *
+ * ── Why it writes on SOME commits and not all of them ────────────────────────
+ * A two-iteration turn commits about forty times. Exactly two of those commits
+ * change the conversation: `Initialize` (the user's message lands) and
+ * `ToolCalls` (an iteration's assistant turn and its tool results land). Every
+ * other commit would store bytes identical to the last write. So the trigger is
+ * "this commit wrote `history`", which is not an optimisation but the honest
+ * reading of the question: the conversation moved iff `history` moved.
+ *
+ * ── What a commit boundary actually guarantees, and what it does not ─────────
+ * It guarantees the whole stage. The agent dispatches ALL of one iteration's
+ * tool calls inside one stage body, so a crash part-way through that body stores
+ * nothing from it and a replay re-runs that iteration's tools. That is the
+ * shipped idempotency requirement, unchanged — mutating tools must be
+ * idempotent, keyed on stable call content rather than `ctx.toolCallId`. What
+ * `'sync'` adds is a BOUND on it: iteration N's tools do not start until
+ * iteration N-1's write has landed, so the replay is the current iteration and
+ * never an earlier one.
+ *
+ * Pattern: an observer (`CombinedRecorder`) for the snapshot, a serialiser for
+ * the writes, and — for `'sync'` only — a barrier the tool dispatch waits on.
+ * Role: internal to `standingAgent`. Deliberately not exported: it is how the
+ * composer keeps its promise, not a second way to write to a store.
+ */
+import { installDurabilityBarrier } from '../core/durabilityBarrier.js';
+/**
+ * Build the writer.
+ *
+ * Under `'sync'` it also answers the tool-dispatch barrier, which is what turns
+ * "we write often" into a bound on how much can re-run.
+ */
+export function durableWriter(options) {
+    const { mode, session, runId, write } = options;
+    /** The write currently on the wire, or `undefined` when nothing is. */
+    let inFlight;
+    /**
+     * The newest snapshot that has not been started yet. At most ONE, and a newer
+     * one replaces it: the conversation only grows, so a superseded snapshot is a
+     * prefix of the one replacing it and writing it first would buy nothing.
+     */
+    let queued;
+    /**
+     * Why the NEWEST write did not land, or `undefined` when it did. Cleared by a
+     * write that succeeds — a store that failed once and then took the newer
+     * state has made that state durable, and reporting the older failure would be
+     * describing a problem that no longer exists.
+     */
+    let failure;
+    /** Per-run accumulation, rebuilt from the commits themselves. */
+    let history = [];
+    let userMessage = '';
+    let iteration = 0;
+    function pump() {
+        if (inFlight !== undefined || queued === undefined)
+            return;
+        const next = queued;
+        queued = undefined;
+        inFlight = write(next.sessionId, next.conversation)
+            .then(() => {
+            failure = undefined;
+        }, (err) => {
+            failure = new Error(`[hosting] the session store did not accept this run's progress, so nothing ` +
+                `after this point may proceed as if it had` +
+                (mode === 'sync' ? ` — the next tool call was not allowed to run` : '') +
+                `. Underlying error: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+        })
+            .then(() => {
+            inFlight = undefined;
+            pump();
+        });
+    }
+    function enqueue(sessionId) {
+        queued = {
+            sessionId,
+            conversation: {
+                version: 1,
+                runId: runId() ?? 'unknown',
+                // The commit event hands over the stage's retained write view. Clone on
+                // the way to a store so nothing a persistence layer does can reach back
+                // into the run's own snapshot.
+                history: structuredClone(history),
+                lastCompletedIteration: iteration,
+                originalInput: { message: userMessage },
+                checkpointedAt: Date.now(),
+            },
+        };
+        pump();
+    }
+    const recorder = {
+        id: 'af-hosting-durability',
+        // INLINE, always. A write delivered one beat behind is a write that can be
+        // lost by the very crash it exists to survive — and under `'sync'` the
+        // barrier would be waiting on a snapshot the queue had not handed over yet.
+        // The causal-evidence bridge and the compaction meter are inline for the
+        // same class of reason.
+        delivery: 'inline',
+        onCommit(event) {
+            let conversationMoved = false;
+            for (const mutation of event.mutations) {
+                if (mutation.key === 'history' && Array.isArray(mutation.value)) {
+                    history = mutation.value;
+                    conversationMoved = true;
+                }
+                else if (mutation.key === 'userMessage' && typeof mutation.value === 'string') {
+                    userMessage = mutation.value;
+                }
+                else if (mutation.key === 'iteration' && typeof mutation.value === 'number') {
+                    iteration = mutation.value;
+                }
+            }
+            if (!conversationMoved)
+                return;
+            const sessionId = session();
+            if (sessionId === undefined)
+                return;
+            enqueue(sessionId);
+        },
+        // A fresh run starts from a fresh conversation. Without this a resumed run
+        // whose first commit has not landed yet could stamp the previous run's
+        // history onto this run's id.
+        clear() {
+            history = [];
+            userMessage = '';
+            iteration = 0;
+        },
+    };
+    const settle = async () => {
+        // Loop rather than await once: a write that completes may release a queued
+        // successor, and "settled" has to mean nothing is left.
+        while (inFlight !== undefined || queued !== undefined) {
+            pump();
+            await inFlight;
+        }
+        if (failure)
+            throw failure;
+    };
+    return {
+        recorder,
+        install(agent) {
+            // `'async'` deliberately takes NO barrier: its whole promise is that the
+            // run does not wait, and a barrier would be that promise broken quietly.
+            if (mode !== 'sync')
+                return () => undefined;
+            return installDurabilityBarrier(agent, () => {
+                if (inFlight === undefined && queued === undefined && failure === undefined)
+                    return undefined;
+                return settle();
+            });
+        },
+        settle,
+    };
+}
+//# sourceMappingURL=durability.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"durability.js","sourceRoot":"","sources":["../../../src/hosting/durability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AA4CxE;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAEhD,uEAAuE;IACvE,IAAI,QAAmC,CAAC;IACxC;;;;OAIG;IACH,IAAI,MAA2E,CAAC;IAChF;;;;;OAKG;IACH,IAAI,OAA0B,CAAC;IAE/B,iEAAiE;IACjE,IAAI,OAAO,GAA0B,EAAE,CAAC;IACxC,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,SAAS,IAAI;QACX,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QAC3D,MAAM,IAAI,GAAG,MAAM,CAAC;QACpB,MAAM,GAAG,SAAS,CAAC;QACnB,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC;aAChD,IAAI,CACH,GAAG,EAAE;YACH,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;YACf,OAAO,GAAG,IAAI,KAAK,CACjB,6EAA6E;gBAC3E,2CAA2C;gBAC3C,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,8CAA8C,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvE,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAC3E,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;QACJ,CAAC,CACF;aACA,IAAI,CAAC,GAAG,EAAE;YACT,QAAQ,GAAG,SAAS,CAAC;YACrB,IAAI,EAAE,CAAC;QACT,CAAC,CAAC,CAAC;IACP,CAAC;IAED,SAAS,OAAO,CAAC,SAAiB;QAChC,MAAM,GAAG;YACP,SAAS;YACT,YAAY,EAAE;gBACZ,OAAO,EAAE,CAAC;gBACV,KAAK,EAAE,KAAK,EAAE,IAAI,SAAS;gBAC3B,wEAAwE;gBACxE,wEAAwE;gBACxE,+BAA+B;gBAC/B,OAAO,EAAE,eAAe,CAAC,OAAO,CAAiB;gBACjD,sBAAsB,EAAE,SAAS;gBACjC,aAAa,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;gBACvC,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE;aAC3B;SACF,CAAC;QACF,IAAI,EAAE,CAAC;IACT,CAAC;IAED,MAAM,QAAQ,GAAqB;QACjC,EAAE,EAAE,uBAAuB;QAC3B,2EAA2E;QAC3E,uEAAuE;QACvE,4EAA4E;QAC5E,yEAAyE;QACzE,wBAAwB;QACxB,QAAQ,EAAE,QAAQ;QAElB,QAAQ,CAAC,KAAkB;YACzB,IAAI,iBAAiB,GAAG,KAAK,CAAC;YAC9B,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACvC,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;oBAChE,OAAO,GAAG,QAAQ,CAAC,KAA8B,CAAC;oBAClD,iBAAiB,GAAG,IAAI,CAAC;gBAC3B,CAAC;qBAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,aAAa,IAAI,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAChF,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC;gBAC/B,CAAC;qBAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,WAAW,IAAI,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9E,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC;gBAC7B,CAAC;YACH,CAAC;YACD,IAAI,CAAC,iBAAiB;gBAAE,OAAO;YAC/B,MAAM,SAAS,GAAG,OAAO,EAAE,CAAC;YAC5B,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO;YACpC,OAAO,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC;QAED,2EAA2E;QAC3E,uEAAuE;QACvE,8BAA8B;QAC9B,KAAK;YACH,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,GAAG,EAAE,CAAC;YACjB,SAAS,GAAG,CAAC,CAAC;QAChB,CAAC;KACF,CAAC;IAEF,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;QACvC,2EAA2E;QAC3E,wDAAwD;QACxD,OAAO,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACtD,IAAI,EAAE,CAAC;YACP,MAAM,QAAQ,CAAC;QACjB,CAAC;QACD,IAAI,OAAO;YAAE,MAAM,OAAO,CAAC;IAC7B,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ;QACR,OAAO,CAAC,KAAa;YACnB,yEAAyE;YACzE,yEAAyE;YACzE,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;YAC5C,OAAO,wBAAwB,CAAC,KAAK,EAAE,GAAG,EAAE;gBAC1C,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;oBACzE,OAAO,SAAS,CAAC;gBACnB,OAAO,MAAM,EAAE,CAAC;YAClB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM;KACP,CAAC;AACJ,CAAC"}

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

@@ -1,17 +1,27 @@
 /**
- * hosting/envelope — pack a conversation for storage, and refuse to unpack one
- * you cannot read.
- *
- * Two functions and one rule: **an unknown format is refused by name, never
- * guessed at.** A store outlives the code that wrote to it. Somebody will
- * deploy a newer runtime, it will write a newer format, and an older instance
- * still running will read it. The only honest thing that older instance can do
- * is say which format it found, which ones it knows, and stop — because
- * "restore what I can and hope" means an agent answering from a conversation
- * that is missing whatever the older reader did not understand.
+ * hosting/envelope — pack a session for storage, and refuse to unpack one you
+ * cannot read.
+ *
+ * One rule, and everything here is a consequence of it: **an envelope this
+ * runtime cannot read is refused BY NAME, never guessed at.** A store outlives
+ * the code that wrote to it. Somebody will deploy a newer runtime, it will write
+ * a newer format, and an older instance still running will read it. The only
+ * honest thing that older instance can do is say which format it found, which
+ * ones it knows, and stop — because "restore what I can and hope" means an agent
+ * answering from a session that is missing whatever the older reader did not
+ * understand.
+ *
+ * ── Two formats, two readers, and why they refuse each other ─────────────────
+ * `readEnvelope` unpacks a CONVERSATION; `readPausedRun` unpacks a PAUSED RUN.
+ * Each refuses the other's format by name and points at its sibling. That looks
+ * fussy until you notice the alternative: one reader that quietly returned the
+ * conversation inside a paused run would hand back a session that LOOKS finished
+ * while a person is still waiting on a question nobody mentioned. That is a
+ * half-restore wearing a happy path, which is the exact failure the format field
+ * exists to prevent.
  */
 import { type AgentRunCheckpoint } from '../core/runCheckpoint.js';
-import type { CheckpointEnvelope } from './types.js';
+import type { CheckpointEnvelope, ConversationEnvelope, PausedRun, PausedRunEnvelope } from './types.js';
 /**
  * Pack a conversation checkpoint for storage.
  *
@@ -19,7 +29,28 @@ import type { CheckpointEnvelope } from './types.js';
  *   const conversation = agent.checkpoint();
  *   if (conversation) await sessions.persist(sessionId, toEnvelope(conversation));
  */
-export declare function toEnvelope(checkpoint: AgentRunCheckpoint): CheckpointEnvelope;
+export declare function toEnvelope(checkpoint: AgentRunCheckpoint): ConversationEnvelope;
+/**
+ * Pack a paused run for storage — the engine checkpoint, the conversation as of
+ * the pause, and the question it is waiting on.
+ *
+ * Store it anywhere that speaks JSON. Note what JSON does and does not preserve
+ * here: `agent.resume()` reads `checkpoint.sharedState`, which round-trips
+ * unchanged; the engine's diagnostic halves lose their explicitly-`undefined`
+ * properties, because that is what `JSON.stringify` does to them. See
+ * {@link PausedRun}.
+ *
+ * @example
+ *   const outcome = await agent.run({ message });
+ *   if (isPaused(outcome)) {
+ *     await sessions.persist(sessionId, toPausedEnvelope({
+ *       checkpoint: outcome.checkpoint,
+ *       conversation: agent.checkpoint()!,
+ *       pending: { pauseData: outcome.pauseData },
+ *     }));
+ *   }
+ */
+export declare function toPausedEnvelope(paused: PausedRun): PausedRunEnvelope;
 /**
  * Unpack a stored envelope back into a conversation checkpoint.
  *
@@ -27,7 +58,37 @@ export declare function toEnvelope(checkpoint: AgentRunCheckpoint): CheckpointEn
  * else wrote, in a format this runtime may not know, and typing the parameter
  * as the happy shape would be assuming the very thing that needs checking.
  *
- * @throws TypeError naming the format when it is one this runtime cannot read,
- *   and naming the missing field when the conversation inside is malformed.
+ * @throws TypeError naming the format when it is one this runtime cannot read;
+ *   naming the missing field when the conversation inside is malformed; and
+ *   pointing at {@link readPausedRun} when the envelope holds a paused run,
+ *   which is a session with a question outstanding rather than a conversation.
  */
 export declare function readEnvelope(envelope: unknown): AgentRunCheckpoint;
+/**
+ * Unpack a stored envelope back into a paused run.
+ *
+ * @throws TypeError naming the format when it is one this runtime cannot read;
+ *   pointing at {@link readEnvelope} when the envelope holds a plain
+ *   conversation; and naming the missing field when the paused run inside is
+ *   malformed.
+ */
+export declare function readPausedRun(envelope: unknown): PausedRun;
+/**
+ * Check that an envelope is one this runtime can read, and hand it back
+ * unchanged — without committing to which half you wanted.
+ *
+ * This is what a STORE wants. A store's job is to notice that the bytes it is
+ * about to hand over are unreadable, so the refusal names the store that
+ * produced them rather than whoever read them next; it has no business caring
+ * whether the session inside is mid-conversation or mid-question.
+ *
+ * @throws TypeError naming the format when this runtime cannot read it, or the
+ *   missing field when the payload is malformed.
+ *
+ * @example
+ *   async hydrate(sessionId) {
+ *     const stored = await myStore.get(sessionId);
+ *     return stored === undefined ? undefined : checkEnvelope(stored);
+ *   }
+ */
+export declare function checkEnvelope(envelope: unknown): CheckpointEnvelope;

package/dist/esm/hosting/envelope.js

@@ -1,18 +1,28 @@
 /**
- * hosting/envelope — pack a conversation for storage, and refuse to unpack one
- * you cannot read.
+ * hosting/envelope — pack a session for storage, and refuse to unpack one you
+ * cannot read.
  *
- * Two functions and one rule: **an unknown format is refused by name, never
- * guessed at.** A store outlives the code that wrote to it. Somebody will
- * deploy a newer runtime, it will write a newer format, and an older instance
- * still running will read it. The only honest thing that older instance can do
- * is say which format it found, which ones it knows, and stop — because
- * "restore what I can and hope" means an agent answering from a conversation
- * that is missing whatever the older reader did not understand.
+ * One rule, and everything here is a consequence of it: **an envelope this
+ * runtime cannot read is refused BY NAME, never guessed at.** A store outlives
+ * the code that wrote to it. Somebody will deploy a newer runtime, it will write
+ * a newer format, and an older instance still running will read it. The only
+ * honest thing that older instance can do is say which format it found, which
+ * ones it knows, and stop — because "restore what I can and hope" means an agent
+ * answering from a session that is missing whatever the older reader did not
+ * understand.
+ *
+ * ── Two formats, two readers, and why they refuse each other ─────────────────
+ * `readEnvelope` unpacks a CONVERSATION; `readPausedRun` unpacks a PAUSED RUN.
+ * Each refuses the other's format by name and points at its sibling. That looks
+ * fussy until you notice the alternative: one reader that quietly returned the
+ * conversation inside a paused run would hand back a session that LOOKS finished
+ * while a person is still waiting on a question nobody mentioned. That is a
+ * half-restore wearing a happy path, which is the exact failure the format field
+ * exists to prevent.
  */
 import { validateCheckpoint } from '../core/runCheckpoint.js';
 /** Every format this runtime can read. Add, never redefine. */
-const KNOWN_FORMATS = ['conversation-v1'];
+const KNOWN_FORMATS = ['conversation-v1', 'flowchart-v1'];
 /**
  * Pack a conversation checkpoint for storage.
  *
@@ -23,6 +33,29 @@ const KNOWN_FORMATS = ['conversation-v1'];
 export function toEnvelope(checkpoint) {
     return { format: 'conversation-v1', data: checkpoint, savedAt: Date.now() };
 }
+/**
+ * Pack a paused run for storage — the engine checkpoint, the conversation as of
+ * the pause, and the question it is waiting on.
+ *
+ * Store it anywhere that speaks JSON. Note what JSON does and does not preserve
+ * here: `agent.resume()` reads `checkpoint.sharedState`, which round-trips
+ * unchanged; the engine's diagnostic halves lose their explicitly-`undefined`
+ * properties, because that is what `JSON.stringify` does to them. See
+ * {@link PausedRun}.
+ *
+ * @example
+ *   const outcome = await agent.run({ message });
+ *   if (isPaused(outcome)) {
+ *     await sessions.persist(sessionId, toPausedEnvelope({
+ *       checkpoint: outcome.checkpoint,
+ *       conversation: agent.checkpoint()!,
+ *       pending: { pauseData: outcome.pauseData },
+ *     }));
+ *   }
+ */
+export function toPausedEnvelope(paused) {
+    return { format: 'flowchart-v1', data: paused, savedAt: Date.now() };
+}
 /**
  * Unpack a stored envelope back into a conversation checkpoint.
  *
@@ -30,20 +63,112 @@ export function toEnvelope(checkpoint) {
  * else wrote, in a format this runtime may not know, and typing the parameter
  * as the happy shape would be assuming the very thing that needs checking.
  *
- * @throws TypeError naming the format when it is one this runtime cannot read,
- *   and naming the missing field when the conversation inside is malformed.
+ * @throws TypeError naming the format when it is one this runtime cannot read;
+ *   naming the missing field when the conversation inside is malformed; and
+ *   pointing at {@link readPausedRun} when the envelope holds a paused run,
+ *   which is a session with a question outstanding rather than a conversation.
  */
 export function readEnvelope(envelope) {
-    if (!envelope || typeof envelope !== 'object') {
-        throw new TypeError(`[hosting] stored session is not an envelope (got ${envelope === null ? 'null' : typeof envelope}). ` + `Expected { format, data, savedAt } as written by toEnvelope().`);
+    if (readFormat(envelope) === 'flowchart-v1') {
+        throw new TypeError(`[hosting] this envelope holds a PAUSED RUN ('flowchart-v1'), not a conversation. ` +
+            `Read it with readPausedRun(envelope) — it is waiting on a person's decision, and ` +
+            `handing back only the conversation inside it would restore a session that looks ` +
+            `finished while somebody is still waiting to be asked.`);
+    }
+    return validateCheckpoint(envelope.data);
+}
+/**
+ * Unpack a stored envelope back into a paused run.
+ *
+ * @throws TypeError naming the format when it is one this runtime cannot read;
+ *   pointing at {@link readEnvelope} when the envelope holds a plain
+ *   conversation; and naming the missing field when the paused run inside is
+ *   malformed.
+ */
+export function readPausedRun(envelope) {
+    if (readFormat(envelope) === 'conversation-v1') {
+        throw new TypeError(`[hosting] this envelope holds a conversation ('conversation-v1'), not a paused run. ` +
+            `Read it with readEnvelope(envelope). Nothing is waiting on a decision here.`);
+    }
+    return validatePausedRun(envelope.data);
+}
+/**
+ * Check that an envelope is one this runtime can read, and hand it back
+ * unchanged — without committing to which half you wanted.
+ *
+ * This is what a STORE wants. A store's job is to notice that the bytes it is
+ * about to hand over are unreadable, so the refusal names the store that
+ * produced them rather than whoever read them next; it has no business caring
+ * whether the session inside is mid-conversation or mid-question.
+ *
+ * @throws TypeError naming the format when this runtime cannot read it, or the
+ *   missing field when the payload is malformed.
+ *
+ * @example
+ *   async hydrate(sessionId) {
+ *     const stored = await myStore.get(sessionId);
+ *     return stored === undefined ? undefined : checkEnvelope(stored);
+ *   }
+ */
+export function checkEnvelope(envelope) {
+    if (readFormat(envelope) === 'flowchart-v1') {
+        validatePausedRun(envelope.data);
+    }
+    else {
+        validateCheckpoint(envelope.data);
+    }
+    return envelope;
+}
+/**
+ * The one place a `format` is checked, so every refusal in this file says the
+ * same thing in the same words.
+ */
+function readFormat(envelope) {
+    if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
+        throw new TypeError(`[hosting] stored session is not an envelope (got ${envelope === null ? 'null' : Array.isArray(envelope) ? 'an array' : typeof envelope}). Expected { format, data, savedAt } as written by toEnvelope() / toPausedEnvelope().`);
     }
     const found = envelope.format;
     if (typeof found !== 'string' || !KNOWN_FORMATS.includes(found)) {
         throw new TypeError(`[hosting] unknown checkpoint format '${String(found)}'. ` +
             `This runtime reads: ${KNOWN_FORMATS.join(', ')}. ` +
-            `Refusing rather than restoring a conversation it cannot read — a newer envelope ` +
+            `Refusing rather than restoring a session it cannot read — a newer envelope ` +
             `needs a runtime that knows the format that wrote it.`);
     }
-    return validateCheckpoint(envelope.data);
+    return found;
+}
+/**
+ * Validate a paused run at deserialization time, naming the missing piece.
+ *
+ * Only the fields resume actually consumes are required. `executionTree` and
+ * `subflowResults` are the engine's diagnostic halves — a checkpoint that lost
+ * them in transit still resumes, so demanding them would refuse a session that
+ * would have worked.
+ */
+function validatePausedRun(value) {
+    if (!value || typeof value !== 'object') {
+        throw new TypeError('[hosting] paused run is not an object.');
+    }
+    const run = value;
+    const cp = run.checkpoint;
+    if (!cp || typeof cp !== 'object') {
+        throw new TypeError(`[hosting] paused run is missing required field: checkpoint. ` +
+            `It is the engine checkpoint agent.resume() continues from; without it the run ` +
+            `cannot be continued at all.`);
+    }
+    if (typeof cp.pausedStageId !== 'string' ||
+        !cp.sharedState ||
+        typeof cp.sharedState !== 'object') {
+        throw new TypeError(`[hosting] paused run's checkpoint is missing required fields (pausedStageId, ` +
+            `sharedState) — the two agent.resume() rebuilds the cursor and the run's state from.`);
+    }
+    if (!Array.isArray(cp.subflowPath)) {
+        throw new TypeError(`[hosting] paused run's checkpoint is missing required field: subflowPath.`);
+    }
+    if (!run.pending || typeof run.pending !== 'object') {
+        throw new TypeError(`[hosting] paused run is missing required field: pending — the question it is ` +
+            `waiting on. A stored pause nobody can describe is a session that hangs.`);
+    }
+    validateCheckpoint(run.conversation);
+    return run;
 }
 //# sourceMappingURL=envelope.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/hosting/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kBAAkB,EAA2B,MAAM,0BAA0B,CAAC;AAGvF,+DAA+D;AAC/D,MAAM,aAAa,GAAsB,CAAC,iBAAiB,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,UAA8B;IACvD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,QAAiB;IAC5C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,IAAI,SAAS,CACjB,oDACE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,QACtC,KAAK,GAAG,gEAAgE,CACzE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAI,QAAwC,CAAC,MAAM,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CACjB,wCAAwC,MAAM,CAAC,KAAK,CAAC,KAAK;YACxD,uBAAuB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACnD,kFAAkF;YAClF,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,OAAO,kBAAkB,CAAE,QAA+B,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/hosting/envelope.ts"],"names":[],"mappings":"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"}

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

@@ -3,17 +3,21 @@
  * same words.
  *
  * A refusal that varies by adapter is a refusal nobody can write a test or a
- * runbook against. These three carry a stable `code`, name WHO refused, and say
+ * runbook against. These five carry a stable `code`, name WHO refused, and say
  * what the caller should do instead. Adapters map the codes onto whatever their
  * transport uses to say "no" — that mapping is the adapter's business and lives
  * in the adapter, never here.
  *
- * `requireCapability` is the fourth refusal and the only one that is a
+ * Note what is NOT here: a run that paused. That is unfinished work rather than
+ * a refusal, and it leaves through `reply.awaiting(...)` — its own terminal —
+ * not through an error dressed up as one.
+ *
+ * `requireCapability` is the last refusal and the only one that is a
  * programming mistake rather than a runtime condition, so it throws a plain
  * `Error`: nothing branches on "I forgot to feature-detect", it just needs to
  * say so loudly and name the adapter it is talking about.
  */
-import type { AgentHost, HostCapability } from './types.js';
+import type { AgentHost, HostCapability, PendingAsk } from './types.js';
 /**
  * Thrown when a request arrives at a host that is shutting down or shut down.
  *
@@ -44,22 +48,67 @@ export declare class ConcurrentRunError extends Error {
     constructor(sessionId: string, activeRunId?: string);
 }
 /**
- * Raised when a run paused to ask a person something and the reply cannot carry
- * a pause.
+ * Raised when a run paused to ask a person something and there is **nowhere to
+ * keep it**.
  *
  * **The run did not fail.** A pause is unfinished work: the agent stopped to ask
- * and is waiting for an answer. What cannot happen here is storing it — the
- * `'conversation-v1'` envelope holds a conversation, and a paused run is a
- * conversation plus an engine checkpoint. So nothing is written, and the
- * session keeps exactly the conversation it had before this request.
+ * and is waiting for an answer. Since 7.19 a paused run is stored as
+ * `'flowchart-v1'` and continued by a later request carrying a decision — so the
+ * one case left where a pause genuinely cannot be carried is a request with no
+ * session id. There is no session to store it under, and therefore no later
+ * request that could ever answer it.
+ *
+ * The other half of the old meaning — "the reply cannot carry a pause" — is
+ * gone: {@link HostReply.awaiting} carries it now. An adapter that has not
+ * implemented that terminal still gets its pause STORED (the store is not the
+ * transport's business) and this refusal on the wire, naming the session it can
+ * be answered on.
  */
 export declare class PauseNotCarriedError extends Error {
     readonly code: "ERR_PAUSE_NOT_CARRIED";
     /** The tool that asked, when the run recorded which one it was. */
     readonly toolName?: string;
-    /** The session whose stored conversation was left untouched. */
+    /** The session the paused run was stored under, when there was one. */
     readonly sessionId?: string;
-    constructor(toolName?: string, sessionId?: string);
+    /** Whether the paused run was stored. `false` means it is gone. */
+    readonly stored: boolean;
+    constructor(toolName?: string, sessionId?: string, stored?: boolean);
+}
+/**
+ * Thrown when a new message arrives for a session whose run is waiting on a
+ * person's decision.
+ *
+ * The message is NOT run and the pause is NOT discarded — those are the two ways
+ * this could have gone wrong. Answering the message would step over an
+ * outstanding consent gate; dropping the paused run to make room for the message
+ * would throw away work a person was asked about. So the request is refused, the
+ * pending question is named, and the session sits exactly where it was.
+ *
+ * Answer it by sending the same session a request carrying
+ * {@link HostRequest.decision}.
+ */
+export declare class AwaitingDecisionError extends Error {
+    readonly code: "ERR_AWAITING_DECISION";
+    /** The session that is waiting. */
+    readonly sessionId: string;
+    /** What it is waiting on — the same payload `reply.awaiting()` delivered. */
+    readonly pending: PendingAsk;
+    constructor(sessionId: string, pending: PendingAsk);
+}
+/**
+ * Thrown when a request carries a decision for a session that is not waiting on
+ * one.
+ *
+ * Usually a duplicate delivery: the run was already continued, or already
+ * answered, and the same decision arrived twice. Running it as an ordinary
+ * message would put a raw approval into the conversation as if the user had
+ * typed it, so it is refused by name instead.
+ */
+export declare class NoPendingAskError extends Error {
+    readonly code: "ERR_NO_PENDING_ASK";
+    /** The session the decision was addressed to. */
+    readonly sessionId: string;
+    constructor(sessionId: string);
 }
 /**
  * Assert that a host can do something, and throw a corrective error naming the