@slopus/happy-agent-base 0.0.2 → 0.0.4

package/dist/AgentBase.js

@@ -1,13 +1,11 @@
 import { areProviderModelsCompatible } from "@slopus/happy-providers";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID } from "node:crypto";
 import { Value } from "@sinclair/typebox/value";
 import { asyncLock, createContextNamespace, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
 import { withAgentContext, withAgentKV, withAgentRunKV } from "./AgentContexts.js";
 import { taskContextBeforeToolCall, withAgentTaskContext } from "./AgentTaskContext.js";
 import { AgentKV } from "./AgentKV.js";
 import { AGENT_BASE_PENDING_KEY, agentBasePendingStateOf, } from "./AgentBasePending.js";
-import { agentBaseStoreLock, agentBaseWithStoreStill } from "./AgentBaseStoreLock.js";
 import { AgentProviders } from "./AgentProviders.js";
 /** Race winner when an abort interrupts a wait on the stream or a running tool. */
 const ABORTED = Symbol("aborted");
@@ -32,8 +30,6 @@ const insideLoops = new AsyncLocalStorage();
  * hears the shutdown finish, short enough that one still holding the loop is told promptly.
  */
 const INSIDE_CLOSE_REPORT_MS = 15;
-/** Rolls a consumption back when every entry in its batch was already taken by another owner. */
-const LOST_QUEUE_RACE = Symbol("lostQueueRace");
 /**
  * A single agent session over one provider. Messages arrive through two FIFO queues: steering
  * messages inject as soon as the current assistant response and its tool batch finish, while
@@ -43,8 +39,7 @@ const LOST_QUEUE_RACE = Symbol("lostQueueRace");
  *
  * The rest of this comment is the list of promises the implementation has to keep. They are
  * written down because most of them are invisible in ordinary use and only show themselves when
- * a process dies, two owners share a store, or a caller races the loop — every one of them was
- * bought with a bug found by `tests/chaos/`, and each has a focused test that fails without it.
+ * a process dies or a caller races the loop. Each has focused test coverage.
  *
  * ## Serialization
  *
@@ -63,24 +58,19 @@ const LOST_QUEUE_RACE = Symbol("lostQueueRace");
  *   acceptance is the same one, and a close still waits for it.
  * - Messages a hook returns from one decision are accepted as one batch. A caller arriving while
  *   that batch is being written lands after all of it, never between two halves of one thought.
- * - Queue keys order by what the store already holds and end in a segment identifying their
- *   writer, so two owners accepting in the same millisecond may order arbitrarily but can never
- *   overwrite one another.
+ * - Queue keys order by what the store already holds, including when the clock moves backwards.
  * - An agent holding a durable message never describes itself as settled.
  *
  * ## Consuming a message
  *
- * A consumption claims each entry with an atomic delete inside its own transaction, so one
- * durable message is answered exactly once however many live owners hold it in memory. A batch
- * that claims nothing rolls back having changed nothing. A message is never durable in both the
- * queue and the context, or in neither, and memory changes only after the commit.
+ * A consumption deletes each entry inside the transaction that appends it to the context. A
+ * message is never durable in both places, or in neither, and memory changes only after commit.
  *
  * ## Turns
  *
- * A turn answers the durable conversation, not the one this instance remembers: it reloads
- * before it decides anything, so an appended message or a model switch from another owner is in
- * force by the next turn. A turn that consumes the last queued work clears the request it just
- * answered, rather than buying an extra turn with an empty queue and a full set of hooks.
+ * A turn reloads the durable conversation before it decides anything, keeping the store
+ * authoritative across restarts. A turn that consumes the last queued work clears the request it
+ * just answered rather than buying an extra empty turn with a full set of hooks.
  *
  * ## Tool calls
  *
@@ -102,10 +92,8 @@ const LOST_QUEUE_RACE = Symbol("lostQueueRace");
  * ## Compaction
  *
  * A compaction runs before a turn's first inference, so the model always receives a settled
- * conversation. It replaces the history whole or not at all, and the suffix it preserves is
- * rebuilt from the store inside the commit — from a record count taken at the snapshot, so work
- * another owner committed while the provider was summarizing survives. A compaction nobody will
- * carry out is rejected rather than left waiting.
+ * conversation. It replaces the history whole or not at all. A compaction nobody will carry out
+ * is rejected rather than left waiting.
  *
  * ## Model changes
  *
@@ -255,13 +243,6 @@ export class AgentBase {
     #toolsRunning = 0;
     /** The in-flight or finished load of the durable state; cleared at the start of every turn. */
     #loaded;
-    /**
-     * Identifies this instance's writes, so no other writer can produce one of its keys. It is a
-     * UUID rather than a number drawn from the general-purpose generator, because two owners of
-     * one store acknowledging a message each are relying on it to keep their keys apart, and a
-     * generator that can be seeded — or replaced — would let both of them claim the same one.
-     */
-    #writer = randomUUID();
     /**
      * The kind of the last durable record, which says what the conversation is waiting for far
      * more precisely than the message it ends on: a consumed message, a tool result or the note
@@ -269,19 +250,6 @@ export class AgentBase {
      * compaction is owed nothing at all.
      */
     #lastRecordType;
-    /**
-     * Whether that last record was a replacement that ended on a message still owed an answer.
-     * Only the rewrite that wrote it can tell a summary's own last message from a suffix it kept.
-     */
-    #lastRecordContinuesInference = false;
-    /**
-     * How many durable records the in-memory conversation accounts for: the ones it was loaded
-     * from, plus every one this instance has appended since. A rewrite replaces exactly those.
-     * Counting the store afresh would treat records this instance has never seen as already
-     * summarized and erase them; forgetting its own appends would carry records the summary
-     * already covers into the replacement a second time.
-     */
-    #loadedRecordCount = 0;
     /**
      * Whether this instance has checked whether a cut-off run should resume inference. The
      * question is only meaningful once, against the state the agent first loaded: afterwards a
@@ -424,7 +392,7 @@ export class AgentBase {
         this.#providers = options.providers;
         this.#providerId = options.provider;
         this.#persistence = options.persistence;
-        this.#persistenceLock = agentBaseStoreLock(options.persistence);
+        this.#persistenceLock = asyncLock({ reentry: "block" });
         this.#hooks = options.hooks ?? {};
         this.state = {
             instructions: options.initialState?.instructions ?? "",
@@ -471,9 +439,9 @@ export class AgentBase {
      * whatever else that transaction is writing, which is how a consumed message and the
      * inference it owes become durable as one fact rather than two.
      */
-    async #recordPending(ctx, pending) {
+    async #recordPending(ctx, pending, force = false) {
         const serialized = deterministicStringify(pending);
-        if (this.#pendingWritten === serialized)
+        if (!force && this.#pendingWritten === serialized)
             return;
         await this.#persistence.writeValue(ctx, AGENT_BASE_PENDING_KEY, pending);
         this.#pending = pending;
@@ -487,22 +455,38 @@ export class AgentBase {
      * is doing, and a run interrupted by a dead process would be indistinguishable from the one
      * starting here.
      */
-    async #enterStage(stage) {
+    async #enterStage(stage, transact) {
         const pending = { stage };
-        if (deterministicStringify(pending) === this.#pendingWritten && this.#inheritedRead)
-            return;
+        if (transact === undefined &&
+            deterministicStringify(pending) === this.#pendingWritten &&
+            this.#inheritedRead) {
+            return undefined;
+        }
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            return await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
                 if (!this.#inheritedRead) {
                     this.#inheritedRead = true;
                     this.#inherited = await agentBasePendingStateOf(lockCtx, this.#persistence);
                 }
-                await this.#recordPending(lockCtx, pending);
+                if (transact === undefined) {
+                    await this.#recordPending(lockCtx, pending);
+                    return undefined;
+                }
+                return await this.#recordTransaction(lockCtx, async (txCtx) => {
+                    // The state is staged first. The callback then writes against this exact
+                    // transaction, so neither its conclusion nor the state it observed can land
+                    // without the other.
+                    await this.#recordPending(txCtx, pending, true);
+                    return await this.#withTransactionalContext(txCtx, transact);
+                });
             });
         }
