@slopus/happy-agent-base 0.0.11 → 0.0.13

package/dist/AgentBase.js

@@ -3,8 +3,8 @@ 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, deterministicStringify, withLifetime, } from "@steve.kite/stdlib";
-import { agentDatabase, agentKV, agentStorageTransaction, withAgentContext, withAgentDatabase, withAgentHistoryKV, withAgentKV, withAgentPermissionMode, withAgentRunKV, withoutAgentStorageTransaction, } from "./AgentContexts.js";
+import { afterCommit, asyncLock, 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 { taskContextBeforeToolCall, withAgentTaskContext } from "./AgentTaskContext.js";
 import { AgentKV } from "./AgentKV.js";
@@ -18,8 +18,13 @@ const ABORTED = Symbol("aborted");
  * The agents whose run loop the current execution is running inside. Hooks and tool executions
  * receive a context carrying this, so an operation that would wait for the very loop it is part
  * of can say so instead of hanging for ever.
+ *
+ * Not detachable. Being inside a loop is a fact about the call in progress, and work that detaches
+ * to a lifetime of its own is by definition no longer inside it.
  */
-const insideTurn = createContextNamespace("agentInsideTurn", []);
+const insideTurn = createContextNamespace("agentInsideTurn", [], {
+    detachable: false,
+});
 /**
  * The same fact as `insideTurn`, tracked by the runtime rather than carried by a context. Not
  * every operation takes one — `close` is the whole agent's lifetime and has no call to carry it —
@@ -459,10 +464,14 @@ 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 = withoutAgentStorageTransaction(withAgentDatabase(withAgentConfig(insideTurn.set(ctx, [options.id]), this.#config), options.persistence.database));
+        // An agent is its own lifetime, so it makes a root of the context it was handed rather
+        // than working on it. Whatever call happened to construct it — a tool of another agent,
+        // most often — takes its cancellation, its open transaction, and the loop it was itself
+        // running inside with it when it returns, and none of that may reach work that goes on
+        // long afterwards. What survives is what describes the world the agent runs in: its
+        // logger, its tracer, and its configuration. Everything the agent owns is put on
+        // deliberately, beginning with the storage the detached root no longer carries.
+        this.#baseCtx = withAgentDatabase(withAgentConfig(insideTurn.set(detach(ctx).named(`agent.${options.id}`), [options.id]), this.#config), options.persistence.database);
         this.#providers = options.providers;
         this.#providerId = options.provider;
         this.#persistence = options.persistence;
@@ -488,11 +497,21 @@ export class AgentBase {
     /**
      * The context everything the agent does runs on: its identity and effective selection, plus
      * the session-scoped key-value store and the store of the run in progress. Rebuilt whenever
-     * the selection changes.
+     * the selection changes. It is what the agent does its own work on, outside a run.
      */
     #deriveCtx() {
         return this.#hookContext(this.#baseCtx);
     }
