agentfootprint 7.18.0 → 7.19.0

package/dist/hosting/durability.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.durableWriter = void 0;
+const durabilityBarrier_js_1 = require("../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.
+ */
+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 (0, durabilityBarrier_js_1.installDurabilityBarrier)(agent, () => {
+                if (inFlight === undefined && queued === undefined && failure === undefined)
+                    return undefined;
+                return settle();
+            });
+        },
+        settle,
+    };
+}
+exports.durableWriter = durableWriter;
+//# sourceMappingURL=durability.js.map

package/dist/hosting/durability.js.map

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

package/dist/hosting/envelope.js

@@ -1,21 +1,31 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readEnvelope = exports.toEnvelope = void 0;
+exports.checkEnvelope = exports.readPausedRun = exports.readEnvelope = exports.toPausedEnvelope = exports.toEnvelope = void 0;
 const runCheckpoint_js_1 = require("../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.
  *
@@ -27,6 +37,30 @@ function toEnvelope(checkpoint) {
     return { format: 'conversation-v1', data: checkpoint, savedAt: Date.now() };
 }
 exports.toEnvelope = toEnvelope;
+/**
+ * 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 },
+ *     }));
+ *   }
+ */
+function toPausedEnvelope(paused) {
+    return { format: 'flowchart-v1', data: paused, savedAt: Date.now() };
+}
+exports.toPausedEnvelope = toPausedEnvelope;
 /**
  * Unpack a stored envelope back into a conversation checkpoint.
  *
@@ -34,21 +68,115 @@ exports.toEnvelope = toEnvelope;
  * 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.
  */
 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 (0, runCheckpoint_js_1.validateCheckpoint)(envelope.data);
+}
+exports.readEnvelope = readEnvelope;
+/**
+ * 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.
+ */
+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);
+}
+exports.readPausedRun = readPausedRun;
+/**
+ * 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);
+ *   }
+ */
+function checkEnvelope(envelope) {
+    if (readFormat(envelope) === 'flowchart-v1') {
+        validatePausedRun(envelope.data);
+    }
+    else {
+        (0, runCheckpoint_js_1.validateCheckpoint)(envelope.data);
+    }
+    return envelope;
+}
+exports.checkEnvelope = checkEnvelope;
+/**
+ * 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 (0, runCheckpoint_js_1.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.`);
+    }
+    (0, runCheckpoint_js_1.validateCheckpoint)(run.conversation);
+    return run;
 }
-exports.readEnvelope = readEnvelope;
 //# sourceMappingURL=envelope.js.map

package/dist/hosting/envelope.js.map

@@ -1 +1 @@
-{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/hosting/envelope.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEH,+DAAuF;AAGvF,+DAA+D;AAC/D,MAAM,aAAa,GAAsB,CAAC,iBAAiB,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,UAA8B;IACvD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;AAC9E,CAAC;AAFD,gCAEC;AAED;;;;;;;;;GASG;AACH,SAAgB,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,IAAA,qCAAkB,EAAE,QAA+B,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAlBD,oCAkBC"}
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/hosting/envelope.ts"],"names":[],"mappings":"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"}

package/dist/hosting/errors.js

@@ -4,18 +4,22 @@
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requireCapability = exports.PauseNotCarriedError = exports.ConcurrentRunError = exports.HostClosedError = void 0;
+exports.requireCapability = exports.NoPendingAskError = exports.AwaitingDecisionError = exports.PauseNotCarriedError = exports.ConcurrentRunError = exports.HostClosedError = void 0;
 /**
  * Thrown when a request arrives at a host that is shutting down or shut down.
  *
@@ -65,40 +69,112 @@ class ConcurrentRunError extends Error {
 }
 exports.ConcurrentRunError = ConcurrentRunError;
 /**
- * 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.
  */
 class PauseNotCarriedError extends Error {
     code = 'ERR_PAUSE_NOT_CARRIED';
     /** The tool that asked, when the run recorded which one it was. */
     toolName;
-    /** The session whose stored conversation was left untouched. */
+    /** The session the paused run was stored under, when there was one. */
     sessionId;
-    constructor(toolName, sessionId) {
+    /** Whether the paused run was stored. `false` means it is gone. */
+    stored;
+    constructor(toolName, sessionId, stored = false) {
         super(`[hosting] the run paused to ask a person about ` +
             (toolName ? `'${toolName}'` : 'a tool') +
-            ` and this reply cannot carry a pause. ` +
-            `The run did not fail — it is unfinished, waiting on an answer. ` +
-            `Nothing was written: ` +
-            (sessionId ? `session '${sessionId}'` : 'the session') +
-            ` still holds the conversation it held before this request. ` +
-            `The 'conversation-v1' envelope stores a conversation; a paused run is a ` +
-            `conversation plus an engine checkpoint, and storing half of it would be worse ` +
-            `than storing none. Carry the pause yourself with agent.run() / agent.resume().`);
+            `. The run did not fail — it is unfinished, waiting on an answer. ` +
+            (stored
+                ? `It IS stored: send another request for session '${String(sessionId)}' carrying ` +
+                    `a 'decision' to continue it. This reply could not describe the question ` +
+                    `because the host it arrived on does not implement reply.awaiting(); read the ` +
+                    `pending ask from the session store, or serve on a host that has it.`
+                : `Nothing was written: ` +
+                    (sessionId === undefined
+                        ? `this request carried no session id, so there is nowhere to store a paused ` +
+                            `run and no later request that could ever answer it. Send a sessionId, or `
+                        : `session '${sessionId}' still holds what it held before this request. `) +
+                    `carry the pause yourself with agent.run() / agent.resume().`));
         this.name = 'PauseNotCarriedError';
         if (toolName !== undefined)
             this.toolName = toolName;
         if (sessionId !== undefined)
             this.sessionId = sessionId;
+        this.stored = stored;
     }
 }
 exports.PauseNotCarriedError = PauseNotCarriedError;