-        catch {
+        catch (error) {
+            if (transact !== undefined)
+                throw error;
             // Losing the record costs recovery precision, never the work itself: the turn is
             // already running and will answer whatever it was going to answer.
+            return undefined;
         }
     }
     /**
@@ -871,12 +855,27 @@ export class AgentBase {
             }),
         ]);
         if (!settled) {
+            // The caller cannot wait for its own turn, but the agent is closing all the same.
+            // Revoke the caller's tool/store capability before reporting the cyclic wait so it
+            // cannot resume later and write after the owning system releases its store lock.
+            this.#closeController.abort();
             throw new Error("Closing the agent from inside its own run loop would wait for a turn that " +
                 "cannot finish. The shutdown was started and will complete once this " +
                 "caller returns.");
         }
         await this.#closing;
     }
+    /**
+     * Wait for a close that has already been requested to finish. Unlike `close`, this never
+     * initiates shutdown, so owners can separate the caller-facing reentrancy report from the
+     * underlying lifetime barrier.
+     */
+    async waitForClosed() {
+        const closing = this.#closing;
+        if (closing === undefined)
+            throw new Error("The agent has not been asked to close.");
+        await closing;
+    }
     /**
      * Make sure the run loop is running. A loop already in flight picks up the request on its
      * next pass, so this never starts a second one.
@@ -918,7 +917,7 @@ export class AgentBase {
             // crash could interrupt. What it records is refined as the run reaches each stage;
             // what matters at this point is that the record exists at all, since its absence is
             // what a later process reads as an agent that finished.
-            await this.#enterStage("inference");
+            await this.#enterStage("inference", this.#hooks.beforeAgentLoopTransact);
             await this.#invokeHook(this.#hooks.beforeAgentLoop);
             do {
                 this.#turnAborted = false;
@@ -927,10 +926,8 @@ export class AgentBase {
                 // redundant turn this can cost is cheap: an empty queue drains without any
                 // inference.
                 this.#turnRequested = false;
-                // Every turn starts from the durable state rather than from what this instance
-                // last remembered. Another owner over the same store may have appended messages
-                // or changed the selection since, and answering out of a stale memory would
-                // reply to a conversation that no longer exists.
+                // Every turn starts from durable state rather than from what this instance last
+                // remembered, so the store remains authoritative after recovery.
                 this.#loaded = undefined;
                 // The durable history has to be loaded before anything else: a turn that cannot
                 // read the conversation cannot answer it, and must not write to it either —
@@ -949,20 +946,29 @@ export class AgentBase {
                     });
                     break;
                 }
-                await this.#applyActions(this.#hooks.beforeTurn, abort.signal, {
+                const turnStart = {
                     contextTokens: this.#contextTokens,
-                });
+                };
+                await this.#enterStage("inference", this.#hooks.beforeTurnTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.beforeTurnTransact?.(hookCtx, turnStart));
+                await this.#applyActions(this.#hooks.beforeTurn, abort.signal, turnStart);
                 await this.#runInference(abort);
-                await this.#applyActions(this.#hooks.afterTurn, abort.signal, {
+                const turn = {
                     contextTokens: this.#contextTokens,
                     aborted: this.#turnAborted,
-                });
+                };
+                await this.#enterStage("inference", this.#hooks.afterTurnTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.afterTurnTransact?.(hookCtx, turn));
+                await this.#applyActions(this.#hooks.afterTurn, abort.signal, turn);
                 if (!this.#turnRequested || this.#closed)
                     break;
                 // Each turn cancels on its own scope. Reopening it here rather than at the top
                 // keeps the run's first turn under the scope its opening hook already ran in.
                 abort = this.#openAbortScope();
             } while (true);
+            await this.#enterStage("inference", this.#hooks.afterAgentLoopTransact);
             await this.#applyActions(this.#hooks.afterAgentLoop, abort.signal);
         } while (this.#turnRequested && !this.#closed);
         // Nothing is asked for any more, so the outstanding work is erased. That erasure is what
@@ -979,7 +985,7 @@ export class AgentBase {
      */
     async #settleDurably() {
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#persistence.transaction(lockCtx, async (txCtx) => {
+            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 await this.#clearPending(txCtx);
                 await this.#invokeTransactionalSettle(txCtx);
                 // The run store is erased last, so a settling hook can still read what the
