@slopus/happy-agent-base 0.0.5 → 0.0.7

package/dist/AgentBase.js

@@ -1,11 +1,15 @@
 import { areProviderModelsCompatible } from "@slopus/happy-providers";
+import { createId } from "@paralleldrive/cuid2";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
-import { asyncLock, createContextNamespace, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
-import { withAgentContext, withAgentKV, withAgentPermissionMode, withAgentRunKV, } from "./AgentContexts.js";
+import { afterCommit, asyncLock, createContextNamespace, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
+import { agentDatabase, agentKV, agentStorageTransaction, withAgentContext, withAgentDatabase, withAgentKV, withAgentPermissionMode, withAgentRunKV, withoutAgentStorageTransaction, } from "./AgentContexts.js";
+import { agentConfig, ownAgentConfig, withAgentConfig } from "./AgentConfig.js";
 import { taskContextBeforeToolCall, withAgentTaskContext } from "./AgentTaskContext.js";
 import { AgentKV } from "./AgentKV.js";
 import { AGENT_BASE_PENDING_KEY, agentBasePendingStateOf, } from "./AgentBasePending.js";
+import { cuid2Schema, ownAgentMessageMetadata, ownAgentMetadata, } from "./AgentMetadata.js";
 import { DEFAULT_AGENT_PERMISSION_MODE, isAgentPermissionMode, } from "./AgentPermissionMode.js";
 import { AgentProviders } from "./AgentProviders.js";
 /** Race winner when an abort interrupts a wait on the stream or a running tool. */
@@ -25,12 +29,35 @@ const insideTurn = createContextNamespace("agentInsideTurn", []);
  * its own and outlives whatever happened to start it.
  */
 const insideLoops = new AsyncLocalStorage();
+/** Persistence locks held by the current asynchronous call chain, independent of Context. */
+const insidePersistenceLocks = new AsyncLocalStorage();
 /**
  * How long a close asked for from inside the agent's own run loop waits for the shutdown before
  * telling its caller it cannot be waited for. Long enough that a caller which has already let go
  * hears the shutdown finish, short enough that one still holding the loop is told promptly.
  */
 const INSIDE_CLOSE_REPORT_MS = 15;
+const storedToolCallSchema = Type.Object({
+    id: cuid2Schema,
+    providerCallId: Type.String(),
+    call: Type.Object({
+        type: Type.Literal("tool_call"),
+        name: Type.String(),
+        arguments: Type.String(),
+        namespace: Type.Optional(Type.String()),
+        incomplete: Type.Optional(Type.Boolean()),
+        vendor: Type.Optional(Type.Unknown()),
+    }),
+    committed: Type.Optional(Type.Unknown()),
+});
+/** A durable first-writer-wins claim on the result one call will append. */
+const storedToolResultSchema = Type.Object({
+    role: Type.Literal("tool"),
+    callId: Type.String(),
+    content: Type.Array(Type.Unknown()),
+    isError: Type.Optional(Type.Boolean()),
+    vendor: Type.Optional(Type.Unknown()),
+});
 /**
  * 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
@@ -114,7 +141,7 @@ const INSIDE_CLOSE_REPORT_MS = 15;
  * running under rather than being told.
  *
  * The loop enforces nothing. It has no idea what any particular tool touches, and a runtime that
- * guessed would be wrong about tools it has never seen. Enforcement belongs to the features and
+ * guessed would be wrong about tools it has never seen. Enforcement belongs to the modules and
  * tools that do know; the loop's whole part is to carry the mode, make its changes durable, and
  * report them.
  *
@@ -203,6 +230,8 @@ export class AgentBase {
     #baseCtx;
     /** The base context extended with the effective selection and the agent's key-value store. */
     #ctx;
+    /** The immutable configuration snapshot carried by every hook context. */
+    #config;
     /** The registry the provider ID is resolved through, each time a session is created. */
     #providers;
     /** The registry ID of the provider in force; durable, so a restart resumes on the same one. */
@@ -282,6 +311,13 @@ export class AgentBase {
      * about the agent is answered from here without touching the disk.
      */
     #pending;
+    /** Stable Base-owned lifecycle identities persisted as part of the pending run. */
+    #loopId;
+    #turnId;
+    #inferenceId;
+    #settlementId;
+    /** The durable settlement awaiting its post-commit observing hook. */
+    #settlement;
     /**
      * The pending state this instance last wrote, so a write that would change nothing is
      * skipped. The loop passes through the same stage many times in a turn, and a store is not
@@ -319,6 +355,8 @@ export class AgentBase {
     #contextTokens;
     /** Whether the current turn was cancelled before it could finish. */
     #turnAborted = false;
+    /** A staged tool result could not settle, so this run must leave its pending state intact. */
+    #durableWorkBlocked = false;
     /** Whether something has asked for a turn that has not been answered yet. */
     #turnRequested = false;
     /** The run loop while it is running; the field is cleared once it has actually stopped. */
@@ -343,6 +381,8 @@ export class AgentBase {
      * owners of one session at once.
      */
     #streamCleanup = new Set();
+    /** IDs offered by this process, for immediate self-reentrant acceptance answers. */
+    #offeredMessageIds = new Set();
     /**
      * A new agent, wired to its options and touching no storage at all. Use this for an identity
      * with no durable state yet; whatever the agent needs from the store is read by its first
@@ -388,11 +428,16 @@ export class AgentBase {
      * by, so reading it here leaves the later stage writes nothing to learn from the store.
      */
     async #loadPendingState() {
-        await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+        await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            await this.#loadConfig(lockCtx);
             const stored = await agentBasePendingStateOf(lockCtx, this.#persistence);
             this.#inherited = stored;
             this.#inheritedRead = true;
             this.#pending = stored;
+            this.#loopId = stored?.loopId;
+            this.#turnId = stored?.turnId;
+            this.#inferenceId = stored?.inferenceId;
+            this.#settlementId = stored?.settlementId;
             this.#pendingWritten =
                 stored === undefined ? undefined : deterministicStringify(stored);
         });
@@ -405,10 +450,11 @@ export class AgentBase {
      */
     constructor(ctx, options) {
         this.id = options.id;
+        this.#config = ownAgentConfig(agentConfig(ctx) ?? {});
         // An agent is its own lifetime. Whatever call happened to construct it — a tool of
         // another agent, most often — is not a loop this one runs inside, so an inherited
         // marker is dropped rather than carried into work that outlives that call.
-        this.#baseCtx = insideTurn.set(ctx, [options.id]);
+        this.#baseCtx = withoutAgentStorageTransaction(withAgentDatabase(withAgentConfig(insideTurn.set(ctx, [options.id]), this.#config), options.persistence.database));
         this.#providers = options.providers;
         this.#providerId = options.provider;
         this.#persistence = options.persistence;
@@ -436,8 +482,24 @@ export class AgentBase {
      * the selection changes.
      */
     #deriveCtx() {
-        const ctx = withAgentContext(this.#baseCtx, this.#selection());
-        return withAgentRunKV(withAgentKV(ctx, this.#kv), this.#runKV);
+        return this.#hookContext(this.#baseCtx);
+    }
+    /** Add this agent's selection and stores to a caller context without losing its transaction. */
+    #hookContext(ctx) {
+        const selected = withAgentContext(ctx, this.#selection());
+        const database = agentDatabase(ctx) ?? this.#persistence.database;
+        return withAgentRunKV(withAgentKV(withAgentDatabase(selected, database), this.#kv), this.#runKV);
+    }
+    /** Load a directly owned configuration written by `updateMetadata`, when one exists. */
+    async #loadConfig(ctx) {
+        const stored = await this.#persistence.readValues(ctx, "agentConfig");
+        const exact = stored.find(({ key }) => key === "agentConfig")?.value;
+        if (exact === undefined)
+            return;
+        const config = ownAgentConfig(exact);
+        this.#config = config;
+        this.#baseCtx = withAgentConfig(this.#baseCtx, config);
+        this.#ctx = this.#deriveCtx();
     }
     /** Everything about what the agent is currently running on, as one value to carry. */
     #selection() {
@@ -465,7 +527,8 @@ 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, force = false) {
+    async #recordPending(ctx, stage, force = false) {
+        const pending = this.#pendingState(stage);
         const serialized = deterministicStringify(pending);
         if (!force && this.#pendingWritten === serialized)
             return;
@@ -473,6 +536,17 @@ export class AgentBase {
         this.#pending = pending;
         this.#pendingWritten = serialized;
     }
+    /** The complete durable lifecycle identity state for one outstanding stage. */
+    #pendingState(stage) {
+        this.#loopId ??= createId();
+        return {
+            stage,
+            loopId: this.#loopId,
+            ...(this.#turnId === undefined ? {} : { turnId: this.#turnId }),
+            ...(this.#inferenceId === undefined ? {} : { inferenceId: this.#inferenceId }),
+            ...(this.#settlementId === undefined ? {} : { settlementId: this.#settlementId }),
+        };
+    }
     /**
      * Record the stage the run has reached, taking the store lock when not already inside it.
      *
@@ -482,27 +556,27 @@ export class AgentBase {
      * starting here.
      */
     async #enterStage(stage, transact) {
-        const pending = { stage };
+        const pending = this.#pendingState(stage);
         if (transact === undefined &&
             deterministicStringify(pending) === this.#pendingWritten &&
             this.#inheritedRead) {
             return undefined;
         }
         try {
-            return await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            return await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                 if (!this.#inheritedRead) {
                     this.#inheritedRead = true;
                     this.#inherited = await agentBasePendingStateOf(lockCtx, this.#persistence);
                 }
                 if (transact === undefined) {
-                    await this.#recordPending(lockCtx, pending);
+                    await this.#recordPending(lockCtx, stage);
                     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);
+                    await this.#recordPending(txCtx, stage, true);
                     return await this.#withTransactionalContext(txCtx, transact);
                 });
             });
@@ -528,22 +602,64 @@ export class AgentBase {
     /**
      * Queue a user message that injects as soon as the current assistant response and its tool
      * batch finish; steering always takes precedence over sent messages. Returns once the message
-     * has been handed to the agent, which never waits for the turn that answers it; with
-     * `await: true` it returns once the durable write has landed instead, and a failed write both
-     * rejects and keeps the message out of the conversation entirely.
+     * has been handed to the agent and returns its acceptance identity. Outside the target's own
+     * loop it waits for the durable created/existing result by default; a failed write rejects and
+     * keeps the message out of the conversation entirely.
      */
     async steer(ctx, message, options) {
-        await this.#offer(ctx, "steering", message, options);
+        return await this.#offer(ctx, "steering", message, options);
     }
     /**
      * Queue a user message that waits until the agent would otherwise stop — no tool calls or
      * steering remain — before injecting. Returns once the message has been handed to the agent,
-     * which never waits for the turn that answers it; with `await: true` it returns once the
-     * durable write has landed instead, and a failed write both rejects and keeps the message out
-     * of the conversation entirely.
+     * without waiting for the turn that answers it and returns its acceptance identity. Outside
+     * the target's own loop it waits for the durable created/existing result by default; a failed
+     * write rejects and keeps the message out of the conversation entirely.
      */
     async send(ctx, message, options) {
-        await this.#offer(ctx, "send", message, options);
+        return await this.#offer(ctx, "send", message, options);
+    }
+    /**
+     * Shallow-merge fields into this agent's immutable metadata. The complete AgentConfig and
+     * transactional hook writes commit together; observing hooks run only after that commit.
+     */
+    async updateMetadata(ctx, update) {
+        this.#assertOutsideStorageTransaction(ctx, "metadata update");
+        const ownedUpdate = ownAgentMetadata(update);
+        if (ownedUpdate === undefined)
+            throw new Error("The agent metadata is not valid.");
+        if (this.#closed)
+            throw new Error("The agent has been closed.");
+        if (insideTurn.get(ctx).includes(this.id) ||
+            this.#insideOwnLoop() ||
+            this.#insideOwnPersistenceLock()) {
+            throw new Error("Updating metadata from inside this agent's current operation would wait for " +
+                "that same operation to finish. Update it after the hook or tool returns.");
+        }
+        let change;
+        let next;
+        await this.#runInPersistenceLock(ctx, async (lockCtx) => {
+            const previousMetadata = ownAgentMetadata(this.#config.metadata ?? {});
+            const metadata = ownAgentMetadata({ ...previousMetadata, ...ownedUpdate });
+            if (previousMetadata === undefined || metadata === undefined) {
+                throw new Error("The agent metadata is not valid.");
+            }
+            next = ownAgentConfig({ ...this.#config, metadata });
+            change = {
+                agentId: this.id,
+                previousMetadata,
+                update: ownedUpdate,
+                metadata,
+            };
+            await this.#persistence.transaction(lockCtx, async (txCtx) => {
+                await this.#persistence.writeValue(txCtx, "agentConfig", next);
+                await this.#withTransactionalContext(withAgentConfig(txCtx, next), async (hookCtx) => await this.#hooks.metadataChangedTransact?.(this.#hookContext(hookCtx), change));
+            });
+            this.#config = next;
+            this.#baseCtx = withAgentConfig(this.#baseCtx, next);
+            this.#ctx = this.#deriveCtx();
+        });
+        await this.#invokeHookOn(this.#hookContext(withAgentConfig(ctx, next)), this.#hooks.metadataChanged, change);
     }
     /**
      * Hand one message to a durable queue. The acceptance runs whether or not the caller waits
@@ -551,16 +667,52 @@ export class AgentBase {
      * the agent's own close still drains it, so nothing is dropped by not looking.
      */
     async #offer(ctx, kind, message, options) {
-        const { await: wait = false, ...settings } = options ?? {};
+        this.#assertOutsideStorageTransaction(ctx, "message delivery");
+        const { await: requestedWait, id = createId(), metadata: suppliedMetadata, ...settings } = options ?? {};
+        if (!Value.Check(cuid2Schema, id)) {
+            throw new Error("The message ID must be a cuid2 identity.");
+        }
+        const wait = requestedWait ?? !insideTurn.get(ctx).includes(this.id);
+        const metadata = ownAgentMessageMetadata(suppliedMetadata);
         // Refusing the flag rather than the operation: a closed agent and a re-entrant wait are
         // both caller mistakes, and both are reported before any work is started.
         this.#assertCanWait(ctx, wait, kind === "steering" ? "a steered message" : "a sent message");
         if (this.#closed)
             throw new Error("The agent has been closed.");
-        const accepted = this.#enqueue(ctx, [{ kind, message, options: settings }]);
-        if (wait)
-            return accepted;
-        accepted.catch(() => undefined);
+        const knownInProcess = this.#offeredMessageIds.has(id);
+        this.#offeredMessageIds.add(id);
+        const accepted = this.#enqueue(ctx, [
+            {
+                kind,
+                id,
+                message: structuredClone(message),
+                ...(metadata === undefined ? {} : { metadata }),
+                options: settings,
+            },
+        ]);
+        if (wait) {
+            try {
+                const [result] = await accepted;
+                if (result === undefined) {
+                    throw new Error("The message acceptance result was lost.");
+                }
+                return result;
+            }
+            catch (error) {
+                if (!knownInProcess)
+                    this.#offeredMessageIds.delete(id);
+                throw error;
+            }
+        }
+        accepted.catch(() => {
+            if (!knownInProcess)
+                this.#offeredMessageIds.delete(id);
+        });
+        return {
+            id,
+            delivery: kind === "steering" ? "steer" : "send",
+            accepted: knownInProcess ? "existing" : "created",
+        };
     }
     /**
      * Refuse a wait that could never end. A hook or a tool runs while its agent's loop waits for
@@ -585,6 +737,25 @@ export class AgentBase {
     #insideOwnLoop() {
         return insideLoops.getStore()?.includes(this.id) === true;
     }
+    /** Whether this call chain already holds this agent's persistence lock. */
+    #insideOwnPersistenceLock() {
+        return insidePersistenceLocks.getStore()?.includes(this.id) === true;
+    }
+    /** Live agent commands cannot be staged or undone by an enclosing database transaction. */
+    #assertOutsideStorageTransaction(ctx, operation) {
+        if (agentStorageTransaction(ctx) !== undefined) {
+            throw new Error(`Agent ${operation} cannot run from inside an outer storage transaction.`);
+        }
+    }
+    /** Hold the persistence lock while marking it independently of the caller's Context. */
+    async #runInPersistenceLock(ctx, work) {
+        return await this.#persistenceLock.runInLock(ctx, async (lockCtx) => {
+            const held = insidePersistenceLocks.getStore() ?? [];
+            return await insidePersistenceLocks.run([...held, this.id], async () => {
+                return await work(lockCtx);
+            });
+        });
+    }
     /**
      * Accept a batch of messages as one durable step. Every message is written under the same
      * hold of the persistence lock and inside one transaction, so a caller arriving while a
@@ -593,40 +764,68 @@ export class AgentBase {
      */
     async #enqueue(ctx, batch) {
         if (batch.length === 0)
-            return;
+            return [];
         if (this.#closed)
             throw new Error("The agent has been closed.");
         // Admitted: from here on the messages are the agent's responsibility, and a close that
         // begins now waits for them rather than resolving over the top of them.
-        const admitted = this.#persistenceLock.runInLock(ctx, async (lockCtx) => {
+        const admitted = this.#runInPersistenceLock(ctx, async (lockCtx) => {
             const accepted = [];
-            await this.#persistence.transaction(lockCtx, async (txCtx) => {
+            const results = [];
+            await this.#recordTransaction(lockCtx, async (txCtx) => {
                 for (const request of batch) {
+                    const identityKey = `message.${request.id}`;
+                    if (!(await this.#persistence.writeValueIfAbsent(txCtx, identityKey, true))) {
+                        results.push({
+                            id: request.id,
+                            delivery: request.kind === "steering" ? "steer" : "send",
+                            accepted: "existing",
+                        });
+                        continue;
+                    }
                     const key = await this.#queueKey(txCtx, `${request.kind}.`);
                     await this.#persistence.writeValue(txCtx, key, {
+                        id: request.id,
                         message: request.message,
+                        ...(request.metadata === undefined ? {} : { metadata: request.metadata }),
                         options: request.options,
                     });
                     accepted.push({ key, request });
+                    results.push({
+                        id: request.id,
+                        delivery: request.kind === "steering" ? "steer" : "send",
+                        accepted: "created",
+                    });
                 }
+                if (accepted.length === 0)
+                    return;
                 // Accepting a message is what makes the work owed: the same transaction that
                 // admits it records that the agent owes an answer, so a process that dies right
                 // here is discovered still owing it rather than looking idle over a full queue.
-                await this.#recordPending(txCtx, { stage: "inference" });
+                await this.#recordPending(txCtx, "inference");
             });
             for (const { key, request } of accepted) {
                 // The queue is resolved inside the lock: a history load running just before this
                 // one replaces the queue arrays wholesale, and a reference taken before the wait
                 // would push the message into an array nobody reads again.
                 const queue = request.kind === "steering" ? this.#steering : this.#sends;
-                queue.push({ key, message: request.message, options: request.options });
+                queue.push({
+                    key,
+                    id: request.id,
+                    message: request.message,
+                    ...(request.metadata === undefined ? {} : { metadata: request.metadata }),
+                    options: request.options,
+                });
             }
-            this.#turnRequested = true;
-            this.#startRun();
+            if (accepted.length > 0) {
+                this.#turnRequested = true;
+                this.#startRun();
+            }
+            return results;
         });
         this.#admitted.add(admitted);
         try {
-            await admitted;
+            return await admitted;
         }
         finally {
             this.#admitted.delete(admitted);
@@ -665,6 +864,7 @@ export class AgentBase {
      * compaction rather than queueing another.
      */
     async compact(ctx, options) {
+        this.#assertOutsideStorageTransaction(ctx, "compaction");
         const wait = options?.await ?? false;
         this.#assertCanWait(ctx, wait, "a compaction");
         if (this.#closed)
@@ -790,6 +990,7 @@ export class AgentBase {
      * when it finished.
      */
     async abort(ctx, options) {
+        this.#assertOutsideStorageTransaction(ctx, "abort");
         const wait = options?.await ?? false;
         this.#assertCanWait(ctx, wait, "an abort");
         const run = this.#signalAbort();
@@ -932,9 +1133,20 @@ export class AgentBase {
      * more work, so the loop hooks always bracket a settled-to-settled span.
      */
     async #runLoop() {
+        if (this.#pending?.stage === "settlement") {
+            this.#loopId ??= createId();
+            this.#settlementId ??= createId();
+            await this.#settleDurably({
+                loopId: this.#loopId,
+                settlementId: this.#settlementId,
+            });
+            return;
+        }
         // The outer loop reopens when an `afterAgentLoop` action requests more work, so the
         // loop hooks always bracket a settled-to-settled span.
         do {
+            this.#loopId ??= createId();
+            const loop = { loopId: this.#loopId };
             // The abort scope opens before the loop hook, not just before the turn. An abort
             // owns everything the run does — its opening hook as much as its inference — so a
             // run cancelled while it is still starting up never reaches the model at all.
@@ -943,10 +1155,14 @@ 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", this.#hooks.beforeAgentLoopTransact);
-            await this.#invokeHook(this.#hooks.beforeAgentLoop);
+            await this.#enterStage("inference", this.#hooks.beforeAgentLoopTransact === undefined
+                ? undefined
+                : (hookCtx) => this.#hooks.beforeAgentLoopTransact?.(hookCtx, loop));
+            await this.#invokeHook(this.#hooks.beforeAgentLoop, loop);
             do {
                 this.#turnAborted = false;
+                this.#durableWorkBlocked = false;
+                this.#turnId ??= createId();
                 // Claimed before any awaiting, so a request raised while the turn is still
                 // starting up survives into another turn instead of being cleared by it. The
                 // redundant turn this can cost is cheap: an empty queue drains without any
@@ -962,7 +1178,7 @@ export class AgentBase {
                 // durable exactly as it was for the next attempt.
                 const loadFailure = await this.#ensureLoaded().then(() => undefined, (error) => error);
                 if (loadFailure !== undefined) {
-                    this.#emit({
+                    await this.#emit({
                         type: "done",
                         state: "error",
                         kind: "internal_error",
@@ -970,9 +1186,12 @@ export class AgentBase {
                             ? loadFailure.message
                             : String(loadFailure),
                     });
+                    this.#turnId = undefined;
                     break;
                 }
                 const turnStart = {
+                    loopId: loop.loopId,
+                    turnId: this.#turnId,
                     contextTokens: this.#contextTokens,
                 };
                 await this.#enterStage("inference", this.#hooks.beforeTurnTransact === undefined
@@ -980,13 +1199,25 @@ export class AgentBase {
                     : (hookCtx) => this.#hooks.beforeTurnTransact?.(hookCtx, turnStart));
                 await this.#applyActions(this.#hooks.beforeTurn, abort.signal, turnStart);
                 await this.#runInference(abort);
+                if (this.#durableWorkBlocked)
+                    return;
                 const turn = {
+                    loopId: loop.loopId,
+                    turnId: turnStart.turnId,
                     contextTokens: this.#contextTokens,
                     aborted: this.#turnAborted,
                 };
-                await this.#enterStage("inference", this.#hooks.afterTurnTransact === undefined
-                    ? undefined
-                    : (hookCtx) => this.#hooks.afterTurnTransact?.(hookCtx, turn));
+                const completedTurnId = this.#turnId;
+                this.#turnId = undefined;
+                try {
+                    await this.#enterStage("inference", this.#hooks.afterTurnTransact === undefined
+                        ? undefined
+                        : (hookCtx) => this.#hooks.afterTurnTransact?.(hookCtx, turn));
+                }
+                catch (error) {
+                    this.#turnId = completedTurnId;
+                    throw error;
+                }
                 await this.#applyActions(this.#hooks.afterTurn, abort.signal, turn);
                 if (!this.#turnRequested || this.#closed)
                     break;
@@ -994,14 +1225,21 @@ export class AgentBase {
                 // 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);
+            await this.#enterStage("inference", this.#hooks.afterAgentLoopTransact === undefined
+                ? undefined
+                : (hookCtx) => this.#hooks.afterAgentLoopTransact?.(hookCtx, loop));
+            await this.#applyActions(this.#hooks.afterAgentLoop, abort.signal, loop);
         } while (this.#turnRequested && !this.#closed);
         // Nothing is asked for any more, so the outstanding work is erased. That erasure is what
         // makes the agent idle, and it commits together with whatever the settling hooks write,
         // so no owner can ever see the agent finished without their conclusions or their
         // conclusions without the agent being finished.
-        await this.#settleDurably();
+        this.#settlementId ??= createId();
+        await this.#enterStage("settlement");
+        await this.#settleDurably({
+            loopId: this.#loopId ?? createId(),
+            settlementId: this.#settlementId,
+        });
     }
     /**
      * Erase the outstanding work and let the transactional settling hooks write in the same
@@ -1009,17 +1247,22 @@ export class AgentBase {
      * is resumed and finds nothing to do, while one wrongly believed to be finished is never
      * resumed at all.
      */
-    async #settleDurably() {
+    async #settleDurably(settlement) {
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+            await this.#runInPersistenceLock(this.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 await this.#clearPending(txCtx);
-                await this.#invokeTransactionalSettle(txCtx);
+                await this.#invokeTransactionalSettle(txCtx, settlement);
                 // The run store is erased last, so a settling hook can still read what the
                 // run concluded and keep whatever part of it belongs to the conversation.
                 // It commits with the settlement: the run is over and its notes are gone as
                 // one fact, never one without the other.
                 await this.#clearRunStore(txCtx);
             }));
+            this.#loopId = undefined;
+            this.#turnId = undefined;
+            this.#inferenceId = undefined;
+            this.#settlementId = undefined;
+            this.#settlement = settlement;
         }
         catch {
             // The run itself is over and succeeded; only the record of its ending failed.
@@ -1032,11 +1275,11 @@ export class AgentBase {
      * with it, because a hook here is writing a conclusion about the very fact being committed,
      * and half of that pair is worse than neither.
      */
-    async #invokeTransactionalSettle(txCtx) {
+    async #invokeTransactionalSettle(txCtx, settlement) {
         const hook = this.#hooks.afterAgentSettledTransact;
         if (hook === undefined)
             return;
-        await this.#withTransactionalContext(insideTurn.set(txCtx, []), hook);
+        await this.#withTransactionalContext(insideTurn.set(txCtx, []), (liveCtx) => hook(liveCtx, settlement));
     }
     /**
      * Erase everything the run wrote about itself, inside the transaction that settles the agent:
@@ -1069,7 +1312,11 @@ export class AgentBase {
             // The settle runs once the loop has stopped, so its hook is not inside a turn and
             // its context does not claim to be: a compaction it waits for reaches a loop that
             // can still be started.
-            await this.#invokeHookOn(insideTurn.set(this.#ctx, []), this.#hooks.afterAgentSettled);
+            const settlement = this.#settlement;
+            if (settlement !== undefined) {
+                await this.#invokeHookOn(insideTurn.set(this.#ctx, []), this.#hooks.afterAgentSettled, settlement);
+                this.#settlement = undefined;
+            }
         })();
         this.#admitted.add(announced);
         void announced.finally(() => this.#admitted.delete(announced));
@@ -1088,7 +1335,7 @@ export class AgentBase {
         await this.#invokeHookOn(this.#ctx, hook, ...args);
     }
     /**
-     * Lend a hook the transaction's context and feature stores for exactly one callback. Keeping
+     * Lend a hook the transaction's context and module stores for exactly one callback. Keeping
      * the context after the callback cannot leak a transaction past its commit.
      */
     async #withTransactionalContext(txCtx, work) {
@@ -1164,9 +1411,21 @@ export class AgentBase {
                 this.#ensureCompaction().catch(() => undefined);
                 continue;
             }
+            const id = action.id ?? createId();
+            if (!Value.Check(cuid2Schema, id))
+                continue;
+            let metadata;
+            try {
+                metadata = ownAgentMessageMetadata(action.metadata);
+            }
+            catch {
+                continue;
+            }
             batch.push({
                 kind: action.type === "steer" ? "steering" : "send",
-                message: action.message,
+                id,
+                message: structuredClone(action.message),
+                ...(metadata === undefined ? {} : { metadata }),
                 options: {},
             });
         }
@@ -1213,7 +1472,8 @@ export class AgentBase {
             let needsInference = resumed.length > 0;
             if (!this.#recoveryChecked) {
                 this.#recoveryChecked = true;
-                needsInference ||= this.#resumesInterruptedRun();
+                if (await this.#resumesInterruptedRun())
+                    needsInference = true;
             }
             // Each cycle first drains the queues, then runs one inference. Steering injects at
             // every stop between responses and always outranks sends; sent messages inject
@@ -1232,7 +1492,7 @@ export class AgentBase {
                 if (abort.signal.aborted) {
                     const hasPendingWork = needsInference || this.#steering.length > 0 || this.#sends.length > 0;
                     if (hasPendingWork)
-                        this.#emit({ type: "done", state: "cancelled" });
+                        await this.#emit({ type: "done", state: "cancelled" });
                     break;
                 }
                 let injected = await this.#consumeQueue(this.#steering, this.#steeringMode, "steering");
@@ -1251,8 +1511,19 @@ 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);
+                this.#inferenceId ??= createId();
+                const inferenceStart = {
+                    loopId: this.#loopId ?? createId(),
+                    turnId: this.#turnId ?? createId(),
+                    inferenceId: this.#inferenceId,
+                    contextTokens: this.#contextTokens,
+                };
+                this.#loopId = inferenceStart.loopId;
+                this.#turnId = inferenceStart.turnId;
+                await this.#enterStage("inference", this.#hooks.beforeInferenceTransact === undefined
+                    ? undefined
+                    : (hookCtx) => this.#hooks.beforeInferenceTransact?.(hookCtx, inferenceStart));
+                await this.#invokeHook(this.#hooks.beforeInference, inferenceStart);
                 const stream = session.run(this.#ctx, {
                     context: {
                         instructions,
@@ -1266,6 +1537,7 @@ export class AgentBase {
                 // A cancelled or failed response measures nothing, so the conversation keeps
                 // the last real measurement instead of forgetting how large it had become.
                 const inference = {
+                    ...inferenceStart,
                     state,
                     tokens,
                     ...(errorMessage === undefined ? {} : { errorMessage }),
@@ -1273,11 +1545,19 @@ export class AgentBase {
                 const afterInferenceTransact = this.#hooks.afterInferenceTransact === undefined
                     ? undefined
                     : (hookCtx) => this.#hooks.afterInferenceTransact?.(hookCtx, inference);
-                if (tokens === undefined) {
-                    await this.#enterStage("inference", afterInferenceTransact);
+                const completedInferenceId = this.#inferenceId;
+                this.#inferenceId = undefined;
+                try {
+                    if (tokens === undefined) {
+                        await this.#enterStage("inference", afterInferenceTransact);
+                    }
+                    else {
+                        await this.#recordContextTokens(tokens.input + tokens.output, afterInferenceTransact);
+                    }
                 }
-                else {
-                    await this.#recordContextTokens(tokens.input + tokens.output, afterInferenceTransact);
+                catch (error) {
+                    this.#inferenceId = completedInferenceId;
+                    throw error;
                 }
                 await this.#invokeHook(this.#hooks.afterInference, inference);
                 if (content.length > 0) {
@@ -1299,10 +1579,7 @@ export class AgentBase {
                     const calls = content.filter((block) => block.type === "tool_call" && block.server !== true);
                     if (calls.length === 0)
                         continue;
-                    const closedDuringTools = await this.#runToolBatch(calls.map((call, index) => ({
-                        key: this.#toolKey(index, call.callId),
-                        call,
-                    })), false, abort.signal, abortPromise);
+                    const closedDuringTools = await this.#runToolBatch(calls.map((call, index) => this.#newToolEntry(index, call)), false, abort.signal, abortPromise);
                     if (closedDuringTools)
                         break;
                     needsInference = true;
@@ -1323,7 +1600,7 @@ export class AgentBase {
             }
         }
         catch (error) {
-            this.#emit({
+            await this.#emit({
                 type: "done",
                 state: "error",
                 kind: "internal_error",
@@ -1350,12 +1627,13 @@ export class AgentBase {
      * beginning of a block that will now never arrive is told to drop it. Only finished blocks
      * are persisted, so the conversation is intact and it is the view being corrected.
      */
-    #resumesInterruptedRun() {
+    async #resumesInterruptedRun() {
         const owed = this.#lastRecordType === "user" ||
             this.#lastRecordType === "tool" ||
             this.#lastRecordType === "system";
-        if (owed && this.#inherited?.stage === "inference")
-            this.#emit({ type: "block_reset" });
+        if (owed && this.#inherited?.stage === "inference") {
+            await this.#emit({ type: "block_reset" });
+        }
         return owed;
     }
     /** Load the durable state once. A failed load is not sticky: the next turn retries it. */
@@ -1375,7 +1653,7 @@ export class AgentBase {
         const previousTokens = this.#contextTokens;
         this.#contextTokens = tokens;
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                 const write = (writeCtx) => tokens === undefined
                     ? this.#persistence.deleteValue(writeCtx, "context")
                     : this.#persistence.writeValue(writeCtx, "context", { tokens });
@@ -1385,6 +1663,7 @@ export class AgentBase {
                 }
                 await this.#recordTransaction(lockCtx, async (txCtx) => {
                     await write(txCtx);
+                    await this.#recordPending(txCtx, "inference", true);
                     await this.#withTransactionalContext(txCtx, transact);
                 });
             });
@@ -1426,10 +1705,11 @@ export class AgentBase {
                 throw new Error(result.message);
             }
             if (result.status === "completed") {
-                await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                     // 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.#deleteMessageIdentities(txCtx, await this.#persistence.load(txCtx));
                         await this.#persistence.clearRecords(txCtx);
                         await this.#persistence.append(txCtx, {
                             type: "compaction",
@@ -1468,32 +1748,55 @@ export class AgentBase {
         if (owed.length === 0)
             return true;
         let settled = false;
+        let staged = false;
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                 // A call the durable batch still holds belongs to the resume, which answers it
                 // properly — and re-executes it when the tool is durable. Settling it here as
                 // well would give the conversation two results for one call.
                 const pending = await this.#persistence.readValues(lockCtx, "tool.");
-                const dispatched = new Set(pending.map(({ value }) => value.callId));
-                const results = owed
-                    .filter((call) => !dispatched.has(call.callId))
-                    .map((call) => toolFailure(call.callId, reason));
-                if (results.length === 0)
+                const dispatched = new Set(pending.map(({ key, value }) => this.#restoreToolEntry(key, value).providerCallId));
+                if (owed.some((call) => dispatched.has(call.callId))) {
+                    settled = true;
                     return;
+                }
+                const entries = owed.map((call, index) => {
+                    const entry = this.#newToolEntry(index, call);
+                    return {
+                        ...entry,
+                        committed: toolFailure(entry.providerCallId, reason),
+                    };
+                });
+                // Give every otherwise-undispatched call a durable internal identity and staged
+                // result first. If the settlement transaction below fails, restart resumes these
+                // exact entries and commits their staged errors without executing the tools.
+                await this.#recordTransaction(lockCtx, async (txCtx) => {
+                    for (const entry of entries) {
+                        await this.#persistence.writeValue(txCtx, entry.key, this.#storedToolEntry(entry));
+                    }
+                    await this.#recordPending(txCtx, "tools");
+                });
+                staged = true;
                 await this.#recordTransaction(lockCtx, async (txCtx) => {
-                    for (const result of results) {
+                    for (const entry of entries) {
+                        const result = entry.committed;
                         await this.#appendRecord(txCtx, { type: "tool", message: result });
+                        await this.#persistence.deleteValue(txCtx, entry.key);
                         // A result the conversation records is a result the hook sees, however
                         // little of a run produced it. A hook that fails here leaves the calls
                         // unsettled, which is what lets a later attempt answer them properly.
-                        await this.#invokeToolTransactHook(txCtx, result.callId, this.#hooks.afterToolCallTransact, result);
+                        await this.#invokeToolTransactHook(txCtx, entry.id, entry.providerCallId, this.#hooks.afterToolCallTransact, result);
+                        await this.#kv.scoped("call", entry.id).clear(txCtx);
                     }
+                    await this.#recordPending(txCtx, "inference");
                 });
-                this.#messages.push(...results);
+                this.#messages.push(...entries.map(({ committed }) => committed));
+                settled = true;
             });
-            settled = true;
         }
         catch {
+            if (staged)
+                this.#durableWorkBlocked = true;
             // The turn is already failing; a restart settles what this could not, as long as
             // nothing is written over the top of the call in the meantime.
         }
@@ -1505,6 +1808,15 @@ export class AgentBase {
     async #appendRecord(ctx, record) {
         await this.#persistence.append(ctx, record);
     }
+    /** Remove deduplication identities for user records a history replacement is deleting. */
+    async #deleteMessageIdentities(ctx, records) {
+        for (const record of records) {
+            if (record.type === "user") {
+                await this.#persistence.deleteValue(ctx, `message.${record.id}`);
+                this.#offeredMessageIds.delete(record.id);
+            }
+        }
+    }
     /**
      * A transaction whose pending-state cache unwinds with it.
      */
@@ -1514,12 +1826,20 @@ export class AgentBase {
         // agent skip the write that actually records what it is doing.
         const pending = this.#pending;
         const written = this.#pendingWritten;
+        const loopId = this.#loopId;
+        const turnId = this.#turnId;
+        const inferenceId = this.#inferenceId;
+        const settlementId = this.#settlementId;
         try {
             return await this.#persistence.transaction(ctx, work);
         }
         catch (error) {
             this.#pending = pending;
             this.#pendingWritten = written;
+            this.#loopId = loopId;
+            this.#turnId = turnId;
+            this.#inferenceId = inferenceId;
+            this.#settlementId = settlementId;
             throw error;
         }
     }
@@ -1538,7 +1858,7 @@ export class AgentBase {
             content: [{ type: "text", text: `The last turn failed: ${message}` }],
         };
         try {
-            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                 await this.#appendRecord(lockCtx, { type: "system", message: failure });
                 this.#messages.push(failure);
             });
@@ -1561,7 +1881,7 @@ export class AgentBase {
         /** Filled in once the consumption has committed, and reported after the lock is released. */
         const accepted = [];
         let permissionChange;
-        const consumed = await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+        const consumed = await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
             if (queue.length === 0)
                 return false;
             // The durable queue, not memory, decides what is left to consume after a restart.
@@ -1605,7 +1925,7 @@ export class AgentBase {
                 }
             }
             // The mode the messages make effective, kept apart from the rest because it is the one
-            // setting with hooks of its own: a change is announced, and what a feature concludes
+            // setting with hooks of its own: a change is announced, and what a module concludes
             // from it commits with the message that carried it.
             const modeChange = permissionMode === this.#permissionMode
                 ? undefined
@@ -1698,6 +2018,7 @@ export class AgentBase {
                     await this.#persistence.deleteValue(txCtx, entry.key);
                 }
                 if (reset) {
+                    await this.#deleteMessageIdentities(txCtx, await this.#persistence.load(txCtx));
                     await this.#persistence.clearRecords(txCtx);
                     // The erased conversation is what the measurement described.
                     await this.#persistence.deleteValue(txCtx, "context");
@@ -1711,7 +2032,9 @@ export class AgentBase {
                 for (const entry of batch) {
                     await this.#appendRecord(txCtx, {
                         type: "user",
+                        id: entry.id,
                         message: entry.message,
+                        ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
                     });
                 }
                 if (changed) {
@@ -1726,7 +2049,7 @@ export class AgentBase {
                 // 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" });
+                await this.#recordPending(txCtx, "inference");
                 // Last, so a hook writing its own account of the consumption sees a transaction
                 // holding all of it. The mode comes before the messages: it is what they were
                 // said under, and a listener recording them wants to know that first.
@@ -1735,13 +2058,23 @@ export class AgentBase {
                     await this.#invokeTransactHook(txCtx, selection, this.#hooks.permissionModeChangedTransact, modeChange);
                 }
                 for (const entry of batch) {
-                    await this.#invokeTransactHook(txCtx, selection, this.#hooks.messageAcceptedTransact, { kind, message: entry.message });
+                    await this.#invokeTransactHook(txCtx, selection, this.#hooks.messageAcceptedTransact, {
+                        id: entry.id,
+                        kind,
+                        message: entry.message,
+                        ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
+                    });
                 }
             });
             // Committed: from here the messages are part of the conversation, so what has to be
             // announced about them is decided now and reported once the lock is released.
             permissionChange = modeChange;
-            accepted.push(...batch.map((entry) => ({ kind, message: entry.message })));
+            accepted.push(...batch.map((entry) => ({
+                id: entry.id,
+                kind,
+                message: entry.message,
+                ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
+            })));
             queue.splice(0, count);
             if (reset) {
                 this.#messages = injected === undefined ? [] : [injected];
@@ -1794,7 +2127,7 @@ export class AgentBase {
      * not-yet-consumed queues. Consecutive block records reassemble into one assistant message.
      */
     async #loadHistory() {
-        await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+        await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
             const records = await this.#persistence.load(lockCtx);
             const last = records[records.length - 1];
             this.#lastRecordType = last?.type;
@@ -1811,7 +2144,17 @@ export class AgentBase {
             this.#contextTokens = measured?.tokens;
             const entry = (key, value) => {
                 const envelope = value;
-                return { key, message: envelope.message, options: envelope.options ?? {} };
+                if (!Value.Check(cuid2Schema, envelope.id)) {
+                    throw new Error(`The queued message under "${key}" has an invalid ID.`);
+                }
+                const metadata = ownAgentMessageMetadata(envelope.metadata);
+                return {
+                    key,
+                    id: envelope.id,
+                    message: envelope.message,
+                    ...(metadata === undefined ? {} : { metadata }),
+                    options: envelope.options ?? {},
+                };
             };
             this.#steering = steering.map(({ key, value }) => entry(key, value));
             this.#sends = sends.map(({ key, value }) => entry(key, value));
@@ -1833,10 +2176,7 @@ export class AgentBase {
                 }
                 this.#ctx = this.#deriveCtx();
             }
-            this.#pendingTools = pendingTools.map(({ key, value }) => ({
-                key,
-                call: value,
-            }));
+            this.#pendingTools = pendingTools.map(({ key, value }) => this.#restoreToolEntry(key, value));
             this.#pendingToolsUndispatched = false;
             if (this.#pendingTools.length === 0) {
                 // A crash between the response's last block and the batch commit leaves calls
@@ -1846,10 +2186,7 @@ export class AgentBase {
                 // dispatched.
                 const owed = this.#unansweredCalls(restored);
                 if (owed.length > 0) {
-                    this.#pendingTools = owed.map((call, index) => ({
-                        key: this.#toolKey(index, call.callId),
-                        call,
-                    }));
+                    this.#pendingTools = owed.map((call, index) => this.#newToolEntry(index, call));
                     this.#pendingToolsUndispatched = true;
                 }
             }
@@ -1867,18 +2204,18 @@ export class AgentBase {
      */
     async #runToolBatch(entries, resume, signal, abortPromise) {
         if (!resume) {
-            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+            await this.#runInPersistenceLock(this.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 for (const entry of entries) {
-                    await this.#persistence.writeValue(txCtx, entry.key, entry.call);
+                    await this.#persistence.writeValue(txCtx, entry.key, this.#storedToolEntry(entry));
                 }
                 // The batch and the stage that describes it commit together. A crash can
                 // then never find calls owed with no record of a run owing them, nor a run
                 // recorded as running tools that were never written.
-                await this.#recordPending(txCtx, { stage: "tools" });
+                await this.#recordPending(txCtx, "tools");
                 // Last, so a hook noting a call about to happen sees a transaction holding
                 // the whole batch it belongs to.
                 for (const entry of entries) {
-                    await this.#invokeToolTransactHook(txCtx, entry.call.callId, this.#hooks.beforeToolCallTransact, entry.call);
+                    await this.#invokeToolTransactHook(txCtx, entry.id, entry.providerCallId, this.#hooks.beforeToolCallTransact, entry.call);
                 }
             }));
         }