+    /**
+     * The agent's selection, configuration, and stores put onto the context a stretch of work is
+     * running on. The run loop hands each piece of its work the context of the tracing span that
+     * work belongs to, and every use of that context goes through here, so what the agent is
+     * running on is read at the moment of use: a model switch or a metadata change made in the
+     * middle of a turn is seen by the rest of it, and the span the work opened under is kept.
+     */
+    #workContext(ctx) {
+        return this.#hookContext(withAgentConfig(ctx, this.#config));
+    }
     /** Add this agent's selection and stores to a caller context without losing its transaction. */
     #hookContext(ctx) {
         const selected = withAgentContext(ctx, this.#selection());
@@ -575,7 +594,7 @@ export class AgentBase {
      * is doing, and a run interrupted by a dead process would be indistinguishable from the one
      * starting here.
      */
-    async #enterStage(stage, transact) {
+    async #enterStage(ctx, stage, transact) {
         const pending = this.#pendingState(stage);
         if (transact === undefined &&
             deterministicStringify(pending) === this.#pendingWritten &&
@@ -583,7 +602,7 @@ export class AgentBase {
             return undefined;
         }
         try {
-            return await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            return await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
                 if (!this.#inheritedRead) {
                     this.#inheritedRead = true;
                     this.#inherited = await agentBasePendingStateOf(lockCtx, this.#persistence);
@@ -995,8 +1014,8 @@ export class AgentBase {
      * Instructions and tools are correctness hooks — a failure here fails the turn loudly
      * instead of silently running with a wrong configuration.
      */
-    async #instructions() {
-        const hooked = await this.#hooks.instructions?.(this.#ctx);
+    async #instructions(ctx) {
+        const hooked = await this.#hooks.instructions?.(this.#workContext(ctx));
         return [this.state.instructions, hooked ?? ""]
             .filter((text) => text.length > 0)
             .join("\n\n");
@@ -1006,8 +1025,8 @@ export class AgentBase {
      * answer. Two tools sharing one name and namespace are a configuration error that fails
      * the turn, since the provider would receive ambiguous descriptors.
      */
-    async #tools() {
-        const hooked = await this.#hooks.tools?.(this.#ctx);
+    async #tools(ctx) {
+        const hooked = await this.#hooks.tools?.(this.#workContext(ctx));
         const tools = [...this.state.tools, ...(hooked ?? [])];
         const names = new Set();
         for (const tool of tools) {
@@ -1179,10 +1198,18 @@ export class AgentBase {
      * more work, so the loop hooks always bracket a settled-to-settled span.
      */
     async #runLoop() {
+        // The run is a stretch of work of its own, and the context of its span is the one the
+        // 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));
+    }
+    /** 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();
-            await this.#settleDurably({
+            await this.#settleDurably(ctx, {
                 loopId: this.#loopId,
                 settlementId: this.#settlementId,
             });
@@ -1201,102 +1228,117 @@ 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 === undefined
+            await this.#enterStage(ctx, "inference", this.#hooks.beforeAgentLoopTransact === undefined
                 ? undefined
                 : (hookCtx) => this.#hooks.beforeAgentLoopTransact?.(hookCtx, loop));
-            await this.#invokeHook(this.#hooks.beforeAgentLoop, loop);
+            await this.#invokeHook(ctx, 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
-                // inference.
-                this.#turnRequested = false;
-                // Every turn starts from durable state rather than from what this instance last
-                // remembered, so the store remains authoritative after recovery.
-                this.#loaded = undefined;
-                // The durable history has to be loaded before anything else: a turn that cannot
-                // read the conversation cannot answer it, and must not write to it either —
-                // appending to a conversation it cannot see is how a message ends up after a
-                // tool call nobody answered. The turn ends here instead, leaving everything
-                // durable exactly as it was for the next attempt.
-                const loadFailure = await this.#ensureLoaded().then(() => undefined, (error) => error);
-                if (loadFailure !== undefined) {
-                    await this.#emit({
-                        type: "done",
-                        state: "error",
-                        kind: "internal_error",
-                        message: loadFailure instanceof Error
-                            ? 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
-                    ? undefined
-                    : (hookCtx) => this.#hooks.beforeTurnTransact?.(hookCtx, turnStart));
-                await this.#applyActions(this.#hooks.beforeTurn, abort.signal, turnStart);
-                await this.#runInference(abort);
-                if (this.#durableWorkBlocked)
+                const outcome = await ctx.span("agent.turn", (turnCtx) => this.#runTurn(turnCtx, loop, abort));
+                if (outcome === "blocked")
                     return;
-                const turn = {
-                    loopId: loop.loopId,
-                    turnId: turnStart.turnId,
-                    contextTokens: this.#contextTokens,
-                    aborted: this.#turnAborted,
-                };
-                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 && !this.#hasNoticeWorkToFinish())) {
+                if (outcome === "stop")
                     break;
-                }
                 // Each turn cancels on its own scope. Reopening it here rather than at the top
                 // keeps the run's first turn under the scope its opening hook already ran in.
                 abort = this.#openAbortScope();
             } while (true);
-            await this.#enterStage("inference", this.#hooks.afterAgentLoopTransact === undefined
+            await this.#enterStage(ctx, "inference", this.#hooks.afterAgentLoopTransact === undefined
                 ? undefined
                 : (hookCtx) => this.#hooks.afterAgentLoopTransact?.(hookCtx, loop));
-            await this.#applyActions(this.#hooks.afterAgentLoop, abort.signal, loop);
+            await this.#applyActions(ctx, this.#hooks.afterAgentLoop, abort.signal, loop);
         } while (this.#turnRequested && (!this.#closed || this.#hasNoticeWorkToFinish()));
         // 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.
         this.#settlementId ??= createId();
-        await this.#enterStage("settlement");
-        await this.#settleDurably({
+        await this.#enterStage(ctx, "settlement");
+        await this.#settleDurably(ctx, {
             loopId: this.#loopId ?? createId(),
             settlementId: this.#settlementId,
         });
     }
+    /**
+     * One turn: reload the durable state, ask the pre-turn hooks what to do, run the inference
+     * and its tools, then ask the post-turn hooks. It answers with what the run should do next —
+     * open another turn, stop because nothing more is asked for, or give up entirely because a
+     * staged tool result could not settle and this run must leave its pending state intact.
+     */
+    async #runTurn(ctx, loop, abort) {
+        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 inference.
+        this.#turnRequested = false;
+        // Every turn starts from durable state rather than from what this instance last
+        // remembered, so the store remains authoritative after recovery.
+        this.#loaded = undefined;
+        // The durable history has to be loaded before anything else: a turn that cannot read the
+        // conversation cannot answer it, and must not write to it either — appending to a
+        // conversation it cannot see is how a message ends up after a tool call nobody answered.
+        // The turn ends here instead, leaving everything durable exactly as it was for the next
+        // attempt.
+        const loadFailure = await this.#ensureLoaded(ctx).then(() => undefined, (error) => error);
+        if (loadFailure !== undefined) {
+            await this.#emit(ctx, {
+                type: "done",
+                state: "error",
+                kind: "internal_error",
+                message: loadFailure instanceof Error ? loadFailure.message : String(loadFailure),
+            });
+            this.#turnId = undefined;
+            return "stop";
+        }
+        const turnStart = {
+            loopId: loop.loopId,
+            turnId: this.#turnId,
+            contextTokens: this.#contextTokens,
+        };
+        await this.#enterStage(ctx, "inference", this.#hooks.beforeTurnTransact === undefined
+            ? undefined
+            : (hookCtx) => this.#hooks.beforeTurnTransact?.(hookCtx, turnStart));
+        await this.#applyActions(ctx, this.#hooks.beforeTurn, abort.signal, turnStart);
+        await this.#runInference(ctx, abort);
+        if (this.#durableWorkBlocked)
+            return "blocked";
+        const turn = {
+            loopId: loop.loopId,
+            turnId: turnStart.turnId,
+            contextTokens: this.#contextTokens,
+            aborted: this.#turnAborted,
+        };
+        const completedTurnId = this.#turnId;
+        this.#turnId = undefined;
+        try {
+            await this.#enterStage(ctx, "inference", this.#hooks.afterTurnTransact === undefined
+                ? undefined
+                : (hookCtx) => this.#hooks.afterTurnTransact?.(hookCtx, turn));
+        }
+        catch (error) {
+            this.#turnId = completedTurnId;
+            throw error;
+        }
+        await this.#applyActions(ctx, this.#hooks.afterTurn, abort.signal, turn);
+        if (!this.#turnRequested || (this.#closed && !this.#hasNoticeWorkToFinish())) {
+            return "stop";
+        }
+        return "continue";
+    }
     /**
      * Erase the outstanding work and let the transactional settling hooks write in the same
      * transaction. A failure leaves the record in place: an agent wrongly believed to be working
      * is resumed and finds nothing to do, while one wrongly believed to be finished is never
      * resumed at all.
      */
-    async #settleDurably(settlement) {
+    async #settleDurably(ctx, settlement) {
+        await ctx.span("agent.settle", (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.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+            await this.#runInPersistenceLock(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
@@ -1377,9 +1419,9 @@ export class AgentBase {
             // Hooks observe the run; they never fail it.
         }
     }
-    /** Call an observing hook on the agent's own context. */
-    async #invokeHook(hook, ...args) {
-        await this.#invokeHookOn(this.#ctx, hook, ...args);
+    /** Call an observing hook on the context the work in progress is running on. */
+    async #invokeHook(ctx, hook, ...args) {
+        await this.#invokeHookOn(this.#workContext(ctx), hook, ...args);
     }
     /**
      * Lend a hook the transaction's context and module stores for exactly one callback. Keeping
@@ -1403,19 +1445,19 @@ export class AgentBase {
      * out of work the caller had just cancelled. The answer is dropped rather than deferred,
      * since it was a decision about a turn that no longer exists.
      */
-    async #applyActions(hook, signal, ...args) {
+    async #applyActions(ctx, hook, signal, ...args) {
         if (hook === undefined)
             return;
         let actions;
         try {
-            actions = await hook(this.#ctx, ...args);
+            actions = await hook(this.#workContext(ctx), ...args);
         }
         catch {
             return;
         }
         if (signal.aborted)
             return;
-        await this.#carryOutActions(actions);
+        await this.#carryOutActions(ctx, actions);
     }
     /**
      * Ask a lifecycle hook what to do next and carry its actions out: queue steering, sent
@@ -1424,31 +1466,32 @@ export class AgentBase {
      * Neither a throwing hook nor a failing action ever fails the run. Unlike `#applyActions`
      * this belongs to no turn's scope, so nothing can cancel the answer out from under it.
      */
-    async #applyActionsAlways(hook, ...args) {
+    async #applyActionsAlways(ctx, hook, ...args) {
         if (hook === undefined)
             return;
         let actions;
         try {
-            actions = await hook(this.#ctx, ...args);
+            actions = await hook(this.#workContext(ctx), ...args);
         }
         catch {
             return;
         }
-        await this.#carryOutActions(actions);
+        await this.#carryOutActions(ctx, actions);
     }
     /**
      * Carry out what a hook asked for. User messages keep their ordinary queues; system notices
      * enter a separate durable queue consumed only at a safe history boundary.
      */
-    async #carryOutActions(actions) {
+    async #carryOutActions(ctx, actions) {
         const batch = [];
         const injections = [];
         const flush = async () => {
             const pending = batch.splice(0, batch.length);
             const pendingInjections = injections.splice(0, injections.length);
+            const workCtx = this.#workContext(ctx);
             try {
-                await this.#enqueue(this.#ctx, pending);
-                await this.#enqueueInjections(this.#ctx, pendingInjections);
+                await this.#enqueue(workCtx, pending);
+                await this.#enqueueInjections(workCtx, pendingInjections);
             }
             catch {
                 // A hook-driven action must not fail the run.
@@ -1490,7 +1533,7 @@ export class AgentBase {
      * until nothing is owed an answer. Every failure is caught here and surfaced to the
      * conversation, so a turn ends with a complete context whatever went wrong.
      */
-    async #runInference(abort) {
+    async #runInference(ctx, abort) {
         // One shared promise for the turn's scope keeps races from piling up listeners on the
         // signal, and a scope that was aborted before this point settles it immediately: a
         // listener added afterwards would never hear the event that already happened.
@@ -1500,7 +1543,7 @@ export class AgentBase {
                 abort.signal.addEventListener("abort", () => resolve(ABORTED), { once: true });
             });
         try {
-            await this.#ensureLoaded();
+            await this.#ensureLoaded(ctx);
             // Resume a tool batch that was dispatched but cut off before its results landed, so
             // the interrupted results reach the main store before any queued message.
             const resumed = this.#pendingTools;
@@ -1511,21 +1554,21 @@ export class AgentBase {
                 // A batch that was never committed has certainly not run — the commit precedes
                 // every execution — so it is dispatched as the fresh batch it never got to be,
                 // rather than resumed, which would refuse the non-durable calls.
-                if (await this.#runToolBatch(resumed, !undispatched, abort.signal, abortPromise)) {
+                if (await this.#runToolBatch(ctx, resumed, !undispatched, abort.signal, abortPromise)) {
                     return;
                 }
             }
             let needsInference = resumed.length > 0;
             // A requested compaction runs before this turn's first inference, so the model
             // always receives a settled conversation — never one still owing tool results.
-            await this.#runCompaction(abort.signal);
+            await this.#runCompaction(ctx, abort.signal);
             // An inference is needed without any injection when tool results from a resumed batch
             // end the context, or — checked once, against the freshly loaded durable state —
             // when a cut-off run left its trailing user or tool message unanswered. Afterwards
             // a trailing user message can be legitimate: a response may have zero blocks.
             if (!this.#recoveryChecked) {
                 this.#recoveryChecked = true;
-                if (await this.#resumesInterruptedRun())
+                if (await this.#resumesInterruptedRun(ctx))
                     needsInference = true;
             }
             // Each cycle first drains the queues, then runs one inference. Steering injects at
@@ -1549,100 +1592,34 @@ export class AgentBase {
                         this.#injections.length > 0 ||
                         this.#noticeAwaitingResponse;
                     if (hasPendingWork)
-                        await this.#emit({ type: "done", state: "cancelled" });
+                        await this.#emit(ctx, { type: "done", state: "cancelled" });
                     break;
                 }
-                let injected = await this.#consumeQueue(this.#steering, this.#steeringMode, "steering");
+                let injected = await this.#consumeQueue(ctx, this.#steering, this.#steeringMode, "steering");
                 if (!injected && !needsInference) {
-                    injected = await this.#consumeQueue(this.#sends, this.#sendMode, "send");
+                    injected = await this.#consumeQueue(ctx, this.#sends, this.#sendMode, "send");
                 }
                 // Notices follow queue consumption so a model-switching message can replace
                 // history first. Tool settlement and compaction already finished above.
-                await this.#consumeInjections();
+                await this.#consumeInjections(ctx);
                 // Nothing to answer — a start() on an idle history, or the queues ran dry.
                 if (!this.#noticeAwaitingResponse && !injected && !needsInference)
                     break;
-                const instructions = await this.#instructions();
-                const tools = await this.#tools();
-                const session = await this.#ensureSession(instructions, tools);
-                // Nothing from the previous response may still be holding the session — but
-                // that unwinding was detached from an earlier abort precisely so it could never
-                // hold a cancellation open, so a new cancellation must not start waiting for it
-                // either.
-                if ((await Promise.race([this.#settled(), abortPromise])) === ABORTED)
+                const response = await ctx.span("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)
                     continue;
-                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,
-                        messages: [...this.#messages],
-                    },
-                    ...(this.#model === undefined ? {} : { model: this.#model }),
-                    ...(this.#effort === undefined ? {} : { effort: this.#effort }),
-                    ...(this.#serviceTier === undefined ? {} : { serviceTier: this.#serviceTier }),
-                });
-                const { content, state, errorMessage, tokens } = await this.#collect(stream, abortPromise);
-                // A cancellation or a stream ending without a done event did not answer an
-                // appended notice. Keep that obligation and reopen it under a fresh turn scope.
-                // Every terminal provider outcome counts as the response, including an error.
-                if (this.#noticeAwaitingResponse &&
-                    (state === "cancelled" || state === undefined)) {
-                    this.#turnRequested = true;
-                }
-                else {
-                    this.#noticeAwaitingResponse = false;
-                    this.#clearTurnRequestIfNoPendingInput();
-                }
-                // 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 }),
-                };
-                const afterInferenceTransact = this.#hooks.afterInferenceTransact === undefined
-                    ? undefined
-                    : (hookCtx) => this.#hooks.afterInferenceTransact?.(hookCtx, inference);
-                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);
-                    }
-                }
-                catch (error) {
-                    this.#inferenceId = completedInferenceId;
-                    throw error;
-                }
-                await this.#invokeHook(this.#hooks.afterInference, inference);
-                if (content.length > 0) {
-                    this.#messages.push({ role: "assistant", content });
-                }
+                const { content, state } = response;
                 needsInference = false;
-                pendingError = state === "error" ? errorMessage : undefined;
+                pendingError = state === "error" ? response.errorMessage : undefined;
                 if (state !== "tool_call") {
                     // A response can carry a tool call and still not end in one — a stream that
                     // failed or was cut off after the call was emitted. Nothing will dispatch
                     // it, so it is settled here rather than left in the conversation for ever.
                     // A settling the store refused ends the turn instead: the call stays last,
                     // where a later attempt can still answer it.
-                    if (!(await this.#settleUnansweredCalls("The response ended before this tool call was dispatched."))) {
+                    if (!(await this.#settleUnansweredCalls(ctx, "The response ended before this tool call was dispatched."))) {
                         break;
                     }
                 }
@@ -1650,7 +1627,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) => this.#newToolEntry(index, call)), false, abort.signal, abortPromise);
+                    const closedDuringTools = await this.#runToolBatch(ctx, calls.map((call, index) => this.#newToolEntry(index, call)), false, abort.signal, abortPromise);
                     if (closedDuringTools)
                         break;
                     needsInference = true;
@@ -1667,11 +1644,11 @@ export class AgentBase {
             if (pendingError !== undefined &&
                 this.#loaded !== undefined &&
                 this.#unansweredCalls(this.#messages).length === 0) {
-                await this.#appendFailure(pendingError);
+                await this.#appendFailure(ctx, pendingError);
             }
         }
         catch (error) {
-            await this.#emit({
+            await this.#emit(ctx, {
                 type: "done",
                 state: "error",
                 kind: "internal_error",
@@ -1682,14 +1659,93 @@ export class AgentBase {
             // outright and no later turn would ever repair. When even that write is refused, the
             // note is not written either — the call stays last, and the next run settles it
             // before anything else is said.
-            if (await this.#settleUnansweredCalls("The turn failed before this tool call finished.")) {
-                await this.#appendFailure(error instanceof Error ? error.message : String(error));
+            if (await this.#settleUnansweredCalls(ctx, "The turn failed before this tool call finished.")) {
+                await this.#appendFailure(ctx, error instanceof Error ? error.message : String(error));
             }
             this.#noticeAwaitingResponse = false;
             this.#clearTurnRequestIfNoPendingInput();
         }
         this.#turnAborted = abort.signal.aborted;
     }
+    /**
+     * 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
+     * the blocks the model actually finished saying. Nothing comes back when a cancellation
+     * arrived before the request was made, since there is no response to account for.
+     */
+    async #requestInference(ctx, abortPromise) {
+        const instructions = await this.#instructions(ctx);
+        const tools = await this.#tools(ctx);
+        const session = await this.#ensureSession(instructions, tools);
+        // Nothing from the previous response may still be holding the session — but that
+        // unwinding was detached from an earlier abort precisely so it could never hold a
+        // cancellation open, so a new cancellation must not start waiting for it either.
+        if ((await Promise.race([this.#settled(), abortPromise])) === ABORTED)
+            return undefined;
+        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(ctx, "inference", this.#hooks.beforeInferenceTransact === undefined
+            ? undefined
+            : (hookCtx) => this.#hooks.beforeInferenceTransact?.(hookCtx, inferenceStart));
+        await this.#invokeHook(ctx, this.#hooks.beforeInference, inferenceStart);
+        const stream = session.run(this.#workContext(ctx), {
+            context: {
+                instructions,
+                messages: [...this.#messages],
+            },
+            ...(this.#model === undefined ? {} : { model: this.#model }),
+            ...(this.#effort === undefined ? {} : { effort: this.#effort }),
+            ...(this.#serviceTier === undefined ? {} : { serviceTier: this.#serviceTier }),
+        });
+        const { content, state, errorMessage, tokens } = await this.#collect(ctx, stream, abortPromise);
+        // A cancellation or a stream ending without a done event did not answer an appended
+        // notice. Keep that obligation and reopen it under a fresh turn scope. Every terminal
+        // provider outcome counts as the response, including an error.
+        if (this.#noticeAwaitingResponse && (state === "cancelled" || state === undefined)) {
+            this.#turnRequested = true;
+        }
+        else {
+            this.#noticeAwaitingResponse = false;
+            this.#clearTurnRequestIfNoPendingInput();
+        }
+        // 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 }),
+        };
+        const afterInferenceTransact = this.#hooks.afterInferenceTransact === undefined
+            ? undefined
+            : (hookCtx) => this.#hooks.afterInferenceTransact?.(hookCtx, inference);
+        const completedInferenceId = this.#inferenceId;
+        this.#inferenceId = undefined;
+        try {
+            if (tokens === undefined) {
+                await this.#enterStage(ctx, "inference", afterInferenceTransact);
+            }
+            else {
+                await this.#recordContextTokens(ctx, tokens.input + tokens.output, afterInferenceTransact);
+            }
+        }
+        catch (error) {
+            this.#inferenceId = completedInferenceId;
+            throw error;
+        }
+        await this.#invokeHook(ctx, this.#hooks.afterInference, inference);
+        if (content.length > 0) {
+            this.#messages.push({ role: "assistant", content });
+        }
+        return { content, state, ...(errorMessage === undefined ? {} : { errorMessage }) };
+    }
     /**
      * Whether this agent is picking up a run that was cut off rather than starting a fresh one,
      * and so owes an inference nobody asked for again.
@@ -1700,18 +1756,18 @@ 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.
      */
-    async #resumesInterruptedRun() {
+    async #resumesInterruptedRun(ctx) {
         const owed = this.#lastRecordType === "user" ||
             this.#lastRecordType === "tool" ||
             this.#lastRecordType === "system";
         if (owed && this.#inherited?.stage === "inference") {
-            await this.#emit({ type: "block_reset" });
+            await this.#emit(ctx, { type: "block_reset" });
         }
         return owed;
     }
     /** Load the durable state once. A failed load is not sticky: the next turn retries it. */
-    async #ensureLoaded() {
-        this.#loaded ??= this.#loadHistory().catch((error) => {
+    async #ensureLoaded(ctx) {
+        this.#loaded ??= this.#loadHistory(ctx).catch((error) => {
             this.#loaded = undefined;
             throw error;
         });
@@ -1722,11 +1778,11 @@ export class AgentBase {
      * lets a restarted agent keep knowing how large the conversation is without inferring it;
      * a failed write costs only that knowledge and never the response that produced it.
      */
-    async #recordContextTokens(tokens, transact) {
+    async #recordContextTokens(ctx, tokens, transact) {
         const previousTokens = this.#contextTokens;
         this.#contextTokens = tokens;
         try {
-            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
                 const write = (writeCtx) => tokens === undefined
                     ? this.#persistence.deleteValue(writeCtx, "context")
                     : this.#persistence.writeValue(writeCtx, "context", { tokens });
@@ -1757,14 +1813,20 @@ export class AgentBase {
      * promise for every caller awaiting it. A provider failure rejects them and leaves history
      * untouched.
      */
-    async #runCompaction(signal) {
+    async #runCompaction(ctx, signal) {
+        if (this.#compaction === undefined)
+            return;
+        await ctx.span("agent.compaction", (compactionCtx) => this.#compactHistory(compactionCtx, signal));
+    }
+    /** The compaction itself, on the context of the span it belongs to. */
+    async #compactHistory(ctx, signal) {
         const pending = this.#compaction;
         if (pending === undefined)
             return;
         try {
-            await this.#enterStage("compaction");
-            const instructions = await this.#instructions();
-            const session = await this.#ensureSession(instructions, await this.#tools());
+            await this.#enterStage(ctx, "compaction");
+            const instructions = await this.#instructions(ctx);
+            const session = await this.#ensureSession(instructions, await this.#tools(ctx));
             const snapshot = [...this.#messages];
             await this.#settled();
             const compactionStart = {
@@ -1775,16 +1837,16 @@ export class AgentBase {
             };
             this.#loopId = compactionStart.loopId;
             this.#turnId = compactionStart.turnId;
-            await this.#invokeHook(this.#hooks.beforeCompaction, compactionStart);
+            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
             // work nobody wants any more.
-            const result = await session.compact(withLifetime(this.#ctx, signal), {
+            const result = await session.compact(withLifetime(this.#workContext(ctx), signal), {
                 context: { instructions, messages: snapshot },
                 ...(this.#model === undefined ? {} : { model: this.#model }),
             });
             if (result.status === "failed") {
-                await this.#invokeHook(this.#hooks.afterCompaction, {
+                await this.#invokeHook(ctx, this.#hooks.afterCompaction, {
                     ...compactionStart,
                     result,
                 });
@@ -1792,7 +1854,7 @@ export class AgentBase {
             }
             if (result.status === "completed") {
                 const completed = { ...compactionStart, result };
-                await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+                await this.#runInPersistenceLock(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) => {
@@ -1813,9 +1875,9 @@ export class AgentBase {
                 });
                 // The conversation the measurement described is gone; its size is unknown
                 // again until the next response measures the replacement.
-                await this.#recordContextTokens(undefined);
+                await this.#recordContextTokens(ctx, undefined);
             }
-            await this.#invokeHook(this.#hooks.afterCompaction, {
+            await this.#invokeHook(ctx, this.#hooks.afterCompaction, {
                 ...compactionStart,
                 result,
             });
@@ -1836,7 +1898,7 @@ export class AgentBase {
      * happen must append nothing either — leaving the call last is what lets a later attempt,
      * here or after a restart, still answer it.
      */
-    async #settleUnansweredCalls(reason) {
+    async #settleUnansweredCalls(ctx, reason) {
         // Nothing is known about the conversation, so nothing may be said about it.
         if (this.#loaded === undefined)
             return false;
@@ -1846,7 +1908,7 @@ export class AgentBase {
         let settled = false;
         let staged = false;
         try {
-            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(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.
@@ -1946,7 +2008,7 @@ export class AgentBase {
      * there is no context to append to; its own failure is swallowed, so surfacing a failure can
      * never cause another.
      */
-    async #appendFailure(message) {
+    async #appendFailure(ctx, message) {
         if (this.#loaded === undefined)
             return;
         const failure = {
@@ -1954,7 +2016,7 @@ export class AgentBase {
             content: [{ type: "text", text: `The last turn failed: ${message}` }],
         };
         try {
-            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
                 await this.#appendRecord(lockCtx, { type: "system", message: failure });
                 this.#messages.push(failure);
             });
@@ -1964,8 +2026,8 @@ export class AgentBase {
         }
     }
     /** Move every pending hook notice into history as one atomic, ordered append batch. */
-    async #consumeInjections() {
-        return await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+    async #consumeInjections(ctx) {
+        return await this.#runInPersistenceLock(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));
@@ -2017,12 +2079,12 @@ export class AgentBase {
      * 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.
      */
-    async #consumeQueue(queue, mode, kind) {
+    async #consumeQueue(ctx, queue, mode, kind) {
         const prefix = `${kind}.`;
         /** Filled in once the consumption has committed, and reported after the lock is released. */
         const accepted = [];
         let permissionChange;
-        const consumed = await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+        const consumed = await this.#runInPersistenceLock(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.
@@ -2204,7 +2266,9 @@ export class AgentBase {
                         id: entry.id,
                         kind,
                         message: entry.message,
-                        ...(entry.metadata === undefined ? {} : { metadata: entry.metadata }),
+                        ...(entry.metadata === undefined
+                            ? {}
+                            : { metadata: entry.metadata }),
                     });
                 }
             });
@@ -2239,13 +2303,13 @@ export class AgentBase {
             }
             return true;
         });
-        // Outside the lock, and on the agent's own context, which now carries whatever these
-        // messages made effective.
+        // Outside the lock, and on a context carrying whatever these messages made effective:
+        // the selection is read now rather than when the turn opened.
         if (permissionChange !== undefined) {
-            await this.#invokeHook(this.#hooks.permissionModeChanged, permissionChange);
+            await this.#invokeHook(ctx, this.#hooks.permissionModeChanged, permissionChange);
         }
         for (const message of accepted) {
-            await this.#invokeHook(this.#hooks.messageAccepted, message);
+            await this.#invokeHook(ctx, this.#hooks.messageAccepted, message);
         }
         return consumed;
     }
@@ -2266,8 +2330,8 @@ export class AgentBase {
      * 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() {
-        await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+    async #loadHistory(ctx) {
+        await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
             const records = await this.#persistence.load(lockCtx);
             const last = records[records.length - 1];
             this.#lastRecordType = last?.type;
@@ -2347,9 +2411,13 @@ export class AgentBase {
      * settles every call still running as an aborted error result, so the batch always leaves a
      * complete context behind.
      */
-    async #runToolBatch(entries, resume, signal, abortPromise) {
+    async #runToolBatch(ctx, entries, resume, signal, abortPromise) {
+        return await ctx.span("agent.tools", (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.#ctx, (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
+            await this.#runInPersistenceLock(this.#workContext(ctx), (lockCtx) => this.#recordTransaction(lockCtx, async (txCtx) => {
                 for (const entry of entries) {
                     await this.#persistence.writeValue(txCtx, entry.key, this.#storedToolEntry(entry));
                 }
@@ -2365,7 +2433,7 @@ export class AgentBase {
             }));
         }
         else {
-            await this.#enterStage("tools");
+            await this.#enterStage(ctx, "tools");
         }
         const results = new Array(entries.length);
         // Every execution actually started, whether or not its result reached the conversation.
@@ -2381,7 +2449,7 @@ export class AgentBase {
             if (commitFailed)
                 return;
             try {
-                await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+                await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
                     while (committed < entries.length) {
                         const entry = entries[committed];
                         const proposed = results[committed];
@@ -2435,12 +2503,15 @@ export class AgentBase {
             if (entry.committed !== undefined) {
                 outcome = entry.committed;
             }
-            else if (resume && !(await this.#isDurable(entry.call))) {
+            else if (resume && !(await this.#isDurable(ctx, 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);
+                // 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));
                 running.push(execution);
                 outcome = await Promise.race([execution, abortPromise, this.#closingTools()]);
             }
@@ -2492,8 +2563,8 @@ export class AgentBase {
         });
     }
     /** Whether this call's tool may safely be executed again after a restart interrupted it. */
-    async #isDurable(call) {
-        const tool = (await this.#tools()).find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
+    async #isDurable(ctx, call) {
+        const tool = (await this.#tools(ctx)).find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
         return tool?.durable === true;
     }
     /**
@@ -2596,7 +2667,7 @@ export class AgentBase {
             content: [{ type: "text", text }],
             isError: true,
         });
-        const tool = (await this.#tools()).find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
+        const tool = (await this.#tools(ctx)).find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
         if (tool === undefined) {
             return failure(`Tool "${call.name}" is not available.`);
         }
@@ -2823,7 +2894,7 @@ export class AgentBase {
      * the model actually finished saying: a response cut off mid-block keeps the finished blocks
      * alone, so memory never differs from what a reload would rebuild.
      */
-    async #collect(stream, abortPromise) {
+    async #collect(ctx, stream, abortPromise) {
         const content = [];
         // Blocks that finished and were durably appended. An abort keeps exactly these, so the
         // in-memory assistant message never diverges from what a reload would rebuild.
@@ -2832,7 +2903,7 @@ export class AgentBase {
         const persist = async (event) => {
             if (event === undefined)
                 return;
-            await this.#runInPersistenceLock(this.#ctx, async (lockCtx) => {
+            await this.#runInPersistenceLock(this.#workContext(ctx), async (lockCtx) => {
                 if (this.#hooks.onEventTransact === undefined) {
                     await this.#appendRecord(lockCtx, { type: "block", block: event.block });
                 }
@@ -2857,7 +2928,7 @@ export class AgentBase {
                 const next = await Promise.race([iterator.next(), abortPromise]);
                 if (next === ABORTED) {
                     // Drop the unfinished block and end the turn.
-                    await this.#emit({ type: "done", state: "cancelled" });
+                    await this.#emit(ctx, { type: "done", state: "cancelled" });
                     return { content: persisted, state: "cancelled" };
                 }
                 if (next.done === true) {
@@ -2865,7 +2936,7 @@ export class AgentBase {
                     break;
                 }
                 const event = next.value;
-                await this.#emit(event);
+                await this.#emit(ctx, event);
                 switch (event.type) {
                     case "text_start":
                         content.push({ type: "text", text: "" });
@@ -3016,9 +3087,9 @@ export class AgentBase {
         return this.#session;
     }
     /** Report one stream event to the hooks. Hooks observe the stream; they never fail a run. */
-    async #emit(event) {
+    async #emit(ctx, event) {
         try {
-            await this.#hooks.onEvent?.(this.#ctx, event);
+            await this.#hooks.onEvent?.(this.#workContext(ctx), event);
         }
         catch {
             // Hooks observe the stream; they never fail a run.