@superdurable/dex-agents 0.1.0 → 0.3.0

package/dist/src/agent-session-transitions.js

@@ -5,22 +5,33 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
-import { StepRef, goTo, stringCodec, } from "@superdurable/dex";
+import { AttributeMapNotLoadedError, StepMovement, StepRef, goTo, goToMany, stringCodec, } from "@superdurable/dex";
+import { agentSessionStepTypes } from "./agent-session-step-types.js";
+import { isContextCompactionRunner } from "./agent-context-compaction.js";
 import { StreamAgentEventWriter } from "./agent-event-writer.js";
+import { encodeAgentMessage } from "./agent-session-codecs.js";
 import { resolveToolPolicy, } from "./agent-framework-runner.js";
 import { messageSequenceKey } from "./agent-session-persistence.js";
-import { addAgentUsage, emptyAgentUsage, } from "./agent-session-values.js";
-export const agentSessionStepTypes = {
-    startAgentSession: "StartAgentSession",
-    awaitUserMessage: "AwaitUserMessage",
-    runModel: "RunModel",
-    awaitToolApproval: "AwaitToolApproval",
-    callTool: "CallTool",
-    callSingleAttemptTool: "CallSingleAttemptTool",
-    recordToolFailure: "RecordToolFailure",
-    recordToolOutcomeUnknown: "RecordToolOutcomeUnknown",
-    resumeTurn: "ResumeTurn",
-    recordTurnFailure: "RecordTurnFailure",
+import { modelCallRefusedErrorPrefix, withinSpendLimitCallTimeout, } from "./agent-session-spend-limit.js";
+import { messageStepOptions } from "./agent-session-step-options.js";
+import { addAgentUsage, buildToolCallNote, emptyAgentUsage, isFinalToolCallStatus, toolCallCancelledBySteeringResult, toolCallCancelledByTurnCancellationResult, turnCancelledNoteHeader, turnSteeredNoteHeader, } from "./agent-session-values.js";
+export { agentSessionStepTypes } from "./agent-session-step-types.js";
+/** Most archive chunks one commit writes, so a large 0.1.0 history migrates over several commits. */
+export const messageRolloverMaxChunksPerCommit = 4;
+/**
+ * Most chunk bytes one commit writes, 8 MiB, which keeps a Step result far under the engine's frame limit. A
+ * single chunk larger than it still moves, alone.
+ */
+export const messageRolloverMaxBytesPerCommit = 8_388_608;
+// `{"messages":[` and `]}` around the comma-separated messages.
+const messageChunkOverheadBytes = 15;
+const utf8Encoder = new TextEncoder();
+/** Consumes every pending message of a Channel at once; the plan's MAX. */
+export const allPendingMessages = 2_147_483_647;
+/** The model-visible result of a call that steering or `cancel_turn` abandoned, by reason. */
+export const toolCallCancellationResults = {
+    steered: toolCallCancelledBySteeringResult,
+    turn_cancelled: toolCallCancelledByTurnCancellationResult,
 };
 // Keeps liveness well inside the shortest heartbeat timeout, one minute.
 const heartbeatIntervalMs = 20_000;
@@ -29,10 +40,12 @@ export class AgentSessionTransitions {
     persistence;
     runner;
     config;
-    constructor(persistence, runner, config) {
+    tracer;
+    constructor(persistence, runner, config, tracer) {
         this.persistence = persistence;
         this.runner = runner;
         this.config = config;
+        this.tracer = tracer;
     }
     readOptionalAgentState(context) {
         return this.persistence.agentState.get(context) ?? null;
@@ -50,21 +63,175 @@ export class AgentSessionTransitions {
     readPendingInterrupts(context) {
         return this.persistence.pendingInterrupts.get(context) ?? [];
     }
+    readOptionalAgentPlan(context) {
+        return this.persistence.agentPlan.get(context) ?? null;
+    }
     readAgentUsage(context) {
         return this.persistence.agentUsage.get(context) ?? emptyAgentUsage();
     }
+    /** The settings the next turn starts with, or `null` when the session has none. */
+    readSessionSettings(context) {
+        return this.persistence.sessionSettings.get(context) ?? null;
+    }
+    /** The settings the active turn started with; see {@link selectTurnSessionSettings}. */
+    readTurnSessionSettings(context) {
+        return selectTurnSessionSettings(this.persistence.turnSessionSettings.get(context) ?? null, this.readOptionalAgentState(context)?.activeTurnId ?? null);
+    }
+    readContextSummary(context) {
+        return this.persistence.contextSummary.get(context) ?? null;
+    }
+    /** The summary the runner sees; a runner without the compaction methods keeps every message instead. */
+    readRunnerContextSummary(context) {
+        return isContextCompactionRunner(this.runner) ? this.readContextSummary(context) : null;
+    }
     readFrameworkRunState(context) {
         const runState = this.persistence.frameworkRunState.get(context);
         return runState === undefined || runState === "" ? null : runState;
     }
-    /** Returns messages with sequences in [start, end); requires the AgentMessages load. */
+    readMessageIndex(context) {
+        return this.persistence.agentMessageIndex.get(context) ?? null;
+    }
+    /** Sequence of the oldest stored message: retention deleted the earlier ones. */
+    readFirstStoredSequence(context) {
+        return this.readMessageIndex(context)?.firstSequence ?? 1;
+    }
+    /**
+     * Returns the stored messages with sequences in [start, end), from the `AgentMessages` window and the
+     * `AgentMessageChunks` instances. It requires the whole window and every chunk it reads to be loaded.
+     */
     readMessages(context, start, end) {
+        const index = this.readMessageIndex(context);
         const messages = [];
-        for (let sequence = Math.max(1, start); sequence < end; sequence += 1) {
-            messages.push(this.persistence.agentMessages.get(context, messageSequenceKey(sequence)));
+        const chunks = new Map();
+        for (let sequence = Math.max(index?.firstSequence ?? 1, start); sequence < end; sequence += 1) {
+            const range = index === null ? undefined : findMessageChunkRange(index, sequence);
+            if (range === undefined) {
+                messages.push(this.readWindowMessage(context, sequence));
+                continue;
+            }
+            let chunk = chunks.get(range.firstSequence);
+            if (chunk === undefined) {
+                chunk = this.readChunkMessages(context, range);
+                chunks.set(range.firstSequence, chunk);
+            }
+            messages.push(chunk[sequence - range.firstSequence]);
         }
         return messages;
     }
+    readWindowMessage(context, sequence) {
+        const message = this.persistence.agentMessages.get(context, messageSequenceKey(sequence));
+        if (message === undefined) {
+            throw new Error(`AgentMessages has no message ${sequence} in session ${context.flowId}`);
+        }
+        return message;
+    }
+    /** Reads one loaded chunk and checks that it holds exactly the messages its range names. */
+    readChunkMessages(context, range) {
+        const key = messageSequenceKey(range.firstSequence);
+        let chunk;
+        try {
+            chunk = this.persistence.agentMessageChunks.get(context, key);
+        }
+        catch (error) {
+            if (error instanceof AttributeMapNotLoadedError) {
+                throw new Error(`AgentMessageChunks instance ${key} is not loaded`);
+            }
+            throw error;
+        }
+        if (chunk === undefined) {
+            throw new Error(`AgentMessageChunks instance ${key} is not loaded`);
+        }
+        if (!isMessageChunkOfRange(chunk, range)) {
+            throw new Error(`AgentMessageChunks instance ${key} does not hold messages ${range.firstSequence} through ${range.lastSequence}`);
+        }
+        return chunk.messages;
+    }
+    /**
+     * Counts the active turn's stored messages after the user messages that started it, before this Step's
+     * appends. A turn without its `TurnReplySequence`, such as one a 0.1.0 Worker started, is counted from its
+     * stored messages instead.
+     */
+    countStoredTurnReplies(context, state, turnId) {
+        return state.nextMessageSequence - this.readTurnReplySequence(context, state, turnId);
+    }
+    /** Returns the first sequence after the turn's user messages, from `TurnReplySequence` or the stored messages. */
+    readTurnReplySequence(context, state, turnId) {
+        const stored = this.persistence.turnReplySequence.get(context);
+        if (stored !== undefined && stored.turnId === turnId) {
+            return stored.sequence;
+        }
+        const turnMessages = this.readStoredTurnMessages(context, state, turnId);
+        return state.nextMessageSequence - countMessagesAfterUserMessages(turnMessages, turnId);
+    }
+    /**
+     * Returns the turn's newest stored messages, read back until another turn's, the oldest stored message, or a
+     * chunk this Step did not load.
+     */
+    readStoredTurnMessages(context, state, turnId) {
+        const index = this.readMessageIndex(context);
+        const turnMessages = [];
+        for (let sequence = state.nextMessageSequence - 1; sequence >= (index?.firstSequence ?? 1); sequence -= 1) {
+            const message = this.readLoadedMessage(context, index, sequence);
+            if (message === undefined || message.turnId !== turnId) {
+                break;
+            }
+            turnMessages.push(message);
+        }
+        return turnMessages.reverse();
+    }
+    /** Reads one stored message from the window or its chunk, or returns `undefined` when its chunk is not loaded. */
+    readLoadedMessage(context, index, sequence) {
+        const range = index === null ? undefined : findMessageChunkRange(index, sequence);
+        if (range === undefined) {
+            return this.readWindowMessage(context, sequence);
+        }
+        try {
+            return this.readChunkMessages(context, range)[sequence - range.firstSequence];
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.endsWith("is not loaded")) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    /** First sequence of the model input: after the runner's summary, and never before the oldest stored message. */
+    readModelInputFirstSequence(context, summary) {
+        return Math.max(this.readFirstStoredSequence(context), summary === null ? 1 : summary.lastSequence + 1);
+    }
+    /**
+     * Returns the archive chunks that hold messages in [start, end): every chunk when compaction is off, since
+     * the model input then covers them all, else exact instances.
+     */
+    messageChunkLoads(context, start, end = Number.MAX_SAFE_INTEGER) {
+        const index = this.readMessageIndex(context);
+        if (index === null) {
+            return { isWholeMap: false, instances: [] };
+        }
+        const instances = index.chunks
+            .filter((range) => range.lastSequence >= start && range.firstSequence < end)
+            .map((range) => this.persistence.agentMessageChunks.load(messageSequenceKey(range.firstSequence)));
+        return { isWholeMap: false, instances };
+    }
+    /** The chunk loads of a Step that rebuilds the model input. */
+    modelInputChunkLoads(context, summary) {
+        if (this.config.compaction === undefined) {
+            return { isWholeMap: true, instances: [] };
+        }
+        return this.messageChunkLoads(context, this.readModelInputFirstSequence(context, summary));
+    }
+    /** Moves to `RunModel`, loading the window and the archive chunks of the model input. */
+    goToRunModel(context, summary = this.readRunnerContextSummary(context)) {
+        return this.goToModelInputStep(context, agentSessionStepTypes.runModel, summary);
+    }
+    /** Moves to `ApplyTurnControl`, which may rebuild the model input for unfinished-turn messages. */
+    goToApplyTurnControl(context) {
+        return this.goToModelInputStep(context, agentSessionStepTypes.applyTurnControl, this.readRunnerContextSummary(context));
+    }
+    goToModelInputStep(context, stepType, summary) {
+        const options = messageStepOptions(this.persistence, stepType, this.modelInputChunkLoads(context, summary), this.config.runModelLimit);
+        return goToMany(StepMovement.of(new StepRef(stepType), undefined, options));
+    }
     /** Returns the turn's tool call records in deferral order; requires the AgentToolCalls load. */
     readTurnToolCalls(context, turnId) {
         if (turnId === null) {
@@ -92,8 +259,164 @@ export class AgentSessionTransitions {
     writeToolCall(context, toolCall) {
         this.persistence.agentToolCalls.set(context, toolCall.toolCallId, toolCall);
     }
-    /** Appends messages, writes the advanced AgentState, and returns it. */
-    appendMessages(context, state, turnId, frameworkMessages) {
+    /**
+     * Writes a final record, its `tool_call_finished` event, and its `ToolCallResults` notice in one commit.
+     * Pass the Step's open events writer, if it has one, so the event keeps its order.
+     */
+    finishToolCall(context, toolCall, events) {
+        if (!isFinalToolCallStatus(toolCall.status)) {
+            throw new TypeError(`tool call ${toolCall.toolCallId} is not final: ${toolCall.status}`);
+        }
+        this.writeToolCall(context, toolCall);
+        const finalStatus = toolCall.status;
+        if (events === undefined) {
+            this.writeEvents(context, toolCall.turnId, (writer) => writer.writeToolCallFinished(toolCall.toolCallId, toolCall.toolName, finalStatus));
+        }
+        else {
+            events.writeToolCallFinished(toolCall.toolCallId, toolCall.toolName, finalStatus);
+        }
+        this.publishToolCallResult(context, toolCall.toolCallId);
+    }
+    writeInterruptRaised(events, interrupt) {
+        events.writeEvent("interrupt_raised", {
+            interrupt_id: interrupt.interruptId,
+            kind: interrupt.kind,
+            tool_call_id: interrupt.toolCallId,
+            tool_name: interrupt.toolName,
+            deadline: interrupt.deadline,
+            question: interrupt.question ?? null,
+            choices: interrupt.choices ?? [],
+            allows_free_text: interrupt.allowsFreeText ?? true,
+        });
+    }
+    writeInterruptResolved(context, turnId, resolution) {
+        this.writeEvents(context, turnId, (events) => events.writeEvent("interrupt_resolved", {
+            interrupt_id: resolution.interruptId,
+            kind: resolution.kind,
+            approved: resolution.isApproved,
+            answered: resolution.isAnswered,
+            rejection_message: resolution.rejectionMessage,
+            cancellation_reason: resolution.cancellationReason ?? null,
+        }));
+    }
+    /** Writes the `interrupt_resolved` event of an interrupt that steering or `cancel_turn` removed. */
+    writeInterruptCancelled(context, turnId, interruptId, kind, reason) {
+        this.writeInterruptResolved(context, turnId, {
+            interruptId,
+            kind,
+            isApproved: false,
+            isAnswered: false,
+            rejectionMessage: toolCallCancellationResults[reason],
+            cancellationReason: reason,
+        });
+    }
+    /**
+     * Returns why the turn ends at this boundary, or `null`. It reads committed state only: a matching
+     * `TurnCancellationRequest`, then any pending steered message.
+     */
+    readTurnControlReason(context, turnId) {
+        if (turnId === null) {
+            return null;
+        }
+        const request = this.persistence.turnCancellationRequest.get(context);
+        // Turn IDs never repeat, so a request for an earlier turn never matches.
+        if (request !== undefined && request.turnId === turnId) {
+            return "turn_cancelled";
+        }
+        return context.channelSize(this.persistence.steeredUserMessages) > 0 ? "steered" : null;
+    }
+    /** Builds the runner's view of a turn; every record must be final. */
+    createTurnContext(context, state, turnId, toolCalls, events, heartbeat) {
+        const runnerToolCalls = toolCalls.map(toRunnerToolCall);
+        const toolCallsById = new Map(runnerToolCalls.map((toolCall) => [toolCall.toolCallId, toolCall]));
+        const frameworkRunState = this.readFrameworkRunState(context);
+        const contextSummary = this.readRunnerContextSummary(context);
+        const firstStoredSequence = this.readFirstStoredSequence(context);
+        if (contextSummary === null && firstStoredSequence > 1) {
+            console.warn(`dex-agents: session ${context.flowId} stores no messages before ${firstStoredSequence}; retention ` +
+                "deleted them, and this runner cannot use the context summary that covers them");
+        }
+        return {
+            flowId: context.flowId,
+            turnId,
+            attempt: context.attempt,
+            stepExecutionId: context.stepExecutionId,
+            messages: this.readMessages(context, this.readModelInputFirstSequence(context, contextSummary), state.nextMessageSequence),
+            frameworkRunState,
+            isResuming: frameworkRunState !== null,
+            toolCalls: runnerToolCalls,
+            events,
+            cancellationSignal: context.cancellationSignal,
+            deadline: context.deadline,
+            enabledBuiltInTools: this.config.builtInTools,
+            interactionMode: state.interactionMode ?? "chat",
+            plan: this.readOptionalAgentPlan(context),
+            contextSummary,
+            sessionSettings: this.readTurnSessionSettings(context),
+            toolPolicies: this.config.toolPolicies,
+            defaultToolEffect: this.config.defaultToolEffect,
+            resolveToolPolicy: (toolName, frameworkEffect) => this.resolveToolPolicy(toolName, frameworkEffect),
+            recordedToolCall: (toolCallId) => toolCallsById.get(toolCallId),
+            heartbeat,
+        };
+    }
+    /**
+     * Returns the runner's unfinished-turn messages for an ending turn, or `null` when the runner has no such
+     * method or it throws, so the caller stores its note instead.
+     */
+    buildUnfinishedTurnMessages(context, state, turnId, finalToolCalls) {
+        if (this.runner.buildUnfinishedTurnMessages === undefined) {
+            return null;
+        }
+        const events = this.createEventWriter(context, turnId);
+        try {
+            const turnContext = this.createTurnContext(context, state, turnId, finalToolCalls, events, () => Promise.resolve());
+            const messages = this.runner.buildUnfinishedTurnMessages(turnContext);
+            if (!Array.isArray(messages) || !messages.every(isFrameworkMessage)) {
+                throw new TypeError("buildUnfinishedTurnMessages must return an array of framework messages");
+            }
+            return messages;
+        }
+        catch (error) {
+            // A runner defect must not block the end of the turn; the caller's note still tells the model.
+            console.warn(`dex-agents: no unfinished-turn messages are stored for ${turnId}:`, error);
+            return null;
+        }
+        finally {
+            events.close();
+        }
+    }
+    isEnabledBuiltInTool(toolName) {
+        return this.config.builtInTools.has(toolName);
+    }
+    /**
+     * Appends messages, writes the advanced AgentState, and returns it.
+     *
+     * A message goes into the `AgentMessages` window, or, when its own chunk would exceed `messageChunkMaxBytes`,
+     * straight into a chunk of its own, so the first store writes the largest value it ever needs. In the same
+     * commit it moves the oldest window messages into archive chunks while the window is over its size and
+     * applies retention; it writes `AgentMessageIndex` only when one of them changed it. It requires the whole
+     * window to be loaded. With `startsTurn`, `TurnReplySequence` records where the turn's replies begin.
+     */
+    appendMessages(context, state, turnId, frameworkMessages, startsTurn = false) {
+        if (frameworkMessages.length === 0 && !startsTurn) {
+            this.writeAgentState(context, state);
+            return state;
+        }
+        const activeTurnId = state.activeTurnId;
+        if (!startsTurn && activeTurnId !== null && activeTurnId !== undefined) {
+            const stored = this.persistence.turnReplySequence.get(context);
+            if (stored === undefined || stored.turnId !== activeTurnId) {
+                // Recorded before a rollover can move the turn's first messages out of reach.
+                this.persistence.turnReplySequence.set(context, {
+                    turnId: activeTurnId,
+                    sequence: this.readTurnReplySequence(context, state, activeTurnId),
+                });
+            }
+        }
+        const storedIndex = this.readMessageIndex(context);
+        let index = storedIndex ?? emptyMessageIndex();
+        const directChunks = [];
         let nextMessageSequence = state.nextMessageSequence;
         const createdAt = new Date().toISOString();
         for (const frameworkMessage of frameworkMessages) {
@@ -109,32 +432,258 @@ export class AgentSessionTransitions {
                 frameworkItem: frameworkMessage.frameworkItem,
                 createdAt,
             };
-            this.persistence.agentMessages.set(context, messageSequenceKey(nextMessageSequence), message);
+            const key = messageSequenceKey(nextMessageSequence);
+            if (messageChunkOverheadBytes + agentMessageBytes(message) > this.config.messageChunkMaxBytes) {
+                this.persistence.agentMessageChunks.set(context, key, { messages: [message] });
+                directChunks.push({ firstSequence: nextMessageSequence, lastSequence: nextMessageSequence });
+            }
+            else {
+                this.persistence.agentMessages.set(context, key, message);
+            }
             nextMessageSequence += 1;
         }
+        if (directChunks.length > 0) {
+            index = { ...index, chunks: [...index.chunks, ...directChunks] };
+        }
+        if (startsTurn) {
+            this.persistence.turnReplySequence.set(context, { turnId, sequence: nextMessageSequence });
+        }
+        index = this.rollOverMessageWindow(context, index, nextMessageSequence);
+        index = this.applyMessageRetention(context, index, nextMessageSequence, this.readContextSummary(context));
+        if (!isSameMessageIndex(storedIndex ?? emptyMessageIndex(), index)) {
+            this.persistence.agentMessageIndex.set(context, index);
+        }
         const advancedState = { ...state, nextMessageSequence };
         this.writeAgentState(context, advancedState);
         return advancedState;
     }
-    /** Appends the user message, opens the next turn, and moves to RunModel. */
-    beginTurn(context, state, text) {
+    /**
+     * Moves the oldest window messages into immutable chunks while the window holds more than its size. A chunk
+     * closes at `messageChunkSize` messages, at `messageChunkMaxBytes` bytes, or before a message stored in its
+     * own chunk. One commit writes at most {@link messageRolloverMaxChunksPerCommit} chunks and
+     * {@link messageRolloverMaxBytesPerCommit} bytes, so a backlog drains over several commits.
+     */
+    rollOverMessageWindow(context, index, nextMessageSequence) {
+        const chunks = [...index.chunks];
+        const directStarts = new Set(chunks.filter((range) => range.firstSequence >= index.windowFirstSequence).map((range) => range.firstSequence));
+        let windowFirstSequence = skipDirectChunks(directStarts, index.windowFirstSequence);
+        const windowMessageCount = () => nextMessageSequence -
+            windowFirstSequence -
+            [...directStarts].filter((sequence) => sequence >= windowFirstSequence).length;
+        let movedChunks = 0;
+        let movedBytes = 0;
+        while (windowMessageCount() > this.config.messageWindowSize && movedChunks < messageRolloverMaxChunksPerCommit) {
+            const messages = [];
+            let chunkBytes = messageChunkOverheadBytes - 1;
+            for (let sequence = windowFirstSequence; sequence < nextMessageSequence && messages.length < this.config.messageChunkSize && !directStarts.has(sequence); sequence += 1) {
+                const message = this.readWindowMessage(context, sequence);
+                const withMessageBytes = chunkBytes + 1 + agentMessageBytes(message);
+                if (messages.length > 0 && withMessageBytes > this.config.messageChunkMaxBytes) {
+                    break;
+                }
+                messages.push(message);
+                chunkBytes = withMessageBytes;
+            }
+            if (movedChunks > 0 && movedBytes + chunkBytes > messageRolloverMaxBytesPerCommit) {
+                break;
+            }
+            for (const message of messages) {
+                this.persistence.agentMessages.delete(context, messageSequenceKey(message.sequence));
+            }
+            this.persistence.agentMessageChunks.set(context, messageSequenceKey(windowFirstSequence), { messages });
+            const lastSequence = windowFirstSequence + messages.length - 1;
+            chunks.push({ firstSequence: windowFirstSequence, lastSequence });
+            windowFirstSequence = skipDirectChunks(directStarts, lastSequence + 1);
+            movedChunks += 1;
+            movedBytes += chunkBytes;
+        }
+        if (windowFirstSequence === index.windowFirstSequence && chunks.length === index.chunks.length) {
+            return index;
+        }
+        chunks.sort((left, right) => left.firstSequence - right.firstSequence);
+        return { chunks, firstSequence: firstStoredSequence(chunks, windowFirstSequence), windowFirstSequence };
+    }
+    /**
+     * Deletes the oldest archive chunk while every message in it is summarized and at least `retainedMessageLimit`
+     * stored messages come after it, so the newest `retainedMessageLimit` messages always stay. It runs only with
+     * compaction and a limit.
+     */
+    applyMessageRetention(context, index, nextMessageSequence, summary) {
+        const limit = this.config.retainedMessageLimit;
+        if (this.config.compaction === undefined || limit === null || summary === null) {
+            return index;
+        }
+        let deletedChunks = 0;
+        for (const range of index.chunks) {
+            // Only archived chunks, before the window; a message stored in its own chunk waits for the rollover.
+            if (range.firstSequence >= index.windowFirstSequence ||
+                range.lastSequence > summary.lastSequence ||
+                nextMessageSequence - (range.lastSequence + 1) < limit) {
+                break;
+            }
+            this.persistence.agentMessageChunks.delete(context, messageSequenceKey(range.firstSequence));
+            deletedChunks += 1;
+        }
+        if (deletedChunks === 0) {
+            return index;
+        }
+        const chunks = index.chunks.slice(deletedChunks);
+        return { ...index, chunks, firstSequence: firstStoredSequence(chunks, index.windowFirstSequence) };
+    }
+    /** Appends the turn's user messages, in order, opens the next turn, and moves to RunModel. */
+    beginTurn(context, state, messages, stepType, interactionMode = "chat", executedPlan, wasPlanDraft = false, sessionSettings = this.readSessionSettings(context)) {
         const turnId = `turn-${state.turnCount + 1}`;
-        const userMessage = this.runner.buildUserMessage(text);
-        if (userMessage.role !== "user") {
-            throw new TypeError("buildUserMessage must return a message with role user");
+        // The turn keeps these until it ends; later updates wait for the next turn.
+        if (sessionSettings !== null && Object.keys(sessionSettings).length > 0) {
+            this.persistence.turnSessionSettings.set(context, { turnId, sessionSettings });
+        }
+        else if (this.persistence.turnSessionSettings.get(context) !== undefined) {
+            this.persistence.turnSessionSettings.delete(context);
         }
         const sequence = state.nextMessageSequence;
-        const stateWithMessage = this.appendMessages(context, state, turnId, [userMessage]);
-        this.writeAgentState(context, { ...stateWithMessage, status: "running_model", activeTurnId: turnId });
-        this.writeEvents(context, turnId, (events) => events.writeEvent("turn_started", { sequence }));
-        return goTo(new StepRef(agentSessionStepTypes.runModel), undefined);
+        return this.tracer.traceUserMessageActivation(context, stepType, turnId, messageSequenceKey(sequence), messages.map((message) => message.text).join("\n"), () => {
+            const userMessages = messages.map((message) => this.runner.buildUserMessage(message.text));
+            if (userMessages.some((userMessage) => userMessage.role !== "user")) {
+                throw new TypeError("buildUserMessage must return a message with role user");
+            }
+            const stateWithMessage = this.appendMessages(context, state, turnId, userMessages, true);
+            this.writeAgentState(context, {
+                ...stateWithMessage,
+                status: "running_model",
+                activeTurnId: turnId,
+                interactionMode,
+                acceptsTurnControl: true,
+            });
+            this.writeEvents(context, turnId, (events) => {
+                events.writeEvent("turn_started", { sequence });
+                if (executedPlan !== undefined) {
+                    events.writeEvent("plan_execution_started", { revision: executedPlan.revision });
+                    if (wasPlanDraft) {
+                        writePlanUpdated(events, executedPlan);
+                    }
+                }
+            });
+            return this.goToRunModel(context);
+        });
+    }
+    /**
+     * Returns the mode of a turn that these user messages start: `planning` when plan mode is enabled and a
+     * message has `planMode` or a `draft` plan exists, else `chat`.
+     */
+    decideInteractionMode(context, messages) {
+        if (!this.config.planModeEnabled) {
+            return "chat";
+        }
+        const isPlanModeRequested = messages.some((message) => message.planMode === true);
+        return isPlanModeRequested || this.readOptionalAgentPlan(context)?.status === "draft" ? "planning" : "chat";
+    }
+    /** Ends a steered or cancelled turn with its unfinished-turn messages, or with a note; returns the new state. */
+    endControlledTurn(context, initialState, turnId, steeredMessageCount) {
+        const transitions = this;
+        const persistence = this.persistence;
+        const toolCalls = transitions.readTurnToolCalls(context, turnId);
+        const openToolCall = toolCalls.find((toolCall) => !isFinalToolCallStatus(toolCall.status));
+        if (openToolCall !== undefined) {
+            throw new Error(`${turnId} ended before tool call ${openToolCall.toolCallId} finished`);
+        }
+        const isCancelled = transitions.readTurnControlReason(context, turnId) === "turn_cancelled";
+        const storedMessageCount = transitions.countStoredTurnReplies(context, initialState, turnId);
+        let messages = transitions.buildUnfinishedTurnMessages(context, initialState, turnId, toolCalls);
+        if (messages === null) {
+            messages = [];
+            if (toolCalls.length > 0) {
+                // The records are deleted below; the note keeps the next model from repeating them.
+                const note = transitions.runner.buildUserMessage(buildToolCallNote(isCancelled ? turnCancelledNoteHeader : turnSteeredNoteHeader, toolCalls));
+                if (note.role !== "user") {
+                    throw new TypeError("buildUserMessage must return a message with role user");
+                }
+                messages = [note];
+            }
+        }
+        const stateWithMessages = transitions.appendMessages(context, initialState, turnId, messages);
+        for (const toolCall of toolCalls) {
+            persistence.agentToolCalls.delete(context, toolCall.toolCallId);
+        }
+        persistence.frameworkRunState.delete(context);
+        const endedState = {
+            ...stateWithMessages,
+            status: "waiting_for_user_message",
+            turnCount: stateWithMessages.turnCount + 1,
+            activeTurnId: null,
+            lastTurnError: null,
+            acceptsTurnControl: false,
+        };
+        transitions.writeAgentState(context, endedState);
+        const messageCount = storedMessageCount + messages.length;
+        transitions.writeEvents(context, turnId, (events) => isCancelled
+            ? events.writeEvent("turn_cancelled", { message_count: messageCount })
+            : events.writeEvent("turn_steered", {
+                steered_message_count: steeredMessageCount,
+                message_count: messageCount,
+            }));
+        return endedState;
     }
     goToAwaitUserMessage() {
         return goTo(new StepRef(agentSessionStepTypes.awaitUserMessage), undefined);
     }
+    /** Reports whether `cancel_turn` stopped this turn; reads committed state only. */
+    isTurnCancelled(context, turnId) {
+        return this.readTurnControlReason(context, turnId) === "turn_cancelled";
+    }
     resolveToolPolicy(toolName, frameworkEffect) {
         return resolveToolPolicy(toolName, this.config.toolPolicies, this.config.defaultToolEffect, frameworkEffect);
     }
+    /**
+     * Asks the application's spend limit whether a model call may run.
+     * @returns The move that ends the refused turn, or `null` to call the model.
+     * @throws What the check threw, which fails the attempt so no model call runs unchecked.
+     */
+    async checkSpendLimit(context, state, turnId, stepType) {
+        const spendLimit = this.config.spendLimit;
+        if (spendLimit === undefined) {
+            return null;
+        }
+        const decision = await withinSpendLimitCallTimeout("checkModelCall", spendLimit.checkModelCall({
+            flowId: context.flowId,
+            turnId,
+            stepType,
+            attempt: context.attempt,
+            sessionSettings: this.readTurnSessionSettings(context),
+            sessionUsage: this.readAgentUsage(context),
+        }));
+        if (typeof decision?.isAllowed !== "boolean") {
+            throw new TypeError("checkModelCall must return a ModelCallDecision");
+        }
+        if (decision.isAllowed) {
+            return null;
+        }
+        // RecordTurnFailure loads what ending a turn needs, which CompactContext does not.
+        this.writeAgentState(context, { ...state, lastTurnError: `${modelCallRefusedErrorPrefix}: ${decision.reason}` });
+        return goTo(new StepRef(agentSessionStepTypes.recordTurnFailure), undefined);
+    }
+    /** Reports a finished model call. A failure is logged: failing the attempt would pay for the call again. */
+    async reportModelUsage(context, turnId, stepType, usage) {
+        const spendLimit = this.config.spendLimit;
+        if (spendLimit === undefined) {
+            return;
+        }
+        const reportId = `${context.flowId}/${turnId}/${context.stepExecutionId}/${context.attempt}`;
+        try {
+            await withinSpendLimitCallTimeout("reportModelUsage", spendLimit.reportModelUsage({
+                reportId,
+                flowId: context.flowId,
+                turnId,
+                stepType,
+                attempt: context.attempt,
+                sessionSettings: this.readTurnSessionSettings(context),
+                usage,
+                sessionUsage: addAgentUsage(this.readAgentUsage(context), usage),
+            }));
+        }
+        catch (error) {
+            console.warn(`dex-agents: reportModelUsage failed for ${reportId}:`, error);
+        }
+    }
     recordUsage(context, usage, events) {
         const sessionUsage = addAgentUsage(this.readAgentUsage(context), usage);
         this.persistence.agentUsage.set(context, sessionUsage);
@@ -156,10 +705,10 @@ export class AgentSessionTransitions {
         }
     }
     /** Runs an operation while recording a heartbeat every 20 seconds. */
-    async runWithHeartbeats(context, operation) {
+    async runWithHeartbeats(context, operation, recordHeartbeat = () => this.recordHeartbeat(context)) {
         const heartbeatTimer = setInterval(() => {
             // A rejected heartbeat means the attempt already ended; the operation result decides the outcome.
-            this.recordHeartbeat(context).catch(() => undefined);
+            recordHeartbeat().catch(() => undefined);
         }, heartbeatIntervalMs);
         try {
             return await operation();
@@ -172,6 +721,142 @@ export class AgentSessionTransitions {
         return context.recordHeartbeat(context.stepExecutionId, stringCodec);
     }
 }
+/**
+ * Heartbeats of one tool Step attempt. Each carries the latest checkpoint, else the Step execution ID,
+ * which every attempt shares and so never reads as a checkpoint.
+ */
+export class ToolStepHeartbeats {
+    context;
+    previousCheckpoint;
+    checkpoint;
+    constructor(context) {
+        this.context = context;
+        const previous = context.hasLastHeartbeatValue() ? context.getLastHeartbeatValue(stringCodec) : undefined;
+        this.previousCheckpoint = previous === undefined || previous === context.stepExecutionId ? undefined : previous;
+        // Every heartbeat replaces the saved value, so carry the earlier attempt's checkpoint forward.
+        this.checkpoint = this.previousCheckpoint;
+    }
+    record() {
+        return this.context.recordHeartbeat(this.checkpoint ?? this.context.stepExecutionId, stringCodec);
+    }
+    saveCheckpoint(checkpoint) {
+        this.checkpoint = checkpoint;
+        return this.record();
+    }
+}
+/** Returns a record as a runner sees it; only records that runners may see are accepted. */
+export function toRunnerToolCall(record) {
+    if (record.status === "awaiting_answer" || record.status === "waiting_for_timer" || record.status === "waiting_for_task") {
+        throw new TypeError(`tool call ${record.toolCallId} is still ${record.status}`);
+    }
+    return record;
+}
+function isFrameworkMessage(value) {
+    const message = value;
+    const isNullableString = (field) => field === null || typeof field === "string";
+    return (typeof message === "object" &&
+        message !== null &&
+        (message.role === "user" || message.role === "assistant" || message.role === "tool") &&
+        typeof message.frameworkItem === "string" &&
+        isNullableString(message.text) &&
+        isNullableString(message.toolCallId) &&
+        isNullableString(message.toolName) &&
+        isNullableString(message.toolArguments) &&
+        isNullableString(message.toolOutput));
+}
+/** Moves to `FinishTurnCancellation` for one turn; its locks come from the Step's own options. */
+export function finishTurnCancellationMovement(turnId) {
+    return StepMovement.of(new StepRef(agentSessionStepTypes.finishTurnCancellation), turnId);
+}
+/** Reports whether `cancel_turn` abandons this call's started task. */
+export function isAbandonedToolTask(toolCall) {
+    return ((toolCall.taskId ?? null) !== null &&
+        (toolCall.status === "waiting_for_task" || toolCall.status === "awaiting_answer"));
+}
+/** Reports whether steering or `cancel_turn` may abandon a call that waits in a session Step. */
+export function isCancellableByTurnControl(toolCall) {
+    // Each of these waits for a person or a Timer; the call has taken no effect. A task's question
+    // waits for a person too, but its task has started, and a waiting_for_task record is never listed.
+    return (toolCall.status === "awaiting_approval" ||
+        (toolCall.status === "awaiting_answer" && (toolCall.taskId ?? null) === null) ||
+        toolCall.status === "waiting_for_timer");
+}
+/** Returns a record that steering or `cancel_turn` abandoned before the call started. */
+export function cancelledToolCall(toolCall, reason) {
+    return {
+        ...toolCall,
+        status: "rejected",
+        rejectionMessage: toolCallCancellationResults[reason],
+        cancellationReason: reason,
+        inputQuestion: null,
+        inputChoices: [],
+        inputAllowsFreeText: true,
+    };
+}
+/**
+ * Returns the kept chunk that holds a message, found by binary search over the index's ordered ranges, or
+ * `undefined` when the message is in the window.
+ */
+export function findMessageChunkRange(index, sequence) {
+    let low = 0;
+    let high = index.chunks.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const range = index.chunks[middle];
+        if (sequence < range.firstSequence) {
+            high = middle - 1;
+        }
+        else if (sequence > range.lastSequence) {
+            low = middle + 1;
+        }
+        else {
+            return range;
+        }
+    }
+    if (sequence < index.windowFirstSequence) {
+        throw new Error(`AgentMessageIndex lists no chunk that holds message ${sequence}`);
+    }
+    return undefined;
+}
+/** The index of a session whose messages are all in the window, as a new session or a 0.1.0 one stores them. */
+function emptyMessageIndex() {
+    return { chunks: [], firstSequence: 1, windowFirstSequence: 1 };
+}
+/** The oldest stored message: the first archived chunk's first sequence, else the window's first. */
+function firstStoredSequence(chunks, windowFirstSequence) {
+    const first = chunks[0];
+    return first !== undefined && first.firstSequence < windowFirstSequence ? first.firstSequence : windowFirstSequence;
+}
+/** Returns the first sequence at or after `sequence` that is not a message stored in its own chunk. */
+function skipDirectChunks(directStarts, sequence) {
+    let next = sequence;
+    while (directStarts.has(next)) {
+        next += 1;
+    }
+    return next;
+}
+/** Whether a chunk holds exactly the messages of its range, in order. */
+export function isMessageChunkOfRange(chunk, range) {
+    return (chunk.messages.length === range.lastSequence - range.firstSequence + 1 &&
+        chunk.messages.every((message, offset) => message.sequence === range.firstSequence + offset));
+}
+/** The UTF-8 bytes of a message's JSON as this core stores it. */
+function agentMessageBytes(message) {
+    return utf8Encoder.encode(JSON.stringify(encodeAgentMessage(message))).length;
+}
+function isSameMessageIndex(left, right) {
+    return (left.firstSequence === right.firstSequence &&
+        left.windowFirstSequence === right.windowFirstSequence &&
+        left.chunks.length === right.chunks.length &&
+        left.chunks.every((range, offset) => range.firstSequence === right.chunks[offset]?.firstSequence &&
+            range.lastSequence === right.chunks[offset]?.lastSequence));
+}
+/** Counts a turn's stored messages after the user messages that started it. */
+export function countMessagesAfterUserMessages(messages, turnId) {
+    const turnMessages = messages.filter((message) => message.turnId === turnId);
+    const firstNonUserIndex = turnMessages.findIndex((message) => message.role !== "user");
+    return firstNonUserIndex === -1 ? 0 : turnMessages.length - firstNonUserIndex;
+}
 export function toolStepTypeForEffect(effect) {
     switch (effect) {
         case "read":
@@ -184,12 +869,19 @@ export function toolStepTypeForEffect(effect) {
 }
 /** Returns the text of the failure that selected a recovery Step. */
 export function readRecoveryDetail(context) {
-    const recoveryError = context.recoveryError;
+    return recoveryErrorDetail(context.recoveryError);
+}
+/** Returns the text of a recovery error: its detail, else its error type, else "unknown failure". */
+export function recoveryErrorDetail(recoveryError) {
     if (recoveryError === undefined) {
         return "unknown failure";
     }
     return recoveryError.detail !== "" ? recoveryError.detail : recoveryError.errorType;
 }
+/** Writes `plan_updated` with the plan's revision, status, and task count. */
+export function writePlanUpdated(events, plan) {
+    events.writeEvent("plan_updated", { revision: plan.revision, status: plan.status, task_count: plan.tasks.length });
+}
 function usagePayload(usage) {
     return {
         model_calls: usage.modelCalls,
@@ -199,4 +891,12 @@ function usagePayload(usage) {
         reasoning_tokens: usage.reasoningTokens,
     };
 }
+/**
+ * Returns the settings of the active turn from its stored copy: the copy's settings while it belongs to that
+ * turn, else `{}`. A turn that a Worker without session settings started, such as 0.1.0, leaves an earlier
+ * turn's copy in place, which must not apply.
+ */
+export function selectTurnSessionSettings(stored, activeTurnId) {
+    return stored !== null && activeTurnId !== null && stored.turnId === activeTurnId ? stored.sessionSettings : {};
+}
 //# sourceMappingURL=agent-session-transitions.js.map