@@ -1899,32 +2236,46 @@ export class AgentBase {
             if (commitFailed)
                 return;
             try {
-                await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                     while (committed < entries.length) {
                         const entry = entries[committed];
-                        const result = results[committed];
-                        if (entry === undefined || result === undefined)
+                        const proposed = results[committed];
+                        if (entry === undefined || proposed === undefined)
                             return;
+                        let winner = proposed;
                         await this.#recordTransaction(lockCtx, async (txCtx) => {
+                            const resultKey = this.#toolResultKey(entry.id);
+                            await this.#persistence.writeValueIfAbsent(txCtx, resultKey, proposed);
+                            const claims = await this.#persistence.readValues(txCtx, resultKey);
+                            const stored = claims.find(({ key }) => key === resultKey)?.value;
+                            if (!Value.Check(storedToolResultSchema, stored)) {
+                                throw new Error(`The committed result claim for tool "${entry.id}" is not valid.`);
+                            }
+                            const result = stored;
+                            if (result.callId !== entry.providerCallId) {
+                                throw new Error(`The committed result claim for tool "${entry.id}" has the wrong provider call ID.`);
+                            }
+                            winner = result;
+                            results[committed] = result;
                             await this.#appendRecord(txCtx, {
                                 type: "tool",
                                 message: result,
                             });
-                            // The call is answered, so what was kept only to let it be retried
-                            // goes with it. What the tool itself wrote under its own call scope
-                            // stays: that is the tool's state, not the batch's bookkeeping, and
-                            // an owner may still want to read what a finished call recorded.
+                            // The call is answered, so both its retry record and its temporary
+                            // invocation store disappear in this same result transaction.
                             await this.#persistence.deleteValue(txCtx, entry.key);
-                            await this.#invokeToolTransactHook(txCtx, entry.call.callId, this.#hooks.afterToolCallTransact, result);
+                            await this.#persistence.deleteValue(txCtx, resultKey);
+                            await this.#invokeToolTransactHook(txCtx, entry.id, entry.providerCallId, this.#hooks.afterToolCallTransact, result);
+                            await this.#kv.scoped("call", entry.id).clear(txCtx);
                         });