+/**
+ * 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}.
+ */
+class AwaitingDecisionError extends Error {
+    code = 'ERR_AWAITING_DECISION';
+    /** The session that is waiting. */
+    sessionId;
+    /** What it is waiting on — the same payload `reply.awaiting()` delivered. */
+    pending;
+    constructor(sessionId, pending) {
+        const asked = pending.question ?? pending.ask?.question ?? pending.checkIn?.evidence.willDo ?? 'a decision';
+        super(`[hosting] session '${sessionId}' is waiting on a person: ` +
+            (pending.tool ? `'${pending.tool}' asked "${asked}"` : `"${asked}"`) +
+            `. This message was NOT run and the paused run was NOT discarded — answering a ` +
+            `new message would step over the question, and dropping the question to answer ` +
+            `the message would throw away work somebody was asked to approve. ` +
+            `Send this session a request carrying 'decision' (checkInApproved(...) / ` +
+            `checkInDeclined(...) for a check-in or a middleware ask) to continue the run.`);
+        this.name = 'AwaitingDecisionError';
+        this.sessionId = sessionId;
+        this.pending = pending;
+    }
+}
+exports.AwaitingDecisionError = AwaitingDecisionError;
+/**
+ * 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.
+ */
+class NoPendingAskError extends Error {
+    code = 'ERR_NO_PENDING_ASK';
+    /** The session the decision was addressed to. */
+    sessionId;
+    constructor(sessionId) {
+        super(`[hosting] this request carries a 'decision' but session '${sessionId}' is not ` +
+            `waiting on one — nothing is paused. The run it answered has most likely already ` +
+            `been continued (a duplicate delivery). Refusing rather than treating an approval ` +
+            `as if a person had typed it into the conversation. Send it as 'input' if that is ` +
+            `genuinely what you meant.`);
+        this.name = 'NoPendingAskError';
+        this.sessionId = sessionId;
+    }
+}
+exports.NoPendingAskError = NoPendingAskError;
 /**
  * Assert that a host can do something, and throw a corrective error naming the
  * adapter when it cannot.

package/dist/hosting/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/hosting/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAIH;;;;;GAKG;AACH,MAAa,eAAgB,SAAQ,KAAK;IAC/B,IAAI,GAAG,iBAA0B,CAAC;IAC3C,6BAA6B;IACpB,QAAQ,CAAS;IAE1B,YAAY,QAAgB;QAC1B,KAAK,CACH,kBAAkB,QAAQ,sDAAsD;YAC9E,wFAAwF;YACxF,iDAAiD,CACpD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAdD,0CAcC;AAED;;;;;;;;GAQG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,oBAA6B,CAAC;IAC9C,gDAAgD;IACvC,SAAS,CAAS;IAC3B,mEAAmE;IAC1D,WAAW,CAAU;IAE9B,YAAY,SAAiB,EAAE,WAAoB;QACjD,KAAK,CACH,sBAAsB,SAAS,+BAA+B;YAC5D,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,WAAW,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,yEAAyE;YACzE,mEAAmE;YACnE,4DAA4D;YAC5D,qEAAqE,CACxE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAChE,CAAC;CACF;AApBD,gDAoBC;AAED;;;;;;;;;GASG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,uBAAgC,CAAC;IACjD,mEAAmE;IAC1D,QAAQ,CAAU;IAC3B,gEAAgE;IACvD,SAAS,CAAU;IAE5B,YAAY,QAAiB,EAAE,SAAkB;QAC/C,KAAK,CACH,iDAAiD;YAC/C,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;YACvC,wCAAwC;YACxC,iEAAiE;YACjE,uBAAuB;YACvB,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,SAAS,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC;YACtD,6DAA6D;YAC7D,0EAA0E;YAC1E,gFAAgF;YAChF,gFAAgF,CACnF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACrD,IAAI,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,CAAC;CACF;AAxBD,oDAwBC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,iBAAiB,CAAC,IAAe,EAAE,UAA0B;IAC3E,IAAI,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjF,MAAM,IAAI,KAAK,CACb,kBAAkB,IAAI,CAAC,IAAI,4BAA4B,UAAU,KAAK;QACpE,eAAe,GAAG,wBAAwB;QAC1C,+BAA+B,UAAU,uCAAuC;QAChF,oFAAoF,CACvF,CAAC;AACJ,CAAC;AATD,8CASC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/hosting/errors.ts"],"names":[],"mappings":"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"}

package/dist/hosting/httpHost.js

@@ -59,17 +59,27 @@ const errors_js_1 = require("./errors.js");
 /**
  * Status codes mapped by refusal code. Anything else is a 500.
  *
- * None of the three is a 5xx: none of them is the agent breaking. A closed host
- * is shutting down (503), a concurrent turn conflicts with the run already
- * going (409), and a paused run conflicts with the state this reply can carry
- * (409) — the run is unfinished, not failed, and a 500 would say otherwise to
- * every dashboard that ever sees it.
+ * Not one of them is a 5xx: none of them is the agent breaking. A closed host is
+ * shutting down (503); the other four are conflicts with the state the session
+ * is already in (409) — a run already going, a question already outstanding, a
+ * decision with nothing to decide, a pause this reply cannot describe. A 500
+ * would tell every dashboard that ever sees it something untrue.
  */
 const STATUS_BY_CODE = {
     ERR_HOST_CLOSED: 503,
     ERR_CONCURRENT_RUN: 409,
     ERR_PAUSE_NOT_CARRIED: 409,
+    ERR_AWAITING_DECISION: 409,
+    ERR_NO_PENDING_ASK: 409,
 };
