@slopus/happy-agent-base 0.0.17 → 0.0.18

package/dist/AgentBase.js

@@ -3,15 +3,17 @@ import { createId } from "@paralleldrive/cuid2";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
-import { afterCommit, asyncLock, createContextNamespace, detach, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
+import { afterCommit, createContextNamespace, detach, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
 import { agentDatabase, agentKV, agentStorageTransaction, withAgentContext, withAgentDatabase, withAgentHistoryKV, withAgentKV, withAgentPermissionMode, withAgentRunKV, } from "./AgentContexts.js";
 import { agentConfig, ownAgentConfig, withAgentConfig } from "./AgentConfig.js";
+import { outsideAgentDatabaseOperation } from "./AgentDatabaseConnection.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";
+import { setAgentSpanAttributes } from "./AgentSpanAttributes.js";
 /** Race winner when an abort interrupts a wait on the stream or a running tool. */
 const ABORTED = Symbol("aborted");
 /**
@@ -34,8 +36,6 @@ 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
@@ -76,10 +76,10 @@ const storedToolResultSchema = Type.Object({
  *
  * ## Serialization
  *
- * One lock serializes every persistence operation together with its in-memory effect, so storage
- * order always matches history order and a load never overlaps an append. Anything that decides
- * from durable state resolves that state inside the lock rather than capturing it beforehand; a
- * reference taken before a wait can belong to a history that has since been replaced.
+ * Database transactions and ordered keys keep persistence changes aligned with their in-memory
+ * publication. Anything that decides from durable state resolves that state inside the committing
+ * step rather than capturing it beforehand; a reference taken before a wait can belong to a
+ * history that has since been replaced.
  *
  * ## Accepting a message
  *
@@ -132,8 +132,8 @@ const storedToolResultSchema = Type.Object({
  *
  * An incompatible provider or model change resets the conversation; a compatible one keeps it.
  * Either way the change lands on one side or the other, never the old history under the new
- * model. `modelChanged` runs inside the lock and is lent a store bound to that hold — a
- * capability released when the hook returns, so it cannot be retained to bypass the lock later.
+ * model. `modelChanged` runs inside the transaction and is lent a store bound to it — a
+ * capability released when the hook returns, so it cannot be retained to write after commit.
  * A failing handoff rejects an incompatible switch outright rather than costing the history.
  *
  * ## Permission modes
@@ -256,12 +256,6 @@ export class AgentBase {
     #permissionMode;
     /** The single set of hooks the run is observed by and its configuration extended from. */
     #hooks;
-    /**
-     * Serializes every persistence operation together with its in-memory effect, so storage
-     * order always matches history order and a load never overlaps an append. The lock belongs
-     * to the store, so an owner inspecting the same store sees only whole steps.
-     */
-    #persistenceLock;
     /** The session-scoped key-value store carried on every context the agent derives. */
     #kv;
     /** Durable state tied to the current history and invalidated when that history is replaced. */
@@ -348,6 +342,14 @@ export class AgentBase {
     #inherited;
     /** Whether that inherited record has been read; it can only be read before it is overwritten. */
     #inheritedRead = false;
+    /**
+     * Whether the activation hook is still owed an announcement for inherited work: the store
+     * already said the agent was working when this process first looked, and no run of this
+     * process has announced taking that work up yet.
+     */
+    #restoreActivationOwed = false;
+    /** Whether this process has announced the activation of the current active period. */
+    #activationAnnounced = false;
     /**
      * The compaction that has been asked for and not carried out yet, together with the promise
      * every caller waiting for it shares. Requesting one while it is pending joins that promise
@@ -382,6 +384,8 @@ export class AgentBase {
     #closing;
     /** Operations accepted from a caller and not finished yet; a close waits for every one. */
     #admitted = new Set();
+    /** Queue acceptances the run loop must publish before it may decide its queues are empty. */
+    #messageAdmissions = new Set();
     /**
      * Work from an earlier response that is still unwinding: a provider stream that has not
      * finished closing, or a tool that was settled in the conversation by an abort and is still
@@ -415,10 +419,16 @@ export class AgentBase {
      * they are needed by the first turn and by nothing before it, so an owner resuming a hundred
      * identities at startup pays for a hundred small reads rather than a hundred transcripts.
      * The rest loads on the way into the turn that actually needs it.
+     *
+     * The read normally runs on the agent's own context. A caller resolving the agent from
+     * inside an open storage transaction passes `loadCtx` to route this one read through that
+     * transaction's connection instead, because a single-connection driver cannot serve a read
+     * beside the transaction it is holding open. The agent's own lifetime context is detached
+     * either way and never carries the caller's transaction.
      */
-    static async load(ctx, options) {
+    static async load(ctx, options, loadCtx) {
         const agent = new AgentBase(ctx, options);
-        await agent.#loadPendingState();
+        await agent.#loadPendingState(loadCtx ?? agent.#ctx);
         return agent;
     }
     /**
@@ -440,14 +450,18 @@ export class AgentBase {
     /**
      * Read the outstanding work the store already holds, before this instance has written any of
      * its own. It is both what `active` answers from and what an interrupted run is recognized
-     * by, so reading it here leaves the later stage writes nothing to learn from the store.
-     */
-    async #loadPendingState() {
-        await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
-            await this.#loadConfig(lockCtx);
-            const stored = await agentBasePendingStateOf(lockCtx, this.#persistence);
+     * by, so reading it here leaves the later stage writes nothing to learn from the store. The
+     * context is the caller's choice: the agent's own for an ordinary load, or the resolving
+     * transaction's when the read has to ride that transaction's connection.
+     */
+    async #loadPendingState(ctx) {
+        await this.#runPersistenceStep(ctx, async (operationCtx) => {
+            await this.#loadConfig(operationCtx);
+            const stored = await agentBasePendingStateOf(operationCtx, this.#persistence);
             this.#inherited = stored;
             this.#inheritedRead = true;
+            this.#restoreActivationOwed =
+                stored !== undefined && this.#hooks.afterAgentActivatedTransact !== undefined;
             this.#pending = stored;
             this.#loopId = stored?.loopId;
             this.#turnId = stored?.turnId;
@@ -477,7 +491,6 @@ export class AgentBase {
         this.#providers = options.providers;
         this.#providerId = options.provider;
         this.#persistence = options.persistence;
-        this.#persistenceLock = asyncLock({ reentry: "block" });
         this.#hooks = options.hooks ?? {};
         this.state = {
             instructions: options.initialState?.instructions ?? "",
@@ -553,6 +566,27 @@ export class AgentBase {
             permissionMode: this.#permissionMode,
         };
     }
+    /**
+     * Open agent work with the selection that governs it, so every operation in a trace can be
+     * attributed without recording prompts, arguments, or provider response content.
+     */
+    #span(ctx, name, attributes, work) {
+        const selection = this.#selection();
+        return Promise.resolve(ctx.span(name, (spanCtx) => {
+            setAgentSpanAttributes(spanCtx, {
+                "agent.id": selection.id,
+                "agent.provider": selection.provider,
+                "agent.permission_mode": selection.permissionMode,
+                ...(selection.model === undefined ? {} : { "agent.model": selection.model }),
+                ...(selection.effort === undefined ? {} : { "agent.effort": selection.effort }),
+                ...(selection.serviceTier === undefined
+                    ? {}
+                    : { "agent.service_tier": selection.serviceTier }),
+                ...attributes,
+            });
+            return work(spanCtx);
+        }));
+    }
     /**
      * Whether the agent has anything left to do. This is the only thing about an agent's state
      * anyone outside it may read: the queues and the stage behind this answer are the run's own
@@ -589,7 +623,7 @@ export class AgentBase {
         };
     }
     /**
-     * Record the stage the run has reached, taking the store lock when not already inside it.
+     * Record the stage the run has reached through the store's transaction boundary.
      *
      * The first of these also reads what the store already held, before overwriting it. That
      * reading is the only chance to see it: from this point the record says what this instance
@@ -599,27 +633,44 @@ export class AgentBase {
     async #enterStage(ctx, stage, transact) {
         const pending = this.#pendingState(stage);
         if (transact === undefined &&
+            !this.#restoreActivationOwed &&
             deterministicStringify(pending) === this.#pendingWritten &&
             this.#inheritedRead) {
             return undefined;
         }
         try {
-            return await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+            return await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
                 if (!this.#inheritedRead) {
                     this.#inheritedRead = true;
                     this.#inherited = await agentBasePendingStateOf(lockCtx, this.#persistence);
+                    this.#restoreActivationOwed =
+                        this.#inherited !== undefined &&
+                            !this.#activationAnnounced &&
+                            this.#hooks.afterAgentActivatedTransact !== undefined;
                 }
-                if (transact === undefined) {
+                const announceRestore = this.#restoreActivationOwed;
+                if (transact === undefined && !announceRestore) {
                     await this.#recordPending(lockCtx, stage);
                     return undefined;
                 }
-                return await this.#recordTransaction(lockCtx, async (txCtx) => {
+                const result = 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, stage, true);
-                    return await this.#withTransactionalContext(txCtx, transact);
+                    // Taking up inherited work is what reactivates the agent after a restart,
+                    // so the announcement commits with the resumed run's own stage record.
+                    if (announceRestore)
+                        await this.#announceActivation(txCtx, true);
+                    return transact === undefined
+                        ? undefined
+                        : await this.#withTransactionalContext(txCtx, transact);
                 });
+                if (announceRestore) {
+                    this.#restoreActivationOwed = false;
+                    this.#activationAnnounced = true;
+                }
+                return result;
             });
         }
         catch (error) {
@@ -640,6 +691,41 @@ export class AgentBase {
         this.#pending = undefined;
         this.#pendingWritten = undefined;
     }
+    /**
+     * Tell the activation hook the agent stopped being settled, inside the very transaction that
+     * records the work it now owes. A failure propagates and rolls that transaction back, so a
+     * module never concludes the agent woke up from a wake-up that never became durable.
+     */
+    async #announceActivation(txCtx, restored) {
+        const hook = this.#hooks.afterAgentActivatedTransact;
+        if (hook === undefined)
+            return;
+        await this.#withTransactionalContext(txCtx, (hookCtx) => hook(this.#workContext(hookCtx), { restored }));
+    }
+    /**
+     * Record that scheduled work made an inference owed, and decide whether this transaction is
+     * the one that woke a settled agent. The decision is the store's own absent-only insert of
+     * the pending record, so transactions racing to wake the same agent are arbitrated by the
+     * database rather than by a read another writer could make stale: exactly one creates the
+     * record and activates, and the others find it already present. A record that is present
+     * but unreadable counts as no pending state, as it does everywhere else.
+     */
+    async #claimPendingWork(txCtx) {
+        const pending = this.#pendingState("inference");
+        const serialized = deterministicStringify(pending);
+        // This instance already recorded the current run, so the work is already owed and
+        // nothing here can be an activation.
+        if (this.#pendingWritten === serialized)
+            return false;
+        let created = await this.#persistence.writeValueIfAbsent(txCtx, AGENT_BASE_PENDING_KEY, pending);
+        if (!created) {
+            created = (await agentBasePendingStateOf(txCtx, this.#persistence)) === undefined;
+            await this.#persistence.writeValue(txCtx, AGENT_BASE_PENDING_KEY, pending);
+        }
+        this.#pending = pending;
+        this.#pendingWritten = serialized;
+        return created;
+    }
     /**
      * 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
@@ -671,34 +757,37 @@ export class AgentBase {
             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()) {
+        if (insideTurn.get(ctx).includes(this.id) || this.#insideOwnLoop()) {
             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.#runPersistenceStep(ctx, async (lockCtx) => {
             await this.#persistence.transaction(lockCtx, async (txCtx) => {
+                const stored = await this.#persistence.readValues(txCtx, "agentConfig");
+                const exact = stored.find(({ key }) => key === "agentConfig")?.value;
+                const current = exact === undefined ? this.#config : ownAgentConfig(exact);
+                const previousMetadata = ownAgentMetadata(current.metadata ?? {});
+                const metadata = ownAgentMetadata({ ...previousMetadata, ...ownedUpdate });
+                if (previousMetadata === undefined || metadata === undefined) {
+                    throw new Error("The agent metadata is not valid.");
+                }
+                next = ownAgentConfig({ ...current, metadata });
+                change = {
+                    agentId: this.id,
+                    previousMetadata,
+                    update: ownedUpdate,
+                    metadata,
+                };
                 await this.#persistence.writeValue(txCtx, "agentConfig", next);
                 await this.#withTransactionalContext(withAgentConfig(txCtx, next), async (hookCtx) => await this.#hooks.metadataChangedTransact?.(this.#hookContext(hookCtx), change));
+                afterCommit(txCtx, () => {
+                    this.#config = next;
+                    this.#baseCtx = withAgentConfig(this.#baseCtx, next);
+                    this.#ctx = this.#deriveCtx();
+                });
             });
-            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);
     }
@@ -712,9 +801,6 @@ export class AgentBase {
         if (outerTransaction?.lifetime.aborted === true) {
             throw new Error("The agent storage transaction carried by this context has ended.");
         }
-        if (outerTransaction !== undefined && this.#insideOwnPersistenceLock()) {
-            throw new Error("Agent message delivery cannot reenter its own persistence operation inside a transaction.");
-        }
         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.");
@@ -796,30 +882,20 @@ 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);
-            });
-        });
+    /** Run one persistence step; its database statements and transactions own consistency. */
+    async #runPersistenceStep(ctx, work) {
+        return await work(ctx);
     }
     /**
-     * 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
-     * batch is being written lands after the whole batch rather than in the middle of it, and a
-     * failure admits none of them.
+     * Accept a batch of messages as one durable transaction, so a caller arriving while it is
+     * being written lands after the whole batch rather than in the middle of it, and a failure
+     * admits none of them.
      */
     async #enqueue(ctx, batch) {
         if (batch.length === 0)
@@ -832,19 +908,22 @@ export class AgentBase {
             ? this.#enqueueIndependently(ctx, batch)
             : this.#enqueueInTransaction(ctx, batch);
         this.#admitted.add(admitted);
+        this.#messageAdmissions.add(admitted);
         try {
             return await admitted;
         }
         finally {
             this.#admitted.delete(admitted);
+            this.#messageAdmissions.delete(admitted);
         }
     }
-    /** Accept a batch under the persistence lock, in a transaction of the acceptance's own. */
+    /** Accept a batch in a transaction of the acceptance's own. */
     async #enqueueIndependently(ctx, batch) {
-        return await this.#runInPersistenceLock(ctx, async (lockCtx) => {
+        return await this.#runPersistenceStep(ctx, async (lockCtx) => {
             const accepted = [];
             const results = [];
             await this.#recordTransaction(lockCtx, async (txCtx) => {
+                let activated = false;
                 for (const request of batch) {
                     const identityKey = `message.${request.id}`;
                     if (!(await this.#persistence.writeValueIfAbsent(txCtx, identityKey, true))) {
@@ -874,36 +953,41 @@ export class AgentBase {
                 // 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, "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,
-                    id: request.id,
-                    message: request.message,
-                    ...(request.metadata === undefined ? {} : { metadata: request.metadata }),
-                    options: request.options,
+                // Creating that record where none existed is what makes a settled agent active,
+                // and the activation hook commits with the very transaction that admits the
+                // message.
+                if (await this.#claimPendingWork(txCtx)) {
+                    await this.#announceActivation(txCtx, false);
+                    activated = true;
+                }
+                afterCommit(txCtx, () => {
+                    if (activated) {
+                        this.#activationAnnounced = true;
+                        this.#restoreActivationOwed = false;
+                    }
+                    for (const { key, request } of accepted) {
+                        const queue = request.kind === "steering" ? this.#steering : this.#sends;
+                        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;
         });
     }
     /**
-     * Accept a batch inside the caller's own open transaction. This path must not take the
-     * agent's persistence lock: the caller holds the database writer for as long as its
-     * transaction stays open, while a running turn takes the lock first and the database second,
-     * so waiting for the lock here would close a cycle nothing could break. The outer transaction
-     * supplies the atomicity the lock otherwise guarantees, queue keys are claimed with
-     * absent-only writes so a racing independent enqueue cannot be overwritten, and no heap
-     * state changes until the commit publishes the batch.
+     * Accept a batch inside the caller's own open transaction. The outer transaction supplies
+     * atomicity, queue keys are claimed with absent-only writes so a racing independent enqueue
+     * cannot be overwritten, and no heap state changes until the commit publishes the batch.
      */
     async #enqueueInTransaction(ctx, batch) {
         const results = [];
@@ -934,43 +1018,58 @@ export class AgentBase {
         // Accepting a message is what makes the work owed, so the same transaction that admits
         // it records that the agent owes an answer; here that record is staged durably and made
         // live only once the outermost commit publishes the whole batch.
-        const stagedPending = acceptedAny
-            ? await this.#stagePendingMessageWork(ctx)
-            : undefined;
+        const staged = acceptedAny ? await this.#stagePendingMessageWork(ctx) : undefined;
+        // Scheduling onto a settled agent is what makes it active; the announcement writes into
+        // the caller's own transaction and is published or rolled back with the batch itself.
+        if (staged?.activated === true)
+            await this.#announceActivation(ctx, false);
         const offeredIds = batch.map(({ id }) => id);
         afterCommit(ctx, async () => {
-            await this.#activateCommittedMessages(offeredIds, stagedPending);
+            await this.#activateCommittedMessages(offeredIds, staged);
         });
         return results;
     }
     /**
      * Persist the pending inference an outer transaction will make live after commit, without
-     * changing any heap state that would survive a rollback. Reading the transaction's current
-     * value also makes multiple sends in one outer transaction reuse the same lifecycle IDs.
+     * changing any heap state that would survive a rollback. Whether the agent was settled is
+     * decided by the store's own absent-only insert of the pending record, so concurrent
+     * transactions waking the same agent are arbitrated by the database itself: exactly one
+     * creates the record and activates. Reading the transaction's current value on the taken
+     * path also makes multiple sends in one outer transaction reuse the same lifecycle IDs.
      */
     async #stagePendingMessageWork(ctx) {
+        const fresh = { stage: "inference", loopId: createId() };
+        if (await this.#persistence.writeValueIfAbsent(ctx, AGENT_BASE_PENDING_KEY, fresh)) {
+            return { pending: fresh, activated: true };
+        }
         const stored = await agentBasePendingStateOf(ctx, this.#persistence);
-        const pending = stored === undefined
-            ? { stage: "inference", loopId: createId() }
-            : { ...stored, stage: "inference" };
+        // A record that is present but unreadable counts as no pending state, as everywhere
+        // else, so this transaction still claims the activation when it replaces one.
+        const pending = stored === undefined ? fresh : { ...stored, stage: "inference" };
         await this.#persistence.writeValue(ctx, AGENT_BASE_PENDING_KEY, pending);
-        return pending;
+        return { pending, activated: stored === undefined };
     }
     /**
      * Publish a transactionally accepted message only after the outermost commit. The next turn
      * reloads the durable queue instead of copying staged entries into memory; the dirty marker
      * prevents a turn already in flight from clearing the request before that reload happens.
      */
-    async #activateCommittedMessages(offeredIds, stagedPending) {
+    async #activateCommittedMessages(offeredIds, staged) {
         for (const id of offeredIds)
             this.#offeredMessageIds.add(id);
-        if (stagedPending === undefined)
+        if (staged === undefined)
             return;
-        await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
-            let pending = stagedPending;
+        // The commit published the staged activation announcement along with the batch, so the
+        // current active period is now an announced one.
+        if (staged.activated) {
+            this.#activationAnnounced = true;
+            this.#restoreActivationOwed = false;
+        }
+        await this.#runPersistenceStep(this.#ctx, async (lockCtx) => {
+            let pending = staged.pending;
             try {
                 pending =
-                    (await agentBasePendingStateOf(lockCtx, this.#persistence)) ?? stagedPending;
+                    (await agentBasePendingStateOf(lockCtx, this.#persistence)) ?? staged.pending;
             }
             catch {
                 // The committed staged value is enough to start; a turn reload retries storage.
@@ -1002,22 +1101,31 @@ export class AgentBase {
             return;
         if (this.#closed)
             throw new Error("The agent has been closed.");
-        await this.#runInPersistenceLock(ctx, async (lockCtx) => {
+        await this.#runPersistenceStep(ctx, async (lockCtx) => {
             const accepted = [];
             await this.#recordTransaction(lockCtx, async (txCtx) => {
+                let activated = false;
                 for (const message of batch) {
                     const key = await this.#queueKey(txCtx, "inject.");
                     await this.#persistence.writeValue(txCtx, key, message);
                     accepted.push({ key, message });
                 }
-                if (accepted.length > 0)
-                    await this.#recordPending(txCtx, "inference");
+                if (accepted.length === 0)
+                    return;
+                if (await this.#claimPendingWork(txCtx)) {
+                    await this.#announceActivation(txCtx, false);
+                    activated = true;
+                }
+                afterCommit(txCtx, () => {
+                    if (activated) {
+                        this.#activationAnnounced = true;
+                        this.#restoreActivationOwed = false;
+                    }
+                    this.#injections.push(...accepted);
+                    this.#turnRequested = true;
+                    this.#startRun();
+                });
             });
-            this.#injections.push(...accepted);
-            if (accepted.length > 0) {
-                this.#turnRequested = true;
-                this.#startRun();
-            }
         });
     }
     /**
@@ -1303,7 +1411,7 @@ export class AgentBase {
             return;
         // The loop is a lifetime of its own, so it marks itself rather than inheriting whatever
         // happened to start it — a tool of another agent, most often, which will be long gone.
-        this.#runPromise = insideLoops
+        this.#runPromise = outsideAgentDatabaseOperation(() => insideLoops
             .run([this.id], () => this.#runLoop())
             .finally(() => {
             this.#runPromise = undefined;
@@ -1315,7 +1423,7 @@ export class AgentBase {
                 return;
             }
             this.#announceSettled();
-        });
+        }));
     }
     /**
      * Answer turns until nothing is asked for any more. The inner loop is one turn each: reload
@@ -1328,13 +1436,14 @@ export class AgentBase {
         // whole of it runs on. Everything below is handed that context rather than reading a
         // scope back off the agent, so each turn, inference, tool call, and hook is placed in
         // the run it actually belongs to even while another agent is running alongside it.
-        await this.#ctx.span("agent.run", (ctx) => this.#runTurns(ctx));
+        await this.#span(this.#ctx, "agent.run", {}, (ctx) => this.#runTurns(ctx));
     }
     /** The run itself, on the context of the span the whole of it belongs to. */
     async #runTurns(ctx) {
         if (this.#pending?.stage === "settlement") {
             this.#loopId ??= createId();
             this.#settlementId ??= createId();
+            setAgentSpanAttributes(ctx, { "agent.loop.id": this.#loopId });
             await this.#settleDurably(ctx, {
                 loopId: this.#loopId,
                 settlementId: this.#settlementId,
@@ -1346,6 +1455,7 @@ export class AgentBase {
         do {
             this.#loopId ??= createId();
             const loop = { loopId: this.#loopId };
+            setAgentSpanAttributes(ctx, { "agent.loop.id": loop.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.
@@ -1359,7 +1469,7 @@ export class AgentBase {
                 : (hookCtx) => this.#hooks.beforeAgentLoopTransact?.(hookCtx, loop));
             await this.#invokeHook(ctx, this.#hooks.beforeAgentLoop, loop);
             do {
-                const outcome = await ctx.span("agent.turn", (turnCtx) => this.#runTurn(turnCtx, loop, abort));
+                const outcome = await this.#span(ctx, "agent.turn", { "agent.loop.id": loop.loopId }, (turnCtx) => this.#runTurn(turnCtx, loop, abort));
                 if (outcome === "blocked")
                     return;
                 if (outcome === "stop")
@@ -1394,6 +1504,7 @@ export class AgentBase {
         this.#turnAborted = false;
         this.#durableWorkBlocked = false;
         this.#turnId ??= createId();
+        setAgentSpanAttributes(ctx, { "agent.turn.id": this.#turnId });
         // 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 inference.
@@ -1459,12 +1570,15 @@ export class AgentBase {
      * resumed at all.
      */
     async #settleDurably(ctx, settlement) {
-        await ctx.span("agent.settle", (settleCtx) => this.#settleRecord(settleCtx, settlement));
+        await this.#span(ctx, "agent.settle", {
+            "agent.loop.id": settlement.loopId,
+            "agent.settlement.id": settlement.settlementId,
+        }, (settleCtx) => this.#settleRecord(settleCtx, settlement));
     }
     /** The settlement itself, on the context of the span it belongs to. */
     async #settleRecord(ctx, settlement) {
         try {
-            await this.#runInPersistenceLock(this.#workContext(ctx), (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+            await this.#runPersistenceStep(this.#workContext(ctx), (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 await this.#clearPending(txCtx);
                 await this.#invokeTransactionalSettle(txCtx, settlement);
                 // The run store is erased last, so a settling hook can still read what the
@@ -1478,6 +1592,10 @@ export class AgentBase {
             this.#inferenceId = undefined;
             this.#settlementId = undefined;
             this.#settlement = settlement;
+            // Settled means nothing is owed: the next scheduled message activates the agent
+            // afresh, and nothing inherited remains to announce.
+            this.#activationAnnounced = false;
+            this.#restoreActivationOwed = false;
         }
         catch {
             // The run itself is over and succeeded; only the record of its ending failed.
@@ -1721,6 +1839,7 @@ export class AgentBase {
                         await this.#emit(ctx, { type: "done", state: "cancelled" });
                     break;
                 }
+                await this.#finishAdmittedQueueWrites();
                 let injected = await this.#consumeQueue(ctx, this.#steering, this.#steeringMode, "steering");
                 if (!injected && !needsInference) {
                     injected = await this.#consumeQueue(ctx, this.#sends, this.#sendMode, "send");
@@ -1731,7 +1850,7 @@ export class AgentBase {
                 // Nothing to answer — a start() on an idle history, or the queues ran dry.
                 if (!this.#noticeAwaitingResponse && !injected && !needsInference)
                     break;
-                const response = await ctx.span("agent.inference", (inferenceCtx) => this.#requestInference(inferenceCtx, abortPromise));
+                const response = await this.#span(ctx, "agent.inference", {}, (inferenceCtx) => this.#requestInference(inferenceCtx, abortPromise));
                 // A cancellation arrived before the request was made, so the turn cycles rather
                 // than talking to a session it may no longer own.
                 if (response === undefined)
@@ -1793,6 +1912,16 @@ export class AgentBase {
         }
         this.#turnAborted = abort.signal.aborted;
     }
+    /**
+     * Let queue writes already admitted by a re-entrant hook publish before deciding the queues
+     * are empty. Their database transactions own ordering; this waits for those concrete writes
+     * without holding another agent or database lock.
+     */
+    async #finishAdmittedQueueWrites() {
+        while (this.#messageAdmissions.size > 0) {
+            await Promise.allSettled(this.#messageAdmissions);
+        }
+    }
     /**
      * Make one request of the provider and take its answer: the instructions and tools the turn
      * is running with, the session they belong to, the inference brackets around the request, and
@@ -1817,6 +1946,11 @@ export class AgentBase {
         };
         this.#loopId = inferenceStart.loopId;
         this.#turnId = inferenceStart.turnId;
+        setAgentSpanAttributes(ctx, {
+            "agent.loop.id": inferenceStart.loopId,
+            "agent.turn.id": inferenceStart.turnId,
+            "agent.inference.id": inferenceStart.inferenceId,
+        });
         await this.#enterStage(ctx, "inference", this.#hooks.beforeInferenceTransact === undefined
             ? undefined
             : (hookCtx) => this.#hooks.beforeInferenceTransact?.(hookCtx, inferenceStart));
@@ -1908,7 +2042,7 @@ export class AgentBase {
         const previousTokens = this.#contextTokens;
         this.#contextTokens = tokens;
         try {
-            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+            await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
                 const write = (writeCtx) => tokens === undefined
                     ? this.#persistence.deleteValue(writeCtx, "context")
                     : this.#persistence.writeValue(writeCtx, "context", { tokens });
@@ -1942,7 +2076,7 @@ export class AgentBase {
     async #runCompaction(ctx, signal) {
         if (this.#compaction === undefined)
             return;
-        await ctx.span("agent.compaction", (compactionCtx) => this.#compactHistory(compactionCtx, signal));
+        await this.#span(ctx, "agent.compaction", {}, (compactionCtx) => this.#compactHistory(compactionCtx, signal));
     }
     /** The compaction itself, on the context of the span it belongs to. */
     async #compactHistory(ctx, signal) {
@@ -1963,6 +2097,11 @@ export class AgentBase {
             };
             this.#loopId = compactionStart.loopId;
             this.#turnId = compactionStart.turnId;
+            setAgentSpanAttributes(ctx, {
+                "agent.loop.id": compactionStart.loopId,
+                "agent.turn.id": compactionStart.turnId,
+                "agent.compaction.id": compactionStart.compactionId,
+            });
             await this.#invokeHook(ctx, this.#hooks.beforeCompaction, compactionStart);
             // Provider compaction is this turn's work, so it runs on this turn's lifetime: an
             // abort reaches the provider operation itself rather than waiting for it to finish
@@ -1980,7 +2119,7 @@ export class AgentBase {
             }
             if (result.status === "completed") {
                 const completed = { ...compactionStart, result };
-                await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+                await this.#runPersistenceStep(this.#workContext(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) => {
@@ -2034,7 +2173,7 @@ export class AgentBase {
         let settled = false;
         let staged = false;
         try {
-            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+            await this.#runPersistenceStep(this.#workContext(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.
@@ -2142,7 +2281,7 @@ export class AgentBase {
             content: [{ type: "text", text: `The last turn failed: ${message}` }],
         };
         try {
-            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+            await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
                 await this.#appendRecord(lockCtx, { type: "system", message: failure });
                 this.#messages.push(failure);
             });
@@ -2153,7 +2292,7 @@ export class AgentBase {
     }
     /** Move every pending hook notice into history as one atomic, ordered append batch. */
     async #consumeInjections(ctx) {
-        return await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+        return await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
             if (this.#injections.length === 0)
                 return false;
             const durable = new Set((await this.#persistence.readValues(lockCtx, "inject.")).map(({ key }) => key));
@@ -2202,16 +2341,16 @@ export class AgentBase {
      * context store and the in-memory history. The moves run in one transaction, so a message
      * is never durable in both stores or neither, and memory changes only after the commit.
      *
-     * What the consumption has to announce is announced once the lock has been released. A hook
-     * told a message has landed may perfectly well answer by sending another one, and doing that
-     * while this still held the store lock would be the hook waiting for its own caller.
+     * What the consumption has to announce is announced once the transaction has committed. A
+     * hook told a message has landed may perfectly well answer by sending another one without
+     * re-entering the transaction that delivered the first message.
      */
     async #consumeQueue(ctx, queue, mode, kind) {
         const prefix = `${kind}.`;
-        /** Filled in once the consumption has committed, and reported after the lock is released. */
+        /** Filled in once the consumption has committed, then reported to observers. */
         const accepted = [];
         let permissionChange;
-        const consumed = await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+        const consumed = await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
             if (queue.length === 0)
                 return false;
             // The durable queue, not memory, decides what is left to consume after a restart.
@@ -2294,8 +2433,7 @@ export class AgentBase {
             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
+                        // The hook runs 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.
@@ -2393,16 +2531,14 @@ export class AgentBase {
                         id: entry.id,
                         kind,
                         message: entry.message,
-                        ...(entry.metadata === undefined
-                            ? {}
-                            : { metadata: entry.metadata }),
+                        ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
                     });
                 }
             });
             if (reset)
                 this.#rotateHistoryKV();
             // 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.
+            // announced about them is decided now and reported once the transaction commits.
             permissionChange = modeChange;
             accepted.push(...batch.map((entry) => ({
                 id: entry.id,
@@ -2452,13 +2588,13 @@ export class AgentBase {
         await this.#withTransactionalContext(hookCtx, (liveCtx) => hook(liveCtx, argument));
     }
     /**
-     * Replace the in-memory state with the durable one. The persistence lock guarantees every
+     * Replace the in-memory state with the durable one. Durable queue acceptance guarantees every
      * message already in memory reached storage first, so the load result supersedes memory
      * entirely: the main store rebuilds the context, and the sorted queue keys rebuild the
      * not-yet-consumed queues. Consecutive block records reassemble into one assistant message.
      */
     async #loadHistory(ctx) {
-        await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+        await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
             const records = await this.#persistence.load(lockCtx);
             const last = records[records.length - 1];
             this.#lastRecordType = last?.type;
@@ -2540,12 +2676,12 @@ export class AgentBase {
      * complete context behind.
      */
     async #runToolBatch(ctx, entries, resume, signal, abortPromise) {
-        return await ctx.span("agent.tools", (batchCtx) => this.#dispatchToolBatch(batchCtx, entries, resume, signal, abortPromise));
+        return await this.#span(ctx, "agent.tools", { "agent.tool.count": entries.length, "agent.tool.resume": resume }, (batchCtx) => this.#dispatchToolBatch(batchCtx, entries, resume, signal, abortPromise));
     }
     /** The batch itself, on the context of the span it belongs to. */
     async #dispatchToolBatch(ctx, entries, resume, signal, abortPromise) {
         if (!resume) {
-            await this.#runInPersistenceLock(this.#workContext(ctx), (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+            await this.#runPersistenceStep(this.#workContext(ctx), (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 for (const entry of entries) {
                     await this.#persistence.writeValue(txCtx, entry.key, this.#storedToolEntry(entry));
                 }
@@ -2577,7 +2713,7 @@ export class AgentBase {
             if (commitFailed)
                 return;
             try {
-                await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+                await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
                     while (committed < entries.length) {
                         const entry = entries[committed];
                         const proposed = results[committed];
@@ -2639,7 +2775,13 @@ export class AgentBase {
                 // The call's own span hangs off the batch's. Every call in the batch runs at
                 // the same time, so each opens its span from the batch's context and carries
                 // its own from there.
-                const execution = ctx.span("agent.tool", (toolCtx) => this.#executeToolCall(withLifetime(this.#workContext(toolCtx), toolLifetime), entry));
+                const execution = this.#span(ctx, "agent.tool", {
+                    "agent.tool.id": entry.id,
+                    "agent.tool.name": entry.call.name,
+                    ...(entry.call.namespace === undefined
+                        ? {}
+                        : { "agent.tool.namespace": entry.call.namespace }),
+                }, (toolCtx) => this.#executeToolCall(withLifetime(this.#workContext(toolCtx), toolLifetime), entry));
                 running.push(execution);
                 outcome = await Promise.race([execution, abortPromise, this.#closingTools()]);
             }
@@ -3026,7 +3168,7 @@ export class AgentBase {
     }
     /**
      * Write a queue entry under a key nothing else holds. An enqueue running outside the
-     * persistence lock can race an independent one for the tail position, so the key is claimed
+     * database transaction can race an independent one for the tail position, so the key is claimed
      * with an absent-only write and a taken key moves one sequence further rather than
      * overwriting whatever claimed it first.
      */
@@ -3055,7 +3197,7 @@ export class AgentBase {
         const persist = async (event) => {
             if (event === undefined)
                 return;
-            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
+            await this.#runPersistenceStep(this.#workContext(ctx), async (lockCtx) => {
                 if (this.#hooks.onEventTransact === undefined) {
                     await this.#appendRecord(lockCtx, { type: "block", block: event.block });
                 }