-                        this.#messages.push(result);
+                        this.#messages.push(winner);
                         committed += 1;
                     }
                     // The batch is fully answered, so its results are what the model is owed a
                     // response to. Recording that here means a crash between the last result and
                     // the next request resumes as an inference rather than as a finished batch.
                     if (committed === entries.length) {
-                        await this.#recordPending(lockCtx, { stage: "inference" });
+                        await this.#recordPending(lockCtx, "inference");
                     }
                 });
             }
@@ -1936,12 +2287,15 @@ export class AgentBase {
         this.#toolsRunning += 1;
         const batch = Promise.all(entries.map(async (entry, index) => {
             let outcome;
-            if (resume && !(await this.#isDurable(entry.call))) {
+            if (entry.committed !== undefined) {
+                outcome = entry.committed;
+            }
+            else if (resume && !(await this.#isDurable(entry.call))) {
                 outcome = toolFailure(entry.call.callId, "The tool call was interrupted by a restart and was not retried.");
             }
             else {
                 const toolLifetime = AbortSignal.any([signal, this.#closeController.signal]);
-                const execution = this.#executeToolCall(withLifetime(this.#ctx, toolLifetime), entry.call);
+                const execution = this.#executeToolCall(withLifetime(this.#ctx, toolLifetime), entry);
                 running.push(execution);
                 outcome = await Promise.race([execution, abortPromise, this.#closingTools()]);
             }
@@ -2008,29 +2362,77 @@ export class AgentBase {
             return [];
         return last.content.filter((block) => block.type === "tool_call" && block.server !== true);
     }
+    /** Allocate one internal identity before the call becomes durable or executable. */
+    #newToolEntry(index, call) {
+        const id = createId();
+        return {
+            key: this.#toolKey(index, id),
+            id,
+            providerCallId: call.callId,
+            call,
+        };
+    }
+    /** Restore the exact internal/provider identity pair that was dispatched before a restart. */
+    #restoreToolEntry(key, value) {
+        if (!Value.Check(storedToolCallSchema, value)) {
+            throw new Error(`The pending tool call under "${key}" is not valid.`);
+        }
+        const stored = value;
+        if (stored.committed !== undefined &&
+            !Value.Check(storedToolResultSchema, stored.committed)) {
+            throw new Error(`The committed result under "${key}" is not valid.`);
+        }
+        const call = {
+            ...stored.call,
+            callId: stored.providerCallId,
+        };
+        return {
+            key,
+            id: stored.id,
+            providerCallId: stored.providerCallId,
+            call,
+            ...(stored.committed === undefined
+                ? {}
+                : { committed: stored.committed }),
+        };
+    }
+    /** The explicit durable representation keeps provider and internal identities separate. */
+    #storedToolEntry(entry) {
+        const { callId: _providerCallId, server: _server, ...call } = entry.call;
+        return {
+            id: entry.id,
+            providerCallId: entry.providerCallId,
+            call,
+            ...(entry.committed === undefined ? {} : { committed: entry.committed }),
+        };
+    }
     /** Sorted by position in the batch; only one batch is ever pending at a time. */
-    #toolKey(index, callId) {
-        return `tool.${String(index).padStart(6, "0")}.${callId}`;
+    #toolKey(index, id) {
+        return `tool.${String(index).padStart(6, "0")}.${id}`;
+    }
+    /** The first-writer-wins durable claim shared by tool commit and ordinary settlement. */
+    #toolResultKey(id) {
+        return `toolResult.${id}`;
     }
     /**
-     * The scope one call owns: state persists under its own call ID, never in another call's
-     * scope, and the task context ends where the call was made. The execution and all four tool
-     * hooks share it, so what one of them writes about a call is where the others look for it.
+     * The scope one call owns: state lives under its internal ID, never under the provider's
+     * opaque ID or another call's scope, and is erased when the call commits. The task context
+     * still locates the provider call in conversation history.
      */
-    #callScoped(ctx, callId) {
-        return withAgentTaskContext(withAgentRunKV(withAgentKV(ctx, this.#kv.scoped("call", callId)), this.#runKV.scoped("call", callId)), taskContextBeforeToolCall(this.#messages, callId));
+    #callScoped(ctx, id, providerCallId) {
+        return withAgentTaskContext(withAgentRunKV(withAgentKV(ctx, this.#kv.scoped("call", id)), this.#runKV.scoped("call", id)), taskContextBeforeToolCall(this.#messages, providerCallId));
     }
     /**
      * Call a tool hook that writes inside a transaction of its own call's. The lifetime ends with
      * the callback, so a context kept afterwards cannot outlive the transaction it belongs to.
      * Its failure is not contained: it rolls that transaction back.
      */
-    async #invokeToolTransactHook(txCtx, callId, hook, argument) {
+    async #invokeToolTransactHook(txCtx, id, providerCallId, hook, argument) {
         if (hook === undefined)
             return;
         const lifetime = new AbortController();
         try {
-            await hook(this.#callScoped(withLifetime(txCtx, lifetime.signal), callId), argument);
+            await hook(this.#callScoped(withLifetime(txCtx, lifetime.signal), id, providerCallId), argument);
         }
         finally {
             lifetime.abort();
@@ -2041,7 +2443,8 @@ export class AgentBase {
      * The context carries the turn's abort signal as its lifetime, so a running tool can
      * observe cancellation and stop its own work.
      */
-    async #executeToolCall(ctx, call) {
+    async #executeToolCall(ctx, entry) {
+        const { call } = entry;
         const failure = (text) => ({
             role: "tool",
             callId: call.callId,
@@ -2065,13 +2468,90 @@ export class AgentBase {
         if (tool.parameters !== undefined && !Value.Check(tool.parameters, args)) {
             return failure(`The arguments for "${call.name}" did not match its schema.`);
         }
-        const callCtx = this.#callScoped(ctx, call.callId);
+        const callKV = this.#kv.scoped("call", entry.id).serialized();
+        const callLifetime = new AbortController();
+        let committing = false;
+        const boundedCallKV = callKV.until(callLifetime.signal, () => !committing);
+        const callCtx = withAgentKV(this.#callScoped(ctx, entry.id, entry.providerCallId), boundedCallKV);
         // From here the call is one the two tool hooks bracket: a tool that exists, a call that
         // finished, and arguments its schema accepts. A call refused before that reaches neither
         // hook, because there is nothing yet to decide about or to report.
         let ran = tool;
         let ranArguments = args;
         let outcome;
+        let committedOutcome;
+        let commitAttempt;
+        let resolveCommitted;
+        const committed = new Promise((resolve) => {
+            resolveCommitted = resolve;
+        });
+        const outcomeFor = (result) => ({
+            callId: call.callId,
+            tool: ran,
+            arguments: ranArguments,
+            content: [...ran.toLLM(result)],
+            isError: ran.isError?.(result) === true,
+            result,
+        });
+        const commit = async (commitCtx, result) => {
+            if (commitAttempt !== undefined)
+                return await commitAttempt;
+            if (callLifetime.signal.aborted || commitCtx.lifetime?.aborted === true) {
+                throw new Error("The tool call can no longer commit a result.");
+            }
+            if (!Value.Check(ran.returnType, result)) {
+                throw new Error(`Tool "${ran.name}" committed an invalid result.`);
+            }
+            const candidate = outcomeFor(result);
+            const message = {
+                role: "tool",
+                callId: entry.providerCallId,
+                content: candidate.content,
+                ...(candidate.isError ? { isError: true } : {}),
+            };
+            committing = true;
+            const attempt = (async () => {
+                if (agentKV(commitCtx)?.prefix !== callKV.prefix) {
+                    throw new Error("A tool result can only be committed with its own live call context.");
+                }
+                await this.#persistence.transaction(commitCtx, async (txCtx) => {
+                    const claimed = await this.#persistence.writeValueIfAbsent(txCtx, this.#toolResultKey(entry.id), message);
+                    if (!claimed) {
+                        throw new Error("The tool call already has a committed result.");
+                    }
+                    const pending = await this.#persistence.readValues(txCtx, entry.key);
+                    const stored = pending.find(({ key }) => key === entry.key);
+                    if (stored === undefined) {
+                        throw new Error("The tool call has already been settled.");
+                    }
+                    const current = this.#restoreToolEntry(entry.key, stored.value);
+                    if (current.id !== entry.id) {
+                        throw new Error("The pending tool identity changed before commit.");
+                    }
+                    if (current.committed === undefined) {
+                        await this.#persistence.writeValue(txCtx, entry.key, this.#storedToolEntry({ ...entry, committed: message }));
+                        await callKV.clear(txCtx);
+                    }
+                    afterCommit(txCtx, () => {
+                        committedOutcome = candidate;
+                        callLifetime.abort();
+                        resolveCommitted(candidate);
+                    });
+                });
+                return result;
+            })();
+            commitAttempt = attempt;
+            try {
+                return await attempt;
+            }
+            catch (error) {
+                if (commitAttempt === attempt) {
+                    commitAttempt = undefined;
+                    committing = false;
+                }
+                throw error;
+            }
+        };
         try {
             const decision = await this.#hooks.beforeToolCall?.(callCtx, {
                 callId: call.callId,
@@ -2104,38 +2584,64 @@ export class AgentBase {
                 const runCtx = decision?.permissionMode === undefined
                     ? callCtx
                     : withAgentPermissionMode(callCtx, decision.permissionMode);
-                const result = await ran.execute(runCtx, ranArguments);
-                if (!Value.Check(ran.returnType, result)) {
-                    throw new Error(`Tool "${ran.name}" returned an invalid result.`);
+                const executionCtx = withLifetime(runCtx, AbortSignal.any(runCtx.lifetime === undefined
+                    ? [callLifetime.signal]
+                    : [runCtx.lifetime, callLifetime.signal]));
+                const execution = Promise.resolve(ran.execute(executionCtx, ranArguments, {
+                    id: entry.id,
+                    providerCallId: entry.providerCallId,
+                    kv: boundedCallKV,
+                    commit,
+                })).then((result) => ({ type: "returned", result }), (error) => ({ type: "threw", error }));
+                const settled = await Promise.race([
+                    execution,
+                    committed.then((committed) => ({ type: "committed", committed })),
+                ]);
+                if (settled.type === "committed") {
+                    outcome = settled.committed;
+                }
+                else if (settled.type === "threw") {
+                    throw settled.error;
+                }
+                else if (committedOutcome !== undefined) {
+                    outcome = committedOutcome;
+                }
+                else {
+                    if (!Value.Check(ran.returnType, settled.result)) {
+                        throw new Error(`Tool "${ran.name}" returned an invalid result.`);
+                    }
+                    outcome = outcomeFor(settled.result);
                 }
-                outcome = {
-                    callId: call.callId,
-                    tool: ran,
-                    arguments: ranArguments,
-                    content: [...ran.toLLM(result)],
-                    isError: ran.isError?.(result) === true,
-                    result,
-                };
             }
         }
         catch (error) {
-            outcome = {
+            outcome =
+                committedOutcome ??
+                    {
+                        callId: call.callId,
+                        tool: ran,
+                        arguments: ranArguments,
+                        content: [
+                            {
+                                type: "text",
+                                text: error instanceof Error ? error.message : String(error),
+                            },
+                        ],
+                        isError: true,
+                    };
+        }
+        try {
+            await this.#invokeHookOn(callCtx, this.#hooks.afterToolCall, outcome);
+            return {
+                role: "tool",
                 callId: call.callId,
-                tool: ran,
-                arguments: ranArguments,
-                content: [
-                    { type: "text", text: error instanceof Error ? error.message : String(error) },
-                ],
-                isError: true,
+                content: outcome.content,
+                ...(outcome.isError ? { isError: true } : {}),
             };
         }
-        await this.#invokeHookOn(callCtx, this.#hooks.afterToolCall, outcome);
-        return {
-            role: "tool",
-            callId: call.callId,
-            content: outcome.content,
-            ...(outcome.isError ? { isError: true } : {}),
-        };
+        finally {
+            callLifetime.abort();
+        }
     }
     /**
      * A key that sorts after every entry the queue already holds. The order comes from the store
@@ -2171,7 +2677,7 @@ export class AgentBase {
         const persist = async (event) => {
             if (event === undefined)
                 return;
-            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
                 if (this.#hooks.onEventTransact === undefined) {
                     await this.#appendRecord(lockCtx, { type: "block", block: event.block });
                 }
@@ -2196,7 +2702,7 @@ export class AgentBase {
                 const next = await Promise.race([iterator.next(), abortPromise]);
                 if (next === ABORTED) {
                     // Drop the unfinished block and end the turn.
-                    this.#emit({ type: "done", state: "cancelled" });
+                    await this.#emit({ type: "done", state: "cancelled" });
                     return { content: persisted, state: "cancelled" };
                 }
                 if (next.done === true) {
@@ -2204,7 +2710,7 @@ export class AgentBase {
                     break;
                 }
                 const event = next.value;
-                this.#emit(event);
+                await this.#emit(event);
                 switch (event.type) {
                     case "text_start":
                         content.push({ type: "text", text: "" });
@@ -2355,9 +2861,9 @@ export class AgentBase {
         return this.#session;
     }
     /** Report one stream event to the hooks. Hooks observe the stream; they never fail a run. */
-    #emit(event) {
+    async #emit(event) {
         try {
-            this.#hooks.onEvent?.(this.#ctx, event);
+            await this.#hooks.onEvent?.(this.#ctx, event);
         }
         catch {
             // Hooks observe the stream; they never fail a run.