+/**
+ * What a run that stopped to ask a person answers with: **202 Accepted.**
+ *
+ * The request was understood and acted on, and the work is not finished — which
+ * is what 202 means and what nothing else in the 2xx range means. Not 200: there
+ * is no answer. Not 4xx or 5xx: nothing was refused and nothing broke.
+ */
+const AWAITING_STATUS = 202;
 const DEFAULT_CAPABILITIES = ['streaming'];
 /**
  * An HTTP host for one handler, speaking the dialect you hand it.
@@ -153,7 +163,7 @@ async function serveOne(req, res, handler, wire) {
     }
     const headers = lowerCased(req.headers);
     const query = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
-    const { input, sessionId } = wire.readRequest({ body, headers, query });
+    const { input, sessionId, decision } = wire.readRequest({ body, headers, query });
     if (wantsStream) {
         res.writeHead(200, {
             'content-type': 'text/event-stream',
@@ -188,6 +198,31 @@ async function serveOne(req, res, handler, wire) {
                 sendJson(res, 200, wire.output(output));
             }
         },
+        awaiting(pending) {
+            if (settled)
+                return;
+            // A wire that cannot describe a question must not answer 202 with an
+            // empty body — that would look like a completed request. Fall through to
+            // the named refusal, which at least says what happened and where the
+            // paused run is.
+            if (!wire.awaiting) {
+                const refusal = new Error(`[hosting] the run is waiting on a person and this host's wire has no ` +
+                    `awaiting() body shape, so the question cannot be described on the wire. ` +
+                    `The paused run is stored; read the pending ask from the session store.`);
+                refusal.code = 'ERR_PAUSE_NOT_CARRIED';
+                reply.fail(refusal);
+                return;
+            }
+            settled = true;
+            const payload = wire.awaiting(pending);
+            if (wantsStream) {
+                res.write((0, stream_js_1.encodeSSE)('awaiting', payload));
+                res.end();
+            }
+            else {
+                sendJson(res, AWAITING_STATUS, payload);
+            }
+        },
         fail(error) {
             if (settled)
                 return;
@@ -207,6 +242,7 @@ async function serveOne(req, res, handler, wire) {
         await handler({
             input,
             ...(sessionId !== undefined && { sessionId }),
+            ...(decision !== undefined && { decision }),
             headers,
             signal: controller.signal,
         }, reply);