@@ -1004,15 +1010,7 @@ export class AgentBase {
         const hook = this.#hooks.afterAgentSettledTransact;
         if (hook === undefined)
             return;
-        const committed = new AbortController();
-        try {
-            const liveCtx = withLifetime(insideTurn.set(txCtx, []), committed.signal);
-            const hookCtx = withAgentKV(liveCtx, this.#kv);
-            await hook(withAgentRunKV(hookCtx, this.#runKV));
-        }
-        finally {
-            committed.abort();
-        }
+        await this.#withTransactionalContext(insideTurn.set(txCtx, []), hook);
     }
     /**
      * Erase everything the run wrote about itself, inside the transaction that settles the agent:
@@ -1063,6 +1061,21 @@ export class AgentBase {
     async #invokeHook(hook, ...args) {
         await this.#invokeHookOn(this.#ctx, hook, ...args);
     }
+    /**
+     * Lend a hook the transaction's context and feature stores for exactly one callback. Keeping
+     * the context after the callback cannot leak a transaction past its commit.
+     */
+    async #withTransactionalContext(txCtx, work) {
+        const lifetime = new AbortController();
+        try {
+            const liveCtx = withLifetime(txCtx, lifetime.signal);
+            const hookCtx = withAgentKV(liveCtx, this.#kv);
+            return await work(withAgentRunKV(hookCtx, this.#runKV));
+        }
+        finally {
+            lifetime.abort();
+        }
+    }
     /**
      * Ask a hook what to do next, on a scope that may be cancelled while the hook is still
      * thinking. An abort owns the whole of the turn it cancelled, including the answer of a hook
@@ -1212,6 +1225,7 @@ export class AgentBase {
                 // either.
                 if ((await Promise.race([this.#settled(), abortPromise])) === ABORTED)
                     continue;
+                await this.#enterStage("inference", this.#hooks.beforeInferenceTransact);
                 await this.#invokeHook(this.#hooks.beforeInference);
                 const stream = session.run(this.#ctx, {
                     context: {
@@ -1225,14 +1239,21 @@ export class AgentBase {
                 const { content, state, errorMessage, tokens } = await this.#collect(stream, abortPromise);
                 // A cancelled or failed response measures nothing, so the conversation keeps
                 // the last real measurement instead of forgetting how large it had become.
-                if (tokens !== undefined) {
-                    await this.#recordContextTokens(tokens.input + tokens.output);
-                }
-                await this.#invokeHook(this.#hooks.afterInference, {
+                const inference = {
                     state,
                     tokens,
                     ...(errorMessage === undefined ? {} : { errorMessage }),
-                });
+                };
+                const afterInferenceTransact = this.#hooks.afterInferenceTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.afterInferenceTransact?.(hookCtx, inference);
+                if (tokens === undefined) {
+                    await this.#enterStage("inference", afterInferenceTransact);
+                }
+                else {
+                    await this.#recordContextTokens(tokens.input + tokens.output, afterInferenceTransact);
+                }
+                await this.#invokeHook(this.#hooks.afterInference, inference);
                 if (content.length > 0) {
                     this.#messages.push({ role: "assistant", content });
                 }
@@ -1298,26 +1319,15 @@ export class AgentBase {
      * and so owes an inference nobody asked for again.
      *
      * What is outstanding is read from the conversation: a tail that is a consumed message, a
-     * tool result, or the note a failed turn left behind is owed an answer, while a replacement
-     * written by a compaction is owed one only when the suffix it kept ends in a request.
-     *
-     * The pending record deliberately does not decide this, because one store may have several
-     * live owners and there is only one record. An owner working right now leaves behind exactly
-     * what a process that died would have left, so deciding from the record alone would have
-     * each owner treat the others' work as abandoned and answer it a second time. What the
-     * record adds is the knowledge that some run reached the model: a listener shown the
+     * tool result, or the note a failed turn left behind is owed an answer. The pending record
+     * adds the knowledge that the interrupted run reached the model: a listener shown the
      * beginning of a block that will now never arrive is told to drop it. Only finished blocks
-     * are ever persisted, so the conversation is intact and it is the view being corrected.
+     * are persisted, so the conversation is intact and it is the view being corrected.
      */
     #resumesInterruptedRun() {
         const owed = this.#lastRecordType === "user" ||
             this.#lastRecordType === "tool" ||
-            this.#lastRecordType === "system" ||
-            // A replacement record is not a question in itself, however it happens to end — but
-            // it keeps the suffix that joined the conversation after its snapshot, and a consumed
-            // message in that suffix still needs inference. Which kind of message ends the
-            // replacement is not visible in the messages, so the rewrite that knew records it.
-            (this.#lastRecordType === "compaction" && this.#lastRecordContinuesInference);
+            this.#lastRecordType === "system";
         if (owed && this.#inherited?.stage === "inference")
             this.#emit({ type: "block_reset" });
         return owed;
@@ -1335,24 +1345,39 @@ export class AgentBase {
      * lets a restarted agent keep knowing how large the conversation is without inferring it;
      * a failed write costs only that knowledge and never the response that produced it.
      */
-    async #recordContextTokens(tokens) {
+    async #recordContextTokens(tokens, transact) {
+        const previousTokens = this.#contextTokens;
         this.#contextTokens = tokens;
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => tokens === undefined
-                ? this.#persistence.deleteValue(lockCtx, "context")
-                : this.#persistence.writeValue(lockCtx, "context", { tokens }));
+            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                const write = (writeCtx) => tokens === undefined
+                    ? this.#persistence.deleteValue(writeCtx, "context")
+                    : this.#persistence.writeValue(writeCtx, "context", { tokens });
+                if (transact === undefined) {
+                    await write(lockCtx);
+                    return;
+                }
+                await this.#recordTransaction(lockCtx, async (txCtx) => {
+                    await write(txCtx);
+                    await this.#withTransactionalContext(txCtx, transact);
+                });
+            });
         }
-        catch {
-            // A measurement is not worth failing a turn over; memory still carries it.
+        catch (error) {
+            // The prior committed measurement stays authoritative in memory. A transactional
+            // observer is part of the same durable conclusion and therefore fails the turn when
+            // that conclusion cannot commit; an ordinary best-effort measurement still does not.
+            this.#contextTokens = previousTokens;
+            if (transact !== undefined)
+                throw error;
         }
     }
     /**
-     * Run the pending compaction, if any. The snapshot is taken before the turn's first
-     * inference, with this pass being the only history writer, so nothing joins the history
-     * mid-compaction; the suffix copy still keeps any such message, defensively. The replacement
-     * is appended as a compaction record — the load-time reset point — and settles the shared
-     * promise for every caller awaiting it. A provider failure rejects them and leaves the
-     * history untouched.
+     * Run the pending compaction, if any. This pass is the only history writer, so the provider
+     * summarizes exactly the conversation that the replacement supersedes. The replacement is
+     * appended as a compaction record — the load-time reset point — and settles the shared
+     * promise for every caller awaiting it. A provider failure rejects them and leaves history
+     * untouched.
      */
     async #runCompaction(signal) {
         const pending = this.#compaction;
@@ -1362,15 +1387,6 @@ export class AgentBase {
             await this.#enterStage("compaction");
             const instructions = await this.#instructions();
             const session = await this.#ensureSession(instructions, await this.#tools());
-            // The snapshot is the durable conversation, counted as records: everything appended
-            // after this point is a suffix the replacement has to keep, whoever wrote it. Taking
-            // the boundary from the store rather than from this instance's own memory means a
-            // record another owner committed while the provider was summarizing survives the
-            // clear-and-replace instead of being erased by it.
-            // The boundary is the prefix this instance's memory was built from, not whatever
-            // the store holds now: the provider is about to summarize that memory, and counting
-            // a newer store would describe records it never saw as summarized.
-            const snapshotCount = this.#loadedRecordCount;
             const snapshot = [...this.#messages];
             await this.#settled();
             // Provider compaction is this turn's work, so it runs on this turn's lifetime: an
@@ -1385,27 +1401,17 @@ export class AgentBase {
             }
             if (result.status === "completed") {
                 await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
-                    const records = await this.#persistence.load(lockCtx);
-                    const suffix = messagesFromRecords(records.slice(snapshotCount));
-                    const replaced = [...result.context.messages, ...suffix];
-                    // Only a message in the live suffix can require another inference. The
-                    // summary's own final message is provider-authored context, not a request.
-                    const continuesInference = suffix.length > 0 && needsInference(replaced);
                     // Physically delete the superseded records and write the replacement —
                     // which keeps the messages that stay — in one atomic step.
                     await this.#recordTransaction(lockCtx, async (txCtx) => {
                         await this.#persistence.clearRecords(txCtx);
                         await this.#persistence.append(txCtx, {
                             type: "compaction",
-                            messages: replaced,
-                            ...(continuesInference ? { continuesInference: true } : {}),
+                            messages: result.context.messages,
                         });
                     });
-                    this.#messages = [...replaced];
+                    this.#messages = [...result.context.messages];
                     this.#lastRecordType = "compaction";
-                    this.#lastRecordContinuesInference = continuesInference;
-                    // The store is now the one replacement record, and memory is exactly it.
-                    this.#loadedRecordCount = 1;
                 });
                 // The conversation the measurement described is gone; its size is unknown
                 // again until the next response measures the replacement.
@@ -1464,21 +1470,15 @@ export class AgentBase {
         return settled;
     }
     /**
-     * Append one record and keep count of it. Every record this instance writes is one more that
-     * its memory accounts for, and a rewrite has to know exactly where its own knowledge ends —
-     * so appending and counting are one step rather than two a caller could get out of order.
+     * Append one record to the durable conversation.
      */
     async #appendRecord(ctx, record) {
         await this.#persistence.append(ctx, record);
-        this.#loadedRecordCount += 1;
     }
     /**
-     * A transaction whose effect on the record count unwinds with it. Records staged by a
-     * transaction that rolls back were never written, and memory never took them either, so the
-     * count must not go on claiming them.
+     * A transaction whose pending-state cache unwinds with it.
      */
     async #recordTransaction(ctx, work) {
-        const counted = this.#loadedRecordCount;
         // The outstanding work unwinds with the records for the same reason: a stage staged by a
         // transaction that rolled back was never written, and memory claiming it would make the
         // agent skip the write that actually records what it is doing.
@@ -1488,7 +1488,6 @@ export class AgentBase {
             return await this.#persistence.transaction(ctx, work);
         }
         catch (error) {
-            this.#loadedRecordCount = counted;
             this.#pending = pending;
             this.#pendingWritten = written;
             throw error;
@@ -1527,9 +1526,7 @@ export class AgentBase {
         return await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
             if (queue.length === 0)
                 return false;
-            // The durable queue, not memory, decides what is left to consume. Another owner over
-            // the same store may have taken these entries already, and a message answered twice
-            // is as wrong as one answered never.
+            // The durable queue, not memory, decides what is left to consume after a restart.
             const durable = new Set((await this.#persistence.readValues(lockCtx, prefix)).map(({ key }) => key));
             const remaining = queue.filter((entry) => durable.has(entry.key));
             if (remaining.length !== queue.length)
@@ -1595,127 +1592,97 @@ export class AgentBase {
                     reset = model !== this.#model;
                 }
             }
-            const consumed = [];
-            try {
-                await this.#recordTransaction(lockCtx, async (txCtx) => {
-                    if (selectionChanged) {
-                        if (this.#hooks.modelChanged !== undefined && model !== undefined) {
-                            // The hook runs while the persistence lock is held and inside the
-                            // transaction that commits the switch, so its store executes directly on
-                            // that transaction: what it writes lands and rolls back with the change
-                            // it was told about, never on its own. The context it is given ends with
-                            // the transaction, so a store it keeps cannot outlive the switch.
-                            const committed = new AbortController();
-                            // Derived from the transaction's own context, which is what makes
-                            // the hook's writes part of the switch rather than a second,
-                            // separate commit, and ending with it.
-                            const changeLifetime = withLifetime(withAgentContext(txCtx, {
-                                id: this.id,
-                                provider,
+            await this.#recordTransaction(lockCtx, async (txCtx) => {
+                if (selectionChanged) {
+                    if (this.#hooks.modelChanged !== undefined && model !== undefined) {
+                        // The hook runs while the persistence lock is held and inside the
+                        // transaction that commits the switch, so its store executes directly on
+                        // that transaction: what it writes lands and rolls back with the change
+                        // it was told about, never on its own. The context it is given ends with
+                        // the transaction, so a store it keeps cannot outlive the switch.
+                        const committed = new AbortController();
+                        // Derived from the transaction's own context, which is what makes
+                        // the hook's writes part of the switch rather than a second,
+                        // separate commit, and ending with it.
+                        const changeLifetime = withLifetime(withAgentContext(txCtx, {
+                            id: this.id,
+                            provider,
+                            model,
+                            effort,
+                            serviceTier,
+                        }), committed.signal);
+                        const changeCtx = withAgentRunKV(withAgentKV(changeLifetime, this.#kv), this.#runKV);
+                        try {
+                            injected = await this.#hooks.modelChanged(changeCtx, {
+                                previousModel: this.#model,
                                 model,
-                                effort,
-                                serviceTier,
-                            }), committed.signal);
-                            const changeCtx = withAgentRunKV(withAgentKV(changeLifetime, this.#kv), this.#runKV);
-                            try {
-                                injected = await this.#hooks.modelChanged(changeCtx, {
-                                    previousModel: this.#model,
-                                    model,
-                                    previousProvider: this.#providerId,
-                                    provider,
-                                    providers: this.#providers,
-                                    previousProviderInstance: this.#providers.get(this.#providerId),
-                                    providerInstance: this.#providers.get(provider),
-                                    wasReset: reset,
-                                });
-                            }
-                            catch {
-                                // A failing handoff must not cost the conversation: an incompatible
-                                // switch is rejected outright — the previous selection stays
-                                // effective and the history is not cleared. A compatible change
-                                // proceeds; the hook only observed it.
-                                if (reset) {
-                                    provider = this.#providerId;
-                                    model = this.#model;
-                                    reset = false;
-                                }
-                            }
-                            finally {
-                                // The store belonged to the hook's call, not to the hook.
-                                committed.abort();
+                                previousProvider: this.#providerId,
+                                provider,
+                                providers: this.#providers,
+                                wasReset: reset,
+                            });
+                        }
+                        catch {
+                            // A failing handoff must not cost the conversation: an incompatible
+                            // switch is rejected outright — the previous selection stays
+                            // effective and the history is not cleared. A compatible change
+                            // proceeds; the hook only observed it.
+                            if (reset) {
+                                provider = this.#providerId;
+                                model = this.#model;
+                                reset = false;
                             }
-                            if (!reset)
-                                injected = undefined;
                         }
-                    }
-                    consumed.length = 0;
-                    // Each entry is claimed as it is consumed: the delete answers whether this
-                    // owner is the one that took it, so a message shared by two live owners over
-                    // one store is answered exactly once. Claiming first also means losing the
-                    // whole batch rolls the transaction back before it has changed anything.
-                    for (const entry of batch) {
-                        const claimed = await this.#persistence.deleteValueIfPresent(txCtx, entry.key);
-                        if (claimed)
-                            consumed.push(entry);
-                    }
-                    if (consumed.length === 0)
-                        throw LOST_QUEUE_RACE;
-                    if (reset) {
-                        await this.#persistence.clearRecords(txCtx);
-                        this.#loadedRecordCount = 0;
-                        // The erased conversation is what the measurement described.
-                        await this.#persistence.deleteValue(txCtx, "context");
-                        if (injected !== undefined) {
-                            await this.#appendRecord(txCtx, {
-                                type: "system",
-                                message: injected,
-                            });
+                        finally {
+                            // The store belonged to the hook's call, not to the hook.
+                            committed.abort();
                         }
+                        if (!reset)
+                            injected = undefined;
                     }
-                    for (const entry of consumed) {
+                }
+                // The queue move is atomic with appending the consumed messages and recording
+                // the inference they make due. The store has one owner, so ordinary deletes
+                // are sufficient.
+                for (const entry of batch) {
+                    await this.#persistence.deleteValue(txCtx, entry.key);
+                }
+                if (reset) {
+                    await this.#persistence.clearRecords(txCtx);
+                    // The erased conversation is what the measurement described.
+                    await this.#persistence.deleteValue(txCtx, "context");
+                    if (injected !== undefined) {
                         await this.#appendRecord(txCtx, {
-                            type: "user",
-                            message: entry.message,
-                        });
-                    }
-                    if (changed) {
-                        await this.#persistence.writeValue(txCtx, "settings", {
-                            provider,
-                            ...(model === undefined ? {} : { model }),
-                            ...(effort === undefined ? {} : { effort }),
-                            ...(serviceTier === undefined ? {} : { serviceTier }),
+                            type: "system",
+                            message: injected,
                         });
                     }
-                    // Consuming a message is precisely the act that makes an inference owed, so
-                    // the two commit as one. A crash cannot land between them and leave a
-                    // message in the conversation that nothing remembers having to answer.
-                    await this.#recordPending(txCtx, { stage: "inference" });
-                });
-            }
-            catch (error) {
-                if (error !== LOST_QUEUE_RACE)
-                    throw error;
-                // Another owner answered all of them. They are gone from the store, so they are
-                // dropped from memory too, and this turn simply has nothing to inject.
-                queue.splice(0, count);
-                return false;
-            }
+                }
+                for (const entry of batch) {
+                    await this.#appendRecord(txCtx, {
+                        type: "user",
+                        message: entry.message,
+                    });
+                }
+                if (changed) {
+                    await this.#persistence.writeValue(txCtx, "settings", {
+                        provider,
+                        ...(model === undefined ? {} : { model }),
+                        ...(effort === undefined ? {} : { effort }),
+                        ...(serviceTier === undefined ? {} : { serviceTier }),
+                    });
+                }
+                // Consuming a message is precisely the act that makes an inference owed, so
+                // the two commit as one. A crash cannot land between them and leave a
+                // message in the conversation that nothing remembers having to answer.
+                await this.#recordPending(txCtx, { stage: "inference" });
+            });
             queue.splice(0, count);
             if (reset) {
                 this.#messages = injected === undefined ? [] : [injected];
                 this.#contextTokens = undefined;
             }
-            if (reset || provider !== this.#providerId) {
-                const session = this.#session;
-                this.#session = undefined;
-                try {
-                    await session?.destroy();
-                }
-                catch {
-                    // The change already committed; a failing destroy must not undo it.
-                }
-            }
-            this.#messages.push(...consumed.map((entry) => entry.message));
+            this.#messages.push(...batch.map((entry) => entry.message));
             // This turn is answering the request that these messages raised. A send accepted
             // while the turn was already running raised it again, and letting that stand would
             // buy an extra turn with an empty queue and a full set of lifecycle hooks.
@@ -1745,9 +1712,6 @@ export class AgentBase {
             const records = await this.#persistence.load(lockCtx);
             const last = records[records.length - 1];
             this.#lastRecordType = last?.type;
-            this.#lastRecordContinuesInference =
-                last?.type === "compaction" && last.continuesInference === true;
-            this.#loadedRecordCount = records.length;
             let restored = messagesFromRecords(records);
             const steering = await this.#persistence.readValues(lockCtx, "steering.");
             const sends = await this.#persistence.readValues(lockCtx, "send.");
@@ -1877,7 +1841,8 @@ export class AgentBase {
                 outcome = toolFailure(entry.call.callId, "The tool call was interrupted by a restart and was not retried.");
             }
             else {
-                const execution = this.#executeToolCall(withLifetime(this.#ctx, signal), entry.call);
+                const toolLifetime = AbortSignal.any([signal, this.#closeController.signal]);
+                const execution = this.#executeToolCall(withLifetime(this.#ctx, toolLifetime), entry.call);
                 running.push(execution);
                 outcome = await Promise.race([execution, abortPromise, this.#closingTools()]);
             }
@@ -2007,20 +1972,15 @@ export class AgentBase {
         }
     }
     /**
-     * A key that sorts after every entry the queue already holds and belongs to no other
-     * writer. The order comes from the store rather than from a counter this instance keeps,
-     * because a restarted agent starts counting again and would otherwise reuse a key. The
-     * trailing writer segment settles the rest: two owners that read the same tail at the same
-     * millisecond still produce different keys, so an acknowledged message can never be
-     * overwritten by one accepted elsewhere — only ordered arbitrarily against it, which is all
-     * that simultaneous acceptance can mean. Reading the tail also keeps the order right when
-     * the clock goes backwards.
+     * A key that sorts after every entry the queue already holds. The order comes from the store
+     * rather than from an in-memory counter, because a restarted agent begins counting again.
+     * Reading the tail also keeps order correct when the clock moves backwards.
      */
     async #queueKey(ctx, prefix) {
         const existing = await this.#persistence.readValues(ctx, prefix);
         const last = existing[existing.length - 1]?.key;
         const time = String(Date.now()).padStart(14, "0");
-        const key = (slot, sequence) => `${prefix}${slot}.${String(sequence).padStart(6, "0")}.${this.#writer}`;
+        const key = (slot, sequence) => `${prefix}${slot}.${String(sequence).padStart(6, "0")}`;
         if (last === undefined)
             return key(time, 0);
         const [lastSlot, lastSequence] = last.slice(prefix.length).split(".");
@@ -2042,11 +2002,21 @@ export class AgentBase {
         // in-memory assistant message never diverges from what a reload would rebuild.
         const persisted = [];
         const toolCallIndexes = new Map();
-        const persist = async (block) => {
-            if (block === undefined)
+        const persist = async (event) => {
+            if (event === undefined)
                 return;
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#appendRecord(lockCtx, { type: "block", block }));
-            persisted.push(block);
+            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                if (this.#hooks.onEventTransact === undefined) {
+                    await this.#appendRecord(lockCtx, { type: "block", block: event.block });
+                }
+                else {
+                    await this.#recordTransaction(lockCtx, async (txCtx) => {
+                        await this.#appendRecord(txCtx, { type: "block", block: event.block });
+                        await this.#withTransactionalContext(txCtx, (hookCtx) => this.#hooks.onEventTransact?.(hookCtx, event));
+                    });
+                }
+            });
+            persisted.push(event.block);
         };
         const iterator = stream[Symbol.asyncIterator]();
         // A response usually ends before its stream does — at the done event, or at an abort —
@@ -2085,7 +2055,7 @@ export class AgentBase {
                     }
                     case "text_end": {
                         const last = content[content.length - 1];
-                        await persist(last?.type === "text" ? last : undefined);
+                        await persist(last?.type === "text" ? { ...event, block: last } : undefined);
                         break;
                     }
                     case "reasoning_start":
@@ -2111,7 +2081,7 @@ export class AgentBase {
                                     : { reasoning: event.reasoning }),
                             };
                             content[content.length - 1] = finished;
-                            await persist(finished);
+                            await persist({ ...event, block: finished });
                         }
                         break;
                     }
@@ -2141,7 +2111,7 @@ export class AgentBase {
                                     : { incomplete: event.incomplete }),
                             };
                             content[index] = finished;
-                            await persist(finished);
+                            await persist({ ...event, block: finished });
                         }
                         break;
                     }
@@ -2191,7 +2161,7 @@ export class AgentBase {
      * that moment; an unregistered ID fails the turn like any thrown error.
      */
     async #ensureSession(instructions, tools) {
-        const key = sessionConfigKey(instructions, tools);
+        const key = sessionConfigKey(this.#providerId, this.#model, instructions, tools);
         if (this.#session !== undefined && this.#sessionConfig !== key) {
             const session = this.#session;
             this.#session = undefined;
@@ -2206,7 +2176,7 @@ export class AgentBase {
             }
         }
         if (this.#session === undefined) {
-            const provider = this.#providers.get(this.#providerId);
+            const provider = await this.#providers.resolve(this.#providerId, this.#model);
             if (provider === null) {
                 throw new Error(`Provider "${this.#providerId}" is not registered.`);
             }
@@ -2228,11 +2198,6 @@ export class AgentBase {
         }
     }
 }
-/** Whether a conversation ends on something the model has not answered. */
-function needsInference(messages) {
-    const last = messages[messages.length - 1];
-    return last?.role === "user" || last?.role === "tool" || last?.role === "system";
-}
 /**
  * The conversation a run of records spells out. A compaction record carries the complete
  * replacement context and supersedes everything before it; consecutive blocks belong to one
@@ -2277,8 +2242,10 @@ function toolFailure(callId, reason) {
  * sees participate, so re-created tool objects with identical descriptors do not churn the
  * session.
  */
-function sessionConfigKey(instructions, tools) {
+function sessionConfigKey(provider, model, instructions, tools) {
     return deterministicStringify([
+        provider,
+        model ?? null,
         instructions,
         tools.map((tool) => [
             tool.name,