@superdurable/dex-agents 0.1.0 → 0.2.0

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

@@ -5,16 +5,19 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
-import { ExecuteFailure, StepMovement, int64Codec, StepRef, Timer, Wait, deadEnd, goTo, goToMany, stringCodec, voidCodec, } from "@superdurable/dex";
+import { ExecuteFailure, StepMovement, int64Codec, StepRef, StepAttemptProgress, Timer, Wait, deadEnd, forceFail, goTo, goToMany, stringCodec, voidCodec, } from "@superdurable/dex";
+import { buildPlanClearedOutput, buildPlanUpdatedOutput, isBlankText, validateAskUserArguments, validateDurableWaitArguments, validateWriteTodosArguments, writeTodosCalledMoreThanOnce, } from "./agent-built-in-tools.js";
+import { isCompactionTriggered, isContextCompactionRunner, readRetainedTokenBudget, } from "./agent-context-compaction.js";
 import { ToolExecutionError, } from "./agent-framework-runner.js";
-import { agentSessionStartInputCodec } from "./agent-session-codecs.js";
-import { agentSessionStepTypes, readRecoveryDetail, toolStepTypeForEffect, } from "./agent-session-transitions.js";
-import { approvalDeadlinePassed, buildTurnFailureNote, emptyAgentUsage, isFinalToolCallStatus, } from "./agent-session-values.js";
-const minuteMs = 60_000;
-// Recovery Steps must eventually run; cap their backoff so a returning Worker picks them up quickly.
-const recoveryRetry = { maximumIntervalMs: 5_000 };
-// An ASYNC FlowConfig could replay a committed result after a Server failover, re-running a write.
-const syncDurability = { waitForDurability: "sync", executeDurability: "sync" };
+import { buildPlanExecutionMessage, planningTurnToolRejection, planStatusAfterWrite } from "./agent-plans.js";
+import { agentSessionStartInputCodec, turnFailureRouteInputCodec } from "./agent-session-codecs.js";
+import { messageStepOptions, minuteMs, modelCallStepOptions, recoveryRetry, syncDurability, } from "./agent-session-step-options.js";
+import { agentSessionStepTypes, allPendingMessages, cancelledToolCall, isAbandonedToolTask, isCancellableByTurnControl, readRecoveryDetail, recoveryErrorDetail, toRunnerToolCall, toolStepTypeForEffect, ToolStepHeartbeats, writePlanUpdated, } from "./agent-session-transitions.js";
+import { messageSequenceKey, planExecutionKey, } from "./agent-session-persistence.js";
+import { checkStoredSessionSettings } from "./agent-session-settings.js";
+import { approvalDeadlinePassed, blankToolTaskId, buildTurnFailureNote, emptyAgentUsage, invalidToolTaskPollInterval, isFinalToolCallStatus, missingToolTaskPoller, toolCallNotRunErrorPrefix, toolTaskAbandonedError, } from "./agent-session-values.js";
+/** Longest wait between two polls of a tool task, as in the Python core; a longer interval is shortened. */
+const maximumToolTaskPollIntervalSeconds = 86_400;
 // An int64 Value, as the Python core's Step[int] encodes it.
 const expectedResultCountCodec = {
     typeName: "ExpectedResultCount",
@@ -22,6 +25,8 @@ const expectedResultCountCodec = {
     encode: (value) => int64Codec.encode(BigInt(requirePositiveResultCount(value))),
     decode: (value) => requirePositiveResultCount(Number(int64Codec.decode(value))),
 };
+/** Start of the Flow failure reason when `StartAgentSession` refuses the start input's settings. */
+export const invalidStartSessionSettingsReason = "dex-agents: the start input's session_settings are not valid session settings";
 export class StartAgentSessionStep {
     transitions;
     inputCodec = agentSessionStartInputCodec;
@@ -32,7 +37,7 @@ export class StartAgentSessionStep {
         return agentSessionStepTypes.startAgentSession;
     }
     getStepOptions() {
-        return syncDurability;
+        return { ...syncDurability, executeLoadAttributeMaps: [this.transitions.persistence.agentMessages] };
     }
     execute(context, input) {
         const persistence = this.transitions.persistence;
@@ -42,17 +47,32 @@ export class StartAgentSessionStep {
             activeTurnId: null,
             nextMessageSequence: 1,
             lastTurnError: null,
+            acceptsTurnControl: false,
         };
+        const sessionSettings = input.sessionSettings ?? null;
+        if (sessionSettings !== null) {
+            try {
+                checkStoredSessionSettings(sessionSettings);
+            }
+            catch (error) {
+                // Every retry would fail the same way, so the session fails now.
+                return forceFail(`${invalidStartSessionSettingsReason}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (Object.keys(sessionSettings).length > 0) {
+                persistence.sessionSettings.set(context, sessionSettings);
+            }
+        }
         this.transitions.writeAgentState(context, state);
         persistence.agentUsage.set(context, emptyAgentUsage());
         persistence.pendingInterrupts.set(context, []);
         const initialMessage = input.initialMessage;
-        if (initialMessage === null || initialMessage.trim() === "") {
+        if (initialMessage === null || isBlankText(initialMessage)) {
             return this.transitions.goToAwaitUserMessage();
         }
-        return this.transitions.beginTurn(context, state, initialMessage);
+        return this.transitions.beginTurn(context, state, [{ text: initialMessage }], this.getStepType(), "chat", undefined, false, sessionSettings);
     }
 }
+/** Waits for one queued user message, or an approved plan execution, and starts its turn. */
 export class AwaitUserMessageStep {
     transitions;
     inputCodec = voidCodec;
@@ -63,18 +83,69 @@ export class AwaitUserMessageStep {
         return agentSessionStepTypes.awaitUserMessage;
     }
     getStepOptions() {
-        return syncDurability;
+        // The lock keeps a turn from starting while cancel_turn decides about the last one.
+        // Storing the turn's user messages may move the oldest window messages into a chunk.
+        return {
+            ...syncDurability,
+            executeLoadAttributeMaps: [this.transitions.persistence.agentMessages],
+            executeLockAttributes: [this.transitions.persistence.turnCancellationRequest.lock()],
+        };
     }
-    waitFor() {
-        return Wait.until(this.transitions.persistence.queuedUserMessages.forOne());
+    waitFor(context) {
+        const persistence = this.transitions.persistence;
+        // Dex selects Channel conditions in argument order: a steer, a queued message, a plan.
+        const conditions = [
+            persistence.turnControlRequests.range(1, allPendingMessages),
+            persistence.queuedUserMessages.forOne(),
+        ];
+        const plan = this.transitions.readOptionalAgentPlan(context);
+        // Keyed by revision, so an approval of an earlier revision never starts a turn.
+        if (plan !== null && isExecutablePlanStatus(plan.status)) {
+            conditions.push(persistence.planExecutions.forOne(planExecutionKey(plan.revision)));
+        }
+        return Wait.anyOf(...conditions);
     }
     execute(context) {
-        const [message] = context.channelResults(this.transitions.persistence.queuedUserMessages);
-        if (message === undefined || message.text.trim() === "") {
-            return this.transitions.goToAwaitUserMessage();
+        const transitions = this.transitions;
+        const persistence = transitions.persistence;
+        if (context.channelResults(persistence.turnControlRequests).length > 0) {
+            return transitions.goToApplyTurnControl(context);
+        }
+        const [message] = context.channelResults(persistence.queuedUserMessages);
+        if (message !== undefined) {
+            if (isBlankText(message.text)) {
+                return transitions.goToAwaitUserMessage();
+            }
+            return this.beginUserMessageTurn(context, message);
         }
-        return this.transitions.beginTurn(context, this.transitions.readAgentState(context), message.text);
+        const plan = transitions.readOptionalAgentPlan(context);
+        const [execution] = plan === null ? [] : context.channelResults(persistence.planExecutions, planExecutionKey(plan.revision));
+        if (execution === undefined) {
+            return transitions.goToAwaitUserMessage();
+        }
+        if (persistence.pendingPlanExecution.get(context) !== undefined) {
+            persistence.pendingPlanExecution.delete(context);
+        }
+        if (plan === null || execution.revision !== plan.revision || !isExecutablePlanStatus(plan.status)) {
+            return transitions.goToAwaitUserMessage();
+        }
+        const wasPlanDraft = plan.status !== "active";
+        const executedPlan = wasPlanDraft
+            ? { ...plan, status: "active", updatedAt: new Date().toISOString() }
+            : plan;
+        if (wasPlanDraft) {
+            persistence.agentPlan.set(context, executedPlan);
+        }
+        return transitions.beginTurn(context, transitions.readAgentState(context), [{ text: buildPlanExecutionMessage(plan.revision) }], this.getStepType(), "executing", executedPlan, wasPlanDraft);
     }
+    beginUserMessageTurn(context, message) {
+        const transitions = this.transitions;
+        return transitions.beginTurn(context, transitions.readAgentState(context), [message], this.getStepType(), transitions.decideInteractionMode(context, [message]));
+    }
+}
+/** Plan statuses that `execute_plan` accepts and `AwaitUserMessage` waits for. */
+export function isExecutablePlanStatus(status) {
+    return status === "draft" || status === "active";
 }
 /** Makes the turn's next model call and fans the requested tool calls out to parallel Steps. */
 export class RunModelStep {
@@ -87,15 +158,8 @@ export class RunModelStep {
         return agentSessionStepTypes.runModel;
     }
     getStepOptions() {
-        const persistence = this.transitions.persistence;
-        return {
-            ...syncDurability,
-            executeMethodTimeoutMs: 15 * minuteMs,
-            heartbeatTimeoutMs: 2 * minuteMs,
-            executeRetry: { maximumAttempts: 3, totalDurationMs: 30 * minuteMs },
-            executeFailure: ExecuteFailure.proceedTo(new StepRef(agentSessionStepTypes.recordTurnFailure)),
-            executeLoadAttributeMaps: [persistence.agentMessages, persistence.agentToolCalls],
-        };
+        // Each movement into RunModel adds the archive chunks of the model input.
+        return messageStepOptions(this.transitions.persistence, this.getStepType(), staticMessageChunkLoads(this.transitions));
     }
     async execute(context) {
         const transitions = this.transitions;
@@ -109,40 +173,56 @@ export class RunModelStep {
         if (openToolCall !== undefined) {
             throw new Error(`RunModel for ${turnId} started before tool call ${openToolCall.toolCallId} finished`);
         }
-        const toolCallsById = new Map(toolCalls.map((toolCall) => [toolCall.toolCallId, toolCall]));
-        const frameworkRunState = transitions.readFrameworkRunState(context);
+        const decision = this.decideBeforeModelCall(context, turnId);
+        if (decision !== null) {
+            return decision;
+        }
         const events = transitions.createEventWriter(context, turnId);
         try {
-            const turnContext = {
-                flowId: context.flowId,
-                turnId,
-                attempt: context.attempt,
-                messages: transitions.readMessages(context, 1, state.nextMessageSequence),
-                frameworkRunState,
-                isResuming: frameworkRunState !== null,
-                toolCalls,
-                events,
-                cancellationSignal: context.cancellationSignal,
-                deadline: context.deadline,
-                resolveToolPolicy: (toolName, frameworkEffect) => transitions.resolveToolPolicy(toolName, frameworkEffect),
-                recordedToolCall: (toolCallId) => toolCallsById.get(toolCallId),
-                heartbeat: () => transitions.recordHeartbeat(context),
-            };
-            const outcome = await transitions.runWithHeartbeats(context, () => transitions.runner.runModelStep(turnContext));
-            switch (outcome?.kind) {
-                case "completed":
-                    return this.completeTurn(context, state, turnId, toolCalls, outcome, events);
-                case "tool_calls_requested":
-                    return this.requestToolCalls(context, state, turnId, toolCalls, outcome, events);
-                default:
-                    throw new TypeError("runModelStep must return a TurnCompleted or ToolCallsRequested outcome");
+            const turnContext = transitions.createTurnContext(context, state, turnId, toolCalls, events, () => transitions.recordHeartbeat(context));
+            const throughSequence = await this.selectCompactionBeforeModelCall(turnContext, state);
+            if (throughSequence !== null) {
+                return this.startCompaction(context, state, turnContext.contextSummary ?? null, throughSequence);
             }
+            return await transitions.tracer.traceModelCall(context, this.getStepType(), turnContext, async (modelCallSpan) => {
+                const outcome = await transitions.runWithHeartbeats(context, () => transitions.runner.runModelStep(turnContext));
+                switch (outcome?.kind) {
+                    case "completed": {
+                        modelCallSpan.recordOutcome(outcome, appendedMessageKeys(state, outcome.newMessages));
+                        // The index keeps where the turn's replies begin, so the count includes messages summarized away.
+                        const storedTurnMessageCount = transitions.countStoredTurnReplies(context, state, turnId);
+                        return this.completeTurn(context, state, turnId, toolCalls, outcome, storedTurnMessageCount, events);
+                    }
+                    case "tool_calls_requested":
+                        if ((outcome.newMessages?.length ?? 0) > 0 && transitions.runner.buildUnfinishedTurnMessages === undefined) {
+                            // A runner defect: a retry would only repeat the paid model call, so the turn fails now.
+                            modelCallSpan.recordOutcome(outcome, []);
+                            transitions.recordUsage(context, outcome.usage, events);
+                            return recordFailedTurn(transitions, context, state, toolCalls, [], missingUnfinishedTurnMessageBuilder);
+                        }
+                        modelCallSpan.recordOutcome(outcome, appendedMessageKeys(state, outcome.newMessages ?? []));
+                        return this.requestToolCalls(context, state, turnId, toolCalls, outcome, events);
+                    default:
+                        throw new TypeError("runModelStep must return a TurnCompleted or ToolCallsRequested outcome");
+                }
+            });
         }
         finally {
             events.close();
         }
     }
-    completeTurn(context, state, turnId, toolCalls, outcome, events) {
+    /** Returns RunModel's move instead of a model call, or `null` to call the model. */
+    decideBeforeModelCall(context, turnId) {
+        // Execute state is fixed at the first attempt, so this and the compaction check are RunModel's decision points.
+        const transitions = this.transitions;
+        if (transitions.readTurnControlReason(context, turnId) === null) {
+            return null;
+        }
+        // Ending the turn in this commit leaves FinishTurnCancellation no pending turn end to race.
+        transitions.endControlledTurn(context, transitions.readAgentState(context), turnId, context.channelSize(transitions.persistence.steeredUserMessages));
+        return transitions.goToApplyTurnControl(context);
+    }
+    completeTurn(context, state, turnId, toolCalls, outcome, storedTurnMessageCount, events) {
         const transitions = this.transitions;
         const persistence = transitions.persistence;
         const stateWithMessages = transitions.appendMessages(context, state, turnId, outcome.newMessages);
@@ -157,72 +237,301 @@ export class RunModelStep {
             turnCount: state.turnCount + 1,
             activeTurnId: null,
             lastTurnError: null,
+            acceptsTurnControl: false,
         });
-        events.writeEvent("turn_completed", { message_count: outcome.newMessages.length });
+        // The turn's user messages are stored but not counted; incremental runners stored more before now.
+        const messageCount = storedTurnMessageCount + outcome.newMessages.length;
+        events.writeEvent("turn_completed", { message_count: messageCount });
         return transitions.goToAwaitUserMessage();
     }
+    /** Returns the sequence to summarize through before this model call, or `null` to make the call. */
+    async selectCompactionBeforeModelCall(turn, state) {
+        const transitions = this.transitions;
+        const policy = transitions.config.compaction;
+        const runner = transitions.runner;
+        if (policy === undefined || !isContextCompactionRunner(runner)) {
+            return null;
+        }
+        if (!isCompactionTriggered(policy, await runner.estimateInputTokens(turn))) {
+            return null;
+        }
+        const cutoff = await runner.selectCompactionCutoff(turn, readRetainedTokenBudget(policy));
+        // A cutoff that does not advance means nothing more to summarize, so the pair cannot loop.
+        if (cutoff === null || cutoff <= (turn.contextSummary?.lastSequence ?? 0)) {
+            return null;
+        }
+        if (!Number.isSafeInteger(cutoff) || cutoff >= state.nextMessageSequence) {
+            throw new TypeError(`selectCompactionCutoff returned ${String(cutoff)}, which is not a stored message`);
+        }
+        return cutoff;
+    }
+    startCompaction(context, state, previousSummary, throughSequence) {
+        const persistence = this.transitions.persistence;
+        // CompactContext commits once, so this commit is where the status becomes visible.
+        this.transitions.writeAgentState(context, { ...state, status: "compacting_context" });
+        const firstSequence = this.transitions.readModelInputFirstSequence(context, previousSummary);
+        const chunkLoads = this.transitions.messageChunkLoads(context, firstSequence, throughSequence + 1);
+        const input = { throughSequence };
+        return goToMany(StepMovement.of(new StepRef(agentSessionStepTypes.compactContext), input, {
+            ...syncDurability,
+            ...modelCallStepOptions,
+            executeLoadAttributeMaps: [persistence.agentMessages],
+            ...(chunkLoads.instances.length === 0 ? {} : { executeLoadAttributeMapInstances: chunkLoads.instances }),
+        }));
+    }
     requestToolCalls(context, state, turnId, toolCalls, outcome, events) {
-        validateToolCallsRequested(turnId, toolCalls, outcome);
         const transitions = this.transitions;
+        validateToolCallsRequested(turnId, toolCalls, outcome);
+        const newMessages = outcome.newMessages ?? [];
+        const stateWithMessages = newMessages.length === 0 ? state : transitions.appendMessages(context, state, turnId, newMessages);
         transitions.persistence.frameworkRunState.set(context, outcome.frameworkRunState);
         const createdAt = new Date();
-        const deadline = transitions.config.interruptDeadlineMs === undefined
-            ? null
-            : new Date(createdAt.getTime() + transitions.config.interruptDeadlineMs).toISOString();
-        const interrupts = [];
-        // goToMany takes movements of mixed input types, which the SDK types as StepMovement<any>.
-        const movements = [];
+        const batch = {
+            context,
+            turnId,
+            createdAt: createdAt.toISOString(),
+            interruptDeadline: transitions.config.interruptDeadlineMs === undefined
+                ? null
+                : new Date(createdAt.getTime() + transitions.config.interruptDeadlineMs).toISOString(),
+            interrupts: [],
+            traceContext: transitions.tracer.readActivationTraceparent(context),
+            movements: [],
+            events,
+            interactionMode: state.interactionMode ?? "chat",
+            writeTodosCallCount: outcome.toolCalls.filter((toolCall) => toolCall.toolName === "write_todos" && transitions.isEnabledBuiltInTool(toolCall.toolName)).length,
+        };
         for (const [index, requestedToolCall] of outcome.toolCalls.entries()) {
-            const requiresApproval = requestedToolCall.policy.requiresApproval;
-            const effect = requestedToolCall.policy.effect;
-            transitions.writeToolCall(context, {
-                toolCallId: requestedToolCall.toolCallId,
-                turnId,
-                toolName: requestedToolCall.toolName,
-                arguments: requestedToolCall.arguments,
-                effect,
-                requiresApproval,
-                status: requiresApproval ? "awaiting_approval" : "approved",
-                output: null,
-                error: null,
-                rejectionMessage: null,
-                deferralOrder: toolCalls.length + index,
-            });
-            events.writeEvent("tool_call_deferred", {
-                tool_call_id: requestedToolCall.toolCallId,
-                tool_name: requestedToolCall.toolName,
-                effect,
-                requires_approval: requiresApproval,
-            });
-            const nextStepType = requiresApproval
-                ? agentSessionStepTypes.awaitToolApproval
-                : toolStepTypeForEffect(effect);
-            movements.push(toolStepMovement(transitions.persistence, nextStepType, requestedToolCall.toolCallId));
-            if (!requiresApproval) {
-                continue;
+            const deferralOrder = toolCalls.length + index;
+            const toolName = requestedToolCall.toolName;
+            if (batch.interactionMode === "planning" && !(toolName === "write_todos" && transitions.isEnabledBuiltInTool(toolName))) {
+                this.rejectPlanningTurnToolCall(batch, requestedToolCall, deferralOrder);
+            }
+            else if (transitions.isEnabledBuiltInTool(toolName)) {
+                this.deferBuiltInToolCall(batch, requestedToolCall, toolName, deferralOrder);
+            }
+            else {
+                this.deferApplicationToolCall(batch, requestedToolCall, deferralOrder);
             }
-            const interrupt = {
-                interruptId: requestedToolCall.toolCallId,
-                kind: "tool_approval",
-                toolCallId: requestedToolCall.toolCallId,
-                toolName: requestedToolCall.toolName,
-                arguments: requestedToolCall.arguments,
-                createdAt: createdAt.toISOString(),
-                deadline,
-            };
-            interrupts.push(interrupt);
-            events.writeEvent("interrupt_raised", {
-                interrupt_id: interrupt.interruptId,
-                tool_call_id: interrupt.toolCallId,
-                tool_name: interrupt.toolName,
-                deadline: interrupt.deadline,
-            });
         }
-        transitions.persistence.pendingInterrupts.set(context, interrupts);
+        transitions.persistence.pendingInterrupts.set(context, batch.interrupts);
         transitions.recordUsage(context, outcome.usage, events);
-        transitions.writeAgentState(context, { ...state, status: "running_tools" });
-        movements.push(StepMovement.of(new StepRef(agentSessionStepTypes.resumeTurn), outcome.toolCalls.length));
-        return goToMany(...movements);
+        transitions.writeAgentState(context, { ...stateWithMessages, status: "running_tools" });
+        batch.movements.push(StepMovement.of(new StepRef(agentSessionStepTypes.resumeTurn), outcome.toolCalls.length));
+        return goToMany(...batch.movements);
+    }
+    /** A planning turn hides executable tools; a call to one never runs. */
+    rejectPlanningTurnToolCall(batch, requestedToolCall, deferralOrder) {
+        const isBuiltInTool = this.transitions.isEnabledBuiltInTool(requestedToolCall.toolName);
+        const record = createToolCallRecord(batch, requestedToolCall, isBuiltInTool ? "read" : requestedToolCall.policy.effect, isBuiltInTool ? false : requestedToolCall.policy.requiresApproval, deferralOrder);
+        writeToolCallDeferred(batch.events, record);
+        this.transitions.finishToolCall(batch.context, { ...record, status: "rejected", rejectionMessage: planningTurnToolRejection }, batch.events);
+    }
+    deferApplicationToolCall(batch, requestedToolCall, deferralOrder) {
+        const transitions = this.transitions;
+        const requiresApproval = requestedToolCall.policy.requiresApproval;
+        const effect = requestedToolCall.policy.effect;
+        const record = createToolCallRecord(batch, requestedToolCall, effect, requiresApproval, deferralOrder);
+        transitions.writeToolCall(batch.context, {
+            ...record,
+            status: requiresApproval ? "awaiting_approval" : "approved",
+        });
+        writeToolCallDeferred(batch.events, record);
+        const nextStepType = requiresApproval
+            ? agentSessionStepTypes.awaitToolApproval
+            : toolStepTypeForEffect(effect);
+        batch.movements.push(toolStepMovement(transitions.persistence, nextStepType, requestedToolCall.toolCallId));
+        if (!requiresApproval) {
+            return;
+        }
+        const interrupt = {
+            interruptId: requestedToolCall.toolCallId,
+            kind: "tool_approval",
+            toolCallId: requestedToolCall.toolCallId,
+            toolName: requestedToolCall.toolName,
+            arguments: requestedToolCall.arguments,
+            createdAt: batch.createdAt,
+            deadline: batch.interruptDeadline,
+            question: null,
+            choices: [],
+            allowsFreeText: true,
+        };
+        batch.interrupts.push(interrupt);
+        transitions.writeInterruptRaised(batch.events, interrupt);
+    }
+    /** Records a built-in call with its fixed policy and routes it to its wait Step; invalid arguments fail at once. */
+    deferBuiltInToolCall(batch, requestedToolCall, builtInTool, deferralOrder) {
+        const transitions = this.transitions;
+        const persistence = transitions.persistence;
+        const record = createToolCallRecord(batch, requestedToolCall, "read", false, deferralOrder);
+        writeToolCallDeferred(batch.events, record);
+        switch (builtInTool) {
+            case "ask_user": {
+                const validation = validateAskUserArguments(record.arguments);
+                if (!validation.isValid) {
+                    this.failBuiltInToolCall(batch, record, validation.error);
+                    return;
+                }
+                transitions.writeToolCall(batch.context, { ...record, status: "awaiting_answer" });
+                const interrupt = {
+                    interruptId: record.toolCallId,
+                    kind: "question",
+                    toolCallId: record.toolCallId,
+                    toolName: record.toolName,
+                    arguments: record.arguments,
+                    createdAt: batch.createdAt,
+                    deadline: batch.interruptDeadline,
+                    question: validation.arguments.question,
+                    choices: validation.arguments.choices,
+                    allowsFreeText: validation.arguments.allowsFreeText,
+                };
+                batch.interrupts.push(interrupt);
+                transitions.writeInterruptRaised(batch.events, interrupt);
+                batch.movements.push(questionAnswerMovement(persistence, { ...record, status: "awaiting_answer" }));
+                return;
+            }
+            case "durable_wait": {
+                const maxDurableWaitSeconds = Math.floor(transitions.config.maxDurableWaitMs / 1_000);
+                const validation = validateDurableWaitArguments(record.arguments, maxDurableWaitSeconds);
+                if (!validation.isValid) {
+                    this.failBuiltInToolCall(batch, record, validation.error);
+                    return;
+                }
+                const waitUntil = new Date(Date.parse(batch.createdAt) + validation.arguments.durationSeconds * 1_000).toISOString();
+                transitions.writeToolCall(batch.context, { ...record, status: "waiting_for_timer", waitUntil });
+                batch.events.writeEvent("timer_started", {
+                    tool_call_id: record.toolCallId,
+                    wait_until: waitUntil,
+                    reason: validation.arguments.reason,
+                });
+                batch.movements.push(toolStepMovement(persistence, agentSessionStepTypes.awaitTimer, record.toolCallId));
+                return;
+            }
+            case "write_todos":
+                this.writeTodos(batch, record);
+                return;
+        }
+    }
+    /** Replaces the plan and records the call final, in this commit; no tool Step runs. */
+    writeTodos(batch, record) {
+        const transitions = this.transitions;
+        if (batch.writeTodosCallCount > 1) {
+            this.failBuiltInToolCall(batch, record, writeTodosCalledMoreThanOnce);
+            return;
+        }
+        const validation = validateWriteTodosArguments(record.arguments);
+        if (!validation.isValid) {
+            this.failBuiltInToolCall(batch, record, validation.error);
+            return;
+        }
+        const tasks = validation.arguments;
+        const previous = transitions.readOptionalAgentPlan(batch.context);
+        const plan = {
+            revision: (previous?.revision ?? 0) + 1,
+            status: planStatusAfterWrite(tasks, batch.interactionMode),
+            tasks,
+            updatedAt: batch.createdAt,
+        };
+        transitions.persistence.agentPlan.set(batch.context, plan);
+        writePlanUpdated(batch.events, plan);
+        const output = plan.status === "cleared" ? buildPlanClearedOutput(plan.revision) : buildPlanUpdatedOutput(plan.revision, tasks.length);
+        transitions.finishToolCall(batch.context, { ...record, status: "succeeded", output }, batch.events);
+    }
+    failBuiltInToolCall(batch, record, error) {
+        this.transitions.finishToolCall(batch.context, { ...record, status: "failed", error }, batch.events);
+    }
+}
+/** Summarizes the messages through a sequence for the model input, then moves back to `RunModel`. */
+export class CompactContextStep {
+    transitions;
+    inputCodec = turnFailureRouteInputCodec;
+    constructor(transitions) {
+        this.transitions = transitions;
+    }
+    getStepType() {
+        return agentSessionStepTypes.compactContext;
+    }
+    getStepOptions() {
+        return {
+            ...syncDurability,
+            ...modelCallStepOptions,
+            executeLoadAttributeMaps: [this.transitions.persistence.agentMessages],
+        };
+    }
+    async execute(context, input) {
+        const transitions = this.transitions;
+        if (input === undefined) {
+            throw new TypeError("CompactContext needs a CompactContextInput");
+        }
+        const state = transitions.readAgentState(context);
+        const turnId = state.activeTurnId;
+        if (turnId === null) {
+            throw new Error(`the agent session ${context.flowId} has no active turn`);
+        }
+        const previousSummary = transitions.readContextSummary(context);
+        const firstSequence = previousSummary === null ? 1 : previousSummary.lastSequence + 1;
+        const throughSequence = input.throughSequence;
+        if (throughSequence < firstSequence || throughSequence >= state.nextMessageSequence) {
+            throw new Error(`CompactContext cannot summarize through message ${throughSequence}`);
+        }
+        const runner = transitions.runner;
+        if (!isContextCompactionRunner(runner)) {
+            throw new TypeError("CompactContext needs a runner that implements the compaction methods");
+        }
+        const events = transitions.createEventWriter(context, turnId);
+        try {
+            events.writeEvent("compaction_started", { through_sequence: throughSequence });
+            const result = await this.summarize(context, runner, turnId, previousSummary, throughSequence, events);
+            const summary = {
+                generation: previousSummary === null ? 1 : previousSummary.generation + 1,
+                firstSequence: 1,
+                lastSequence: throughSequence,
+                text: result.text,
+                createdAt: new Date().toISOString(),
+            };
+            transitions.persistence.contextSummary.set(context, summary);
+            const index = transitions.readMessageIndex(context);
+            if (index !== null) {
+                const retainedIndex = transitions.applyMessageRetention(context, index, state.nextMessageSequence, summary);
+                if (retainedIndex !== index) {
+                    transitions.persistence.agentMessageIndex.set(context, retainedIndex);
+                }
+            }
+            transitions.recordUsage(context, result.usage, events);
+            transitions.writeAgentState(context, { ...state, status: "running_model" });
+            events.writeEvent("compaction_finished", { generation: summary.generation, through_sequence: throughSequence });
+            return transitions.goToRunModel(context, summary);
+        }
+        finally {
+            events.close();
+        }
+    }
+    async summarize(context, runner, turnId, previousSummary, throughSequence, events) {
+        const transitions = this.transitions;
+        const firstSequence = transitions.readModelInputFirstSequence(context, previousSummary);
+        const messages = transitions.readMessages(context, firstSequence, throughSequence + 1);
+        const policy = transitions.config.compaction;
+        return transitions.tracer.traceContextSummary(context, this.getStepType(), turnId, throughSequence, messages, async (summarySpan) => {
+            const result = await transitions.runWithHeartbeats(context, () => runner.summarizeContext({
+                flowId: context.flowId,
+                turnId,
+                attempt: context.attempt,
+                stepExecutionId: context.stepExecutionId,
+                previousSummary,
+                messages,
+                throughSequence,
+                events,
+                cancellationSignal: context.cancellationSignal,
+                deadline: context.deadline,
+                ...(policy === undefined ? {} : { inputTokenBudget: policy.contextWindowTokens }),
+                sessionSettings: transitions.readTurnSessionSettings(context),
+                heartbeat: () => transitions.recordHeartbeat(context),
+            }));
+            if (typeof result?.text !== "string" || result.text.trim() === "" || typeof result.usage !== "object") {
+                throw new TypeError("summarizeContext must return summary text and usage");
+            }
+            summarySpan.recordResult(result);
+            return result;
+        });
     }
 }
 /** Waits for one tool call's approval or its deadline, then runs or rejects the call. */
@@ -240,7 +549,10 @@ export class AwaitToolApprovalStep {
     }
     waitFor(context, toolCallId) {
         const transitions = this.transitions;
-        const conditions = [transitions.persistence.interruptResolutions.forOne(toolCallId)];
+        const conditions = [
+            transitions.persistence.toolCallCancellations.forOne(toolCallId),
+            transitions.persistence.interruptResolutions.forOne(toolCallId),
+        ];
         // A resolved interrupt left PendingInterrupts, so its deadline no longer applies.
         const interrupt = transitions
             .readPendingInterrupts(context)
@@ -259,6 +571,9 @@ export class AwaitToolApprovalStep {
         if (toolCall.status !== "awaiting_approval") {
             return deadEnd();
         }
+        if (context.channelResults(persistence.toolCallCancellations, toolCallId).length > 0) {
+            return cancelWaitingToolCall(this.transitions, context, toolCall, { interruptId: toolCallId, kind: "tool_approval" }, toolStepMovement(persistence, agentSessionStepTypes.awaitToolApproval, toolCallId));
+        }
         const [resolution] = context.channelResults(persistence.interruptResolutions, toolCallId);
         if (resolution === undefined) {
             if (!context.hasTimerFired()) {
@@ -271,29 +586,49 @@ export class AwaitToolApprovalStep {
                 return goToMany(toolStepMovement(persistence, agentSessionStepTypes.awaitToolApproval, toolCallId));
             }
             persistence.pendingInterrupts.set(context, pendingInterrupts.filter((interrupt) => interrupt.interruptId !== toolCallId));
-            return this.rejectToolCall(context, toolCall, approvalDeadlinePassed);
-        }
-        if (!resolution.approved) {
-            return this.rejectToolCall(context, toolCall, resolution.rejectionMessage);
+            return this.applyResolution(context, toolCall, false, approvalDeadlinePassed, true);
         }
-        transitions.writeToolCall(context, { ...toolCall, status: "approved" });
-        this.writeInterruptResolved(context, toolCall, true, null);
-        return goToMany(toolStepMovement(persistence, toolStepTypeForEffect(toolCall.effect), toolCallId));
+        return this.applyResolution(context, toolCall, resolution.approved, resolution.rejectionMessage, false);
+    }
+    applyResolution(context, toolCall, isApproved, rejectionMessage, isDeadlinePassed) {
+        return this.transitions.tracer.traceInterruptActivation(context, this.getStepType(), toolCall.turnId, toolCall.toolCallId, isApproved, isDeadlinePassed, (activation) => {
+            if (!isApproved) {
+                return this.rejectToolCall(context, toolCall, rejectionMessage);
+            }
+            // The approval starts a new activation, so the tool's spans join its root, not the RunModel one.
+            const { traceContext: _deferredTraceContext, ...deferredToolCall } = toolCall;
+            this.transitions.writeToolCall(context, {
+                ...deferredToolCall,
+                status: "approved",
+                cancellationReason: null,
+                ...(activation.traceparent === null ? {} : { traceContext: activation.traceparent }),
+            });
+            this.transitions.writeInterruptResolved(context, toolCall.turnId, {
+                interruptId: toolCall.toolCallId,
+                kind: "tool_approval",
+                isApproved: true,
+                isAnswered: false,
+                rejectionMessage: null,
+            });
+            return goToMany(toolStepMovement(this.transitions.persistence, toolStepTypeForEffect(toolCall.effect), toolCall.toolCallId));
+        });
     }
     rejectToolCall(context, toolCall, rejectionMessage) {
-        this.transitions.writeToolCall(context, { ...toolCall, status: "rejected", rejectionMessage });
-        this.writeInterruptResolved(context, toolCall, false, rejectionMessage);
-        this.transitions.writeEvents(context, toolCall.turnId, (events) => events.writeToolCallFinished(toolCall.toolCallId, toolCall.toolName, "rejected"));
-        this.transitions.publishToolCallResult(context, toolCall.toolCallId);
+        this.transitions.writeInterruptResolved(context, toolCall.turnId, {
+            interruptId: toolCall.toolCallId,
+            kind: "tool_approval",
+            isApproved: false,
+            isAnswered: false,
+            rejectionMessage,
+        });
+        this.transitions.finishToolCall(context, {
+            ...toolCall,
+            status: "rejected",
+            rejectionMessage,
+            cancellationReason: null,
+        });
         return deadEnd();
     }
-    writeInterruptResolved(context, toolCall, isApproved, rejectionMessage) {
-        this.transitions.writeEvents(context, toolCall.turnId, (events) => events.writeEvent("interrupt_resolved", {
-            interrupt_id: toolCall.toolCallId,
-            approved: isApproved,
-            rejection_message: rejectionMessage,
-        }));
-    }
 }
 /** Runs one tool call; one class serves `CallTool` and `CallSingleAttemptTool`. */
 export class ToolCallStep {
@@ -319,49 +654,119 @@ export class ToolCallStep {
         if (toolCall.status !== "approved" || toolStepTypeForEffect(toolCall.effect) !== this.stepType) {
             throw new Error(`tool call ${toolCallId} cannot run in ${this.stepType}`);
         }
+        // Retries reuse the first attempt's state, so a call that started is never abandoned.
+        const reason = transitions.readTurnControlReason(context, toolCall.turnId);
+        if (reason !== null) {
+            transitions.finishToolCall(context, cancelledToolCall(toolCall, reason));
+            return deadEnd();
+        }
         const events = transitions.createEventWriter(context, toolCall.turnId);
         try {
-            events.writeToolCallStarted(toolCall.toolCallId, toolCall.toolName);
-            // Dex re-delivers an attempt whose Worker vanished before any output, so emit output first.
-            await transitions.recordHeartbeat(context);
-            const execution = {
-                flowId: context.flowId,
-                toolCall,
-                idempotencyKey: `${context.flowId}/${toolCall.turnId}/${toolCall.toolCallId}`,
-                attempt: context.attempt,
-                events,
-                cancellationSignal: context.cancellationSignal,
-                deadline: context.deadline,
-                heartbeat: () => transitions.recordHeartbeat(context),
-            };
-            let finishedToolCall;
-            try {
-                const result = await transitions.runWithHeartbeats(context, () => transitions.runner.executeDeferredToolCall(execution));
-                if (typeof result?.output !== "string") {
-                    throw new TypeError(`executeDeferredToolCall returned no output for ${toolCallId}`);
+            return await transitions.tracer.traceToolCall(context, this.stepType, toolCall, async (toolCallSpan) => {
+                events.writeToolCallStarted(toolCall.toolCallId, toolCall.toolName);
+                const heartbeats = new ToolStepHeartbeats(context);
+                // Output first: Dex returns an attempt as not run when its stream half-closes before any output.
+                await heartbeats.record();
+                const execution = {
+                    flowId: context.flowId,
+                    toolCall: toRunnerToolCall(toolCall),
+                    idempotencyKey: `${context.flowId}/${toolCall.turnId}/${toolCall.toolCallId}`,
+                    attempt: context.attempt,
+                    events,
+                    cancellationSignal: context.cancellationSignal,
+                    deadline: context.deadline,
+                    inputAnswers: toolCall.inputAnswers,
+                    supportsToolTasks: transitions.runner.pollToolTask !== undefined,
+                    heartbeat: () => heartbeats.record(),
+                    ...(heartbeats.previousCheckpoint === undefined ? {} : { heartbeatCheckpoint: heartbeats.previousCheckpoint }),
+                    saveHeartbeatCheckpoint: (checkpoint) => heartbeats.saveCheckpoint(checkpoint),
+                };
+                let outcome;
+                try {
+                    outcome = await transitions.runWithHeartbeats(context, () => transitions.runner.executeDeferredToolCall(execution), () => heartbeats.record());
                 }
-                finishedToolCall = { ...toolCall, status: "succeeded", output: result.output };
-            }
-            catch (error) {
-                if (!(error instanceof ToolExecutionError)) {
-                    throw error;
+                catch (error) {
+                    if (!(error instanceof ToolExecutionError)) {
+                        throw error;
+                    }
+                    const failed = { ...toolCall, status: "failed", error: error.message };
+                    toolCallSpan.recordFinished(failed);
+                    transitions.finishToolCall(context, failed, events);
+                    return deadEnd();
                 }
-                finishedToolCall = { ...toolCall, status: "failed", error: error.message };
-            }
-            transitions.writeToolCall(context, finishedToolCall);
-            events.writeToolCallFinished(toolCall.toolCallId, toolCall.toolName, finishedToolCall.status);
-            transitions.publishToolCallResult(context, toolCallId);
-            return deadEnd();
+                if (isToolInputRequested(outcome)) {
+                    return this.requestToolInput(context, toolCall, outcome, events, toolCallSpan);
+                }
+                if (isToolTaskStarted(outcome)) {
+                    return this.startToolTask(context, toolCall, outcome, events, toolCallSpan);
+                }
+                if (typeof outcome?.output !== "string") {
+                    throw new TypeError(`executeDeferredToolCall returned no output for ${toolCallId}`);
+                }
+                const succeeded = { ...toolCall, status: "succeeded", output: outcome.output };
+                toolCallSpan.recordFinished(succeeded);
+                transitions.finishToolCall(context, succeeded, events);
+                return deadEnd();
+            });
         }
         finally {
             events.close();
         }
     }
+    /** Records `awaiting_answer` with the tool's question; `AwaitQuestionAnswer` raises it under the lock. */
+    requestToolInput(context, toolCall, request, events, toolCallSpan) {
+        const transitions = this.transitions;
+        const waiting = recordToolInputRequest(toolCall, request);
+        toolCallSpan.recordFinished(waiting);
+        if (isFinalToolCallStatus(waiting.status)) {
+            transitions.finishToolCall(context, waiting, events);
+            return deadEnd();
+        }
+        // This Step runs unlocked, so it leaves PendingInterrupts to AwaitQuestionAnswer.
+        transitions.writeToolCall(context, waiting);
+        return goToMany(questionAnswerMovement(transitions.persistence, waiting));
+    }
+    /** Records `waiting_for_task` and moves to `PollToolTask`, or records a task it cannot poll by effect. */
+    startToolTask(context, toolCall, started, events, toolCallSpan) {
+        const transitions = this.transitions;
+        const pollIntervalSeconds = toolTaskPollIntervalSeconds(started.pollIntervalSeconds);
+        const defect = transitions.runner.pollToolTask === undefined
+            ? missingToolTaskPoller
+            : typeof started.taskId !== "string" || isBlankText(started.taskId)
+                ? blankToolTaskId
+                : pollIntervalSeconds === null
+                    ? invalidToolTaskPollInterval
+                    : undefined;
+        if (defect !== undefined || pollIntervalSeconds === null) {
+            const finished = recordToolTaskDefect(toolCall, defect ?? invalidToolTaskPollInterval);
+            toolCallSpan.recordFinished(finished);
+            transitions.finishToolCall(context, finished, events);
+            return deadEnd();
+        }
+        // The tool consumed any continuation of its own questions when it ran again.
+        const waiting = {
+            ...toolCall,
+            status: "waiting_for_task",
+            taskId: started.taskId,
+            taskPollIntervalSeconds: pollIntervalSeconds,
+            inputContinuation: null,
+            ...noPendingToolQuestion,
+        };
+        toolCallSpan.recordFinished(waiting);
+        transitions.writeToolCall(context, waiting);
+        events.writeEvent("tool_task_started", {
+            tool_call_id: waiting.toolCallId,
+            tool_name: waiting.toolName,
+            task_id: started.taskId,
+        });
+        return goToMany(toolTaskPollMovement(transitions.persistence, waiting));
+    }
 }
 /**
  * Failure route of a tool Step; it receives the failed Step's input, the tool call ID.
  * `RecordToolFailure` records `failed` for a `read` call and `outcome_unknown` for a write;
- * `RecordToolOutcomeUnknown` always records `outcome_unknown`.
+ * `RecordToolOutcomeUnknown` always records `outcome_unknown`. Either records `failed` with
+ * {@link toolCallNotRunErrorPrefix} when the tool certainly never ran.
  */
 export class ToolCallFailureRecordingStep {
     transitions;
@@ -386,13 +791,34 @@ export class ToolCallFailureRecordingStep {
             return deadEnd();
         }
         const status = this.isReadFailureRecorded && toolCall.effect === "read" ? "failed" : "outcome_unknown";
-        transitions.writeToolCall(context, { ...toolCall, status, error: readRecoveryDetail(context) });
-        transitions.writeEvents(context, toolCall.turnId, (events) => events.writeToolCallFinished(toolCall.toolCallId, toolCall.toolName, status));
-        transitions.publishToolCallResult(context, toolCallId);
+        transitions.finishToolCall(context, recoveredToolCall(toolCall, context.recoveryError, status));
         return deadEnd();
     }
 }
-/** Waits until every tool call of the batch has a final record, then makes the next model call. */
+/** Returns the final record that a tool Step's failure route writes. */
+export function recoveredToolCall(toolCall, recoveryError, status) {
+    // An abandoned task keeps the text CancelToolTask records, whatever made its attempts fail.
+    const error = isAbandonedToolTask(toolCall) && (toolCall.cancellationReason ?? null) !== null
+        ? toolTaskAbandonedError
+        : recoveryErrorDetail(recoveryError);
+    if (isToolCallNotRun(toolCall, recoveryError)) {
+        return { ...toolCall, status: "failed", error: `${toolCallNotRunErrorPrefix}: ${error}` };
+    }
+    return { ...toolCall, status, error };
+}
+/** Returns whether the failed Step certainly never ran the call's tool. */
+function isToolCallNotRun(toolCall, recoveryError) {
+    // Polls and cancellations follow a tool that already ran, as does an answered question's call.
+    return (recoveryError?.attemptProgress === StepAttemptProgress.NOT_STARTED &&
+        toolCall.status === "approved" &&
+        toolCall.inputAnswers.length === 0);
+}
+/**
+ * Waits until every tool call of the batch has a final record, then makes the next model call.
+ *
+ * A steer wakes it early: it cancels the turn's pending interrupts and Timers, and waits again. After a steer or
+ * `cancel_turn`, once every result is in, it moves to `ApplyTurnControl` instead of `RunModel`.
+ */
 export class ResumeTurnStep {
     transitions;
     inputCodec = expectedResultCountCodec;
@@ -403,76 +829,201 @@ export class ResumeTurnStep {
         return agentSessionStepTypes.resumeTurn;
     }
     getStepOptions() {
-        return { ...syncDurability, executeLoadAttributeMaps: [this.transitions.persistence.agentToolCalls] };
+        const persistence = this.transitions.persistence;
+        // A control wake rewrites PendingInterrupts, which the interrupt RPCs also write.
+        return {
+            ...syncDurability,
+            executeLoadAttributeMaps: [persistence.agentToolCalls],
+            executeLockAttributes: [persistence.pendingInterrupts.lock()],
+        };
     }
     waitFor(_context, expectedResultCount) {
-        return Wait.until(this.transitions.persistence.toolCallResults.forN(expectedResultCount));
+        const persistence = this.transitions.persistence;
+        return Wait.anyOf(persistence.toolCallResults.forN(expectedResultCount), persistence.turnControlRequests.range(1, allPendingMessages));
     }
-    execute(context) {
+    execute(context, expectedResultCount) {
         const transitions = this.transitions;
         const state = transitions.readAgentState(context);
-        const unfinishedCount = transitions
-            .readTurnToolCalls(context, state.activeTurnId)
-            .filter((toolCall) => !isFinalToolCallStatus(toolCall.status)).length;
+        const turnId = state.activeTurnId;
+        const toolCalls = transitions.readTurnToolCalls(context, turnId);
+        const reason = transitions.readTurnControlReason(context, turnId);
+        if (context.channelResults(transitions.persistence.turnControlRequests).length > 0) {
+            // FinishTurnCancellation, not this wake, ends the waits of a cancelled turn.
+            if (reason === "steered" && turnId !== null) {
+                this.wakeWaitingToolCalls(context, turnId, toolCalls, reason);
+            }
+            // The results did not all arrive, so wait again for the same count.
+            return goTo(new StepRef(agentSessionStepTypes.resumeTurn), expectedResultCount);
+        }
+        const unfinishedCount = toolCalls.filter((toolCall) => !isFinalToolCallStatus(toolCall.status)).length;
         if (unfinishedCount > 0) {
             // A consumed result from an earlier turn must not resume this one early.
             return goTo(new StepRef(agentSessionStepTypes.resumeTurn), unfinishedCount);
         }
+        if (reason !== null) {
+            return transitions.goToApplyTurnControl(context);
+        }
         transitions.writeAgentState(context, { ...state, status: "running_model" });
-        return goTo(new StepRef(agentSessionStepTypes.runModel), undefined);
+        return transitions.goToRunModel(context);
+    }
+    /** Cancels the turn's pending interrupts and wakes each Step waiting for a person or a Timer. */
+    wakeWaitingToolCalls(context, turnId, toolCalls, reason) {
+        const transitions = this.transitions;
+        const persistence = transitions.persistence;
+        const interrupts = transitions.readPendingInterrupts(context);
+        const cancelledInterruptIds = new Set();
+        for (const toolCall of toolCalls) {
+            if (!isCancellableByTurnControl(toolCall)) {
+                continue;
+            }
+            if (toolCall.status === "waiting_for_timer") {
+                // A later control wake finds the first message still pending and adds none.
+                if (context.channelSize(persistence.toolCallCancellations, toolCall.toolCallId) === 0) {
+                    persistence.toolCallCancellations.publish(context, toolCall.toolCallId, { reason });
+                }
+                continue;
+            }
+            const isApproval = toolCall.status === "awaiting_approval";
+            const interruptId = isApproval ? toolCall.toolCallId : questionInterruptId(toolCall);
+            const kind = isApproval ? "tool_approval" : "question";
+            // An answered interrupt is gone, so its answer wins; an unraised question checks flags.
+            if (interrupts.some((interrupt) => interrupt.interruptId === interruptId && interrupt.toolCallId === toolCall.toolCallId)) {
+                cancelledInterruptIds.add(interruptId);
+                transitions.writeInterruptCancelled(context, turnId, interruptId, kind, reason);
+                persistence.toolCallCancellations.publish(context, toolCall.toolCallId, { reason });
+            }
+        }
+        if (cancelledInterruptIds.size > 0) {
+            persistence.pendingInterrupts.set(context, interrupts.filter((interrupt) => !cancelledInterruptIds.has(interrupt.interruptId)));
+        }
     }
 }
-export class RecordTurnFailureStep {
+/** Ends a steered or cancelled turn, then starts a turn with the steered messages. */
+export class ApplyTurnControlStep {
     transitions;
     inputCodec = voidCodec;
     constructor(transitions) {
         this.transitions = transitions;
     }
+    getStepType() {
+        return agentSessionStepTypes.applyTurnControl;
+    }
+    getStepOptions() {
+        // Each movement into ApplyTurnControl adds the archive chunks of the model input.
+        // The lock keeps a turn from starting while cancel_turn decides about the last one.
+        return {
+            ...messageStepOptions(this.transitions.persistence, this.getStepType(), staticMessageChunkLoads(this.transitions)),
+            executeLockAttributes: [this.transitions.persistence.turnCancellationRequest.lock()],
+        };
+    }
+    waitFor() {
+        const persistence = this.transitions.persistence;
+        // Both conditions are non-blocking: the wait consumes every steered message and stale wake.
+        return Wait.allOf(persistence.steeredUserMessages.atMost(allPendingMessages), persistence.turnControlRequests.atMost(allPendingMessages));
+    }
+    execute(context) {
+        const transitions = this.transitions;
+        let state = transitions.readAgentState(context);
+        const steeredMessages = context.channelResults(transitions.persistence.steeredUserMessages);
+        if (state.activeTurnId !== null) {
+            state = transitions.endControlledTurn(context, state, state.activeTurnId, steeredMessages.length);
+        }
+        if (steeredMessages.length === 0) {
+            return transitions.goToAwaitUserMessage();
+        }
+        // Any steered message with planMode, or a draft plan, makes it a planning turn.
+        return transitions.beginTurn(context, state, steeredMessages, this.getStepType(), transitions.decideInteractionMode(context, steeredMessages));
+    }
+}
+/** Ends a failed turn; it is the failure route of `RunModel` and `CompactContext`, so it takes either's input. */
+export class RecordTurnFailureStep {
+    transitions;
+    inputCodec = turnFailureRouteInputCodec;
+    constructor(transitions) {
+        this.transitions = transitions;
+    }
     getStepType() {
         return agentSessionStepTypes.recordTurnFailure;
     }
     getStepOptions() {
+        const persistence = this.transitions.persistence;
+        const hasUnfinishedTurnMessages = this.transitions.runner.buildUnfinishedTurnMessages !== undefined;
         return {
             ...syncDurability,
             executeRetry: recoveryRetry,
-            executeLoadAttributeMaps: [this.transitions.persistence.agentToolCalls],
+            // A failure route has only static options, so an incremental runner loads every retained chunk.
+            executeLoadAttributeMaps: hasUnfinishedTurnMessages
+                ? [persistence.agentToolCalls, persistence.agentMessages, persistence.agentMessageChunks]
+                : [persistence.agentToolCalls, persistence.agentMessages],
         };
     }
     execute(context) {
         const transitions = this.transitions;
-        const persistence = transitions.persistence;
-        let state = transitions.readAgentState(context);
-        const turnError = readRecoveryDetail(context);
+        const state = transitions.readAgentState(context);
         const toolCalls = transitions.readTurnToolCalls(context, state.activeTurnId);
         const finalToolCalls = toolCalls.filter((toolCall) => isFinalToolCallStatus(toolCall.status));
-        // The records are deleted below; the note keeps the next model from repeating writes.
-        if (state.activeTurnId !== null && finalToolCalls.length > 0) {
-            const note = transitions.runner.buildUserMessage(buildTurnFailureNote(finalToolCalls));
-            if (note.role !== "user") {
-                throw new TypeError("buildUserMessage must return a message with role user");
-            }
-            state = transitions.appendMessages(context, state, state.activeTurnId, [note]);
-        }
-        for (const toolCall of toolCalls) {
-            persistence.agentToolCalls.delete(context, toolCall.toolCallId);
+        const unfinishedTurnMessages = state.activeTurnId === null
+            ? null
+            : transitions.buildUnfinishedTurnMessages(context, state, state.activeTurnId, finalToolCalls);
+        return recordFailedTurn(transitions, context, state, toolCalls, unfinishedTurnMessages ?? [], readRecoveryDetail(context));
+    }
+}
+/**
+ * Ends the active turn as failed in the current commit: appends the unfinished-turn messages, then the
+ * turn-failure note when the turn has final records, and clears the turn.
+ */
+function recordFailedTurn(transitions, context, initialState, toolCalls, unfinishedTurnMessages, turnError) {
+    const persistence = transitions.persistence;
+    const turnId = initialState.activeTurnId;
+    let state = initialState;
+    const finalToolCalls = toolCalls.filter((toolCall) => isFinalToolCallStatus(toolCall.status));
+    if (turnId !== null) {
+        state = transitions.appendMessages(context, state, turnId, unfinishedTurnMessages);
+    }
+    // The records are deleted below; the note keeps the next model from repeating writes.
+    if (turnId !== null && finalToolCalls.length > 0) {
+        const note = transitions.runner.buildUserMessage(buildTurnFailureNote(finalToolCalls));
+        if (note.role !== "user") {
+            throw new TypeError("buildUserMessage must return a message with role user");
         }
-        persistence.frameworkRunState.delete(context);
-        persistence.pendingInterrupts.set(context, []);
-        transitions.writeAgentState(context, {
-            ...state,
-            status: "waiting_for_user_message",
-            turnCount: state.turnCount + 1,
-            activeTurnId: null,
-            lastTurnError: turnError,
-        });
-        transitions.writeEvents(context, state.activeTurnId, (events) => events.writeEvent("turn_failed", { error: turnError }));
-        return transitions.goToAwaitUserMessage();
+        state = transitions.appendMessages(context, state, turnId, [note]);
     }
+    for (const toolCall of toolCalls) {
+        persistence.agentToolCalls.delete(context, toolCall.toolCallId);
+    }
+    persistence.frameworkRunState.delete(context);
+    persistence.pendingInterrupts.set(context, []);
+    transitions.writeAgentState(context, {
+        ...state,
+        status: "waiting_for_user_message",
+        turnCount: state.turnCount + 1,
+        activeTurnId: null,
+        lastTurnError: turnError,
+        acceptsTurnControl: false,
+    });
+    transitions.writeEvents(context, turnId, (events) => events.writeEvent("turn_failed", { error: turnError }));
+    return transitions.goToAwaitUserMessage();
 }
+/**
+ * Chunk loads of a Step's static options, used by a retry or by a movement an earlier version scheduled: none
+ * beyond the window with compaction, else every chunk.
+ */
+function staticMessageChunkLoads(transitions) {
+    return { isWholeMap: transitions.config.compaction === undefined, instances: [] };
+}
+/** The `AgentMessages` keys that appending these messages after the state's last one will use. */
+function appendedMessageKeys(state, messages) {
+    return messages.map((_message, offset) => messageSequenceKey(state.nextMessageSequence + offset));
+}
+/** `last_turn_error` of a turn whose runner stored messages incrementally without the builder. */
+export const missingUnfinishedTurnMessageBuilder = "a runner that sets ToolCallsRequested.newMessages must implement buildUnfinishedTurnMessages";
 function validateToolCallsRequested(turnId, existingToolCalls, outcome) {
     if (typeof outcome.frameworkRunState !== "string" || outcome.frameworkRunState === "") {
         throw new TypeError(`ToolCallsRequested for ${turnId} needs a non-empty frameworkRunState`);
     }
+    if (outcome.newMessages !== undefined && !Array.isArray(outcome.newMessages)) {
+        throw new TypeError(`ToolCallsRequested.newMessages for ${turnId} must be an array`);
+    }
     if (outcome.toolCalls.length === 0) {
         throw new TypeError(`ToolCallsRequested for ${turnId} needs at least one tool call`);
     }
@@ -492,14 +1043,34 @@ function validateToolCallsRequested(turnId, existingToolCalls, outcome) {
  * Returns the full options of a tool Step type. With a tool call ID, the Step loads only that call's
  * record; a movement's options replace the Step's static options, so every option is repeated here.
  */
-function toolStepOptions(persistence, stepType, toolCallId) {
+export function toolStepOptions(persistence, stepType, toolCallId) {
     const loads = toolCallId === undefined
         ? { executeLoadAttributeMaps: [persistence.agentToolCalls] }
         : { executeLoadAttributeMapInstances: [persistence.agentToolCalls.load(toolCallId)] };
+    const waitForLoads = toolCallId === undefined
+        ? { waitForLoadAttributeMaps: [persistence.agentToolCalls] }
+        : { waitForLoadAttributeMapInstances: [persistence.agentToolCalls.load(toolCallId)] };
     switch (stepType) {
         case agentSessionStepTypes.awaitToolApproval:
             // The deadline path rewrites PendingInterrupts, which resolve_interrupt and sibling Steps also write.
             return { ...syncDurability, ...loads, executeLockAttributes: [persistence.pendingInterrupts.lock()] };
+        case agentSessionStepTypes.awaitQuestionAnswer:
+            // Raising a tool's question and the deadline path rewrite PendingInterrupts, as in AwaitToolApproval.
+            return {
+                ...syncDurability,
+                ...loads,
+                ...waitForLoads,
+                // A movement loads only its question's instance; see questionAnswerMovement.
+                ...(toolCallId === undefined
+                    ? {
+                        waitForLoadChannelMaps: [persistence.interruptResolutions],
+                        executeLoadChannelMaps: [persistence.interruptResolutions],
+                    }
+                    : {}),
+                executeLockAttributes: [persistence.pendingInterrupts.lock()],
+            };
+        case agentSessionStepTypes.awaitTimer:
+            return { ...syncDurability, ...loads, ...waitForLoads };
         case agentSessionStepTypes.callTool:
             return {
                 ...syncDurability,
@@ -514,16 +1085,184 @@ function toolStepOptions(persistence, stepType, toolCallId) {
                 executeRetry: { maximumAttempts: 1 },
                 executeFailure: ExecuteFailure.proceedTo(new StepRef(agentSessionStepTypes.recordToolOutcomeUnknown), toolStepOptions(persistence, agentSessionStepTypes.recordToolOutcomeUnknown, toolCallId)),
             };
+        case agentSessionStepTypes.pollToolTask:
+            return toolTaskPollOptions(persistence, agentSessionStepTypes.recordToolFailure, toolCallId);
         case agentSessionStepTypes.recordToolFailure:
         case agentSessionStepTypes.recordToolOutcomeUnknown:
             return { ...syncDurability, ...loads, executeRetry: recoveryRetry };
+        case agentSessionStepTypes.cancelToolTask:
+            // Retries that run out still record the call, so the cancelled turn always ends.
+            return {
+                ...syncDurability,
+                ...loads,
+                executeMethodTimeoutMs: 30_000,
+                executeRetry: { maximumAttempts: 3, totalDurationMs: 2 * minuteMs },
+                executeFailure: ExecuteFailure.proceedTo(new StepRef(agentSessionStepTypes.recordToolOutcomeUnknown), toolStepOptions(persistence, agentSessionStepTypes.recordToolOutcomeUnknown, toolCallId)),
+            };
         default:
             throw new TypeError(`${stepType} is not a tool Step type`);
     }
 }
-function toolStepMovement(persistence, stepType, toolCallId) {
+export function toolStepMovement(persistence, stepType, toolCallId) {
     return StepMovement.of(new StepRef(stepType), toolCallId, toolStepOptions(persistence, stepType, toolCallId));
 }
+/**
+ * Returns the options of `PollToolTask`. It takes no lock and never waits on a cancellation: it owns the
+ * record, and a started task runs on.
+ */
+function toolTaskPollOptions(persistence, recoveryStepType, toolCallId) {
+    const loads = toolCallId === undefined
+        ? {
+            waitForLoadAttributeMaps: [persistence.agentToolCalls],
+            executeLoadAttributeMaps: [persistence.agentToolCalls],
+        }
+        : {
+            waitForLoadAttributeMapInstances: [persistence.agentToolCalls.load(toolCallId)],
+            executeLoadAttributeMapInstances: [persistence.agentToolCalls.load(toolCallId)],
+        };
+    return {
+        ...syncDurability,
+        ...loads,
+        executeRetry: { maximumAttempts: 3 },
+        executeFailure: ExecuteFailure.proceedTo(new StepRef(recoveryStepType), toolStepOptions(persistence, recoveryStepType, toolCallId)),
+    };
+}
+/** Moves to `PollToolTask`; a poll that keeps failing leaves the task running, so the call is recorded by effect. */
+export function toolTaskPollMovement(persistence, toolCall) {
+    const recoveryStepType = toolStepTypeForEffect(toolCall.effect) === agentSessionStepTypes.callTool
+        ? agentSessionStepTypes.recordToolFailure
+        : agentSessionStepTypes.recordToolOutcomeUnknown;
+    return StepMovement.of(new StepRef(agentSessionStepTypes.pollToolTask), toolCall.toolCallId, toolTaskPollOptions(persistence, recoveryStepType, toolCall.toolCallId));
+}
+/** Returns the record of a tool's question: `awaiting_answer`, or `failed` when it is blank. */
+export function recordToolInputRequest(toolCall, request) {
+    const choices = request.choices ?? [];
+    if (typeof request.question !== "string" ||
+        isBlankText(request.question) ||
+        !choices.every((choice) => typeof choice === "string" && !isBlankText(choice))) {
+        return { ...toolCall, status: "failed", error: "the tool asked for input with a blank question or choice" };
+    }
+    return {
+        ...toolCall,
+        status: "awaiting_answer",
+        inputContinuation: request.continuation,
+        inputQuestion: request.question,
+        inputChoices: [...choices],
+        inputAllowsFreeText: (request.allowsFreeText ?? true) || choices.length === 0,
+    };
+}
+/** Returns a final record for a task that cannot be polled: `failed` for a read, else `outcome_unknown`. */
+export function recordToolTaskDefect(toolCall, error) {
+    return {
+        ...toolCall,
+        status: toolCall.effect === "read" ? "failed" : "outcome_unknown",
+        error,
+        ...noPendingToolQuestion,
+    };
+}
+/** Returns a poll interval in whole seconds from 1 to a day, or `null` when it is not a finite number. */
+export function toolTaskPollIntervalSeconds(seconds) {
+    if (typeof seconds !== "number" || !Number.isFinite(seconds)) {
+        return null;
+    }
+    // Dex Timers take whole seconds, and a zero interval would poll without a pause.
+    return Math.min(Math.max(1, Math.ceil(seconds)), maximumToolTaskPollIntervalSeconds);
+}
+function createToolCallRecord(batch, requestedToolCall, effect, requiresApproval, deferralOrder) {
+    return {
+        toolCallId: requestedToolCall.toolCallId,
+        turnId: batch.turnId,
+        toolName: requestedToolCall.toolName,
+        arguments: requestedToolCall.arguments,
+        effect,
+        requiresApproval,
+        status: "approved",
+        output: null,
+        error: null,
+        rejectionMessage: null,
+        deferralOrder,
+        ...(requestedToolCall.toolSourceReference === undefined
+            ? {}
+            : { toolSourceReference: requestedToolCall.toolSourceReference }),
+        ...(batch.traceContext === null ? {} : { traceContext: batch.traceContext }),
+        waitUntil: null,
+        inputContinuation: null,
+        inputAnswers: [],
+        ...noPendingToolQuestion,
+        cancellationReason: null,
+        taskId: null,
+        taskPollIntervalSeconds: null,
+        taskAnswerPending: false,
+    };
+}
+function writeToolCallDeferred(events, record) {
+    events.writeEvent("tool_call_deferred", {
+        tool_call_id: record.toolCallId,
+        tool_name: record.toolName,
+        effect: record.effect,
+        requires_approval: record.requiresApproval,
+    });
+}
+/** Record fields of a call without a pending tool question. */
+export const noPendingToolQuestion = {
+    inputQuestion: null,
+    inputChoices: [],
+    inputAllowsFreeText: true,
+};
+/** Moves to `AwaitQuestionAnswer`, which reads the answer count to tell an unraised question from an answer. */
+export function questionAnswerMovement(persistence, toolCall) {
+    const options = toolStepOptions(persistence, agentSessionStepTypes.awaitQuestionAnswer, toolCall.toolCallId);
+    const interruptId = questionInterruptId(toolCall);
+    const answerLoad = persistence.interruptResolutions.loadMessages(interruptId);
+    // A record keyed by the question's interrupt ID means another call already owns that ID.
+    const recordLoads = interruptId === toolCall.toolCallId
+        ? [persistence.agentToolCalls.load(toolCall.toolCallId)]
+        : [persistence.agentToolCalls.load(toolCall.toolCallId), persistence.agentToolCalls.load(interruptId)];
+    return StepMovement.of(new StepRef(agentSessionStepTypes.awaitQuestionAnswer), toolCall.toolCallId, {
+        ...options,
+        waitForLoadAttributeMapInstances: recordLoads,
+        executeLoadAttributeMapInstances: recordLoads,
+        waitForLoadChannelMapInstances: [answerLoad],
+        executeLoadChannelMapInstances: [answerLoad],
+    });
+}
+/** An `ask_user` question uses the tool call ID; a tool's `n`-th question appends `-input-<n>`. */
+export function questionInterruptId(toolCall) {
+    return toolCall.inputQuestion === null
+        ? toolCall.toolCallId
+        : `${toolCall.toolCallId}-input-${toolCall.inputAnswers.length + 1}`;
+}
+/**
+ * Records a call that `ToolCallCancellations` woke as cancelled, or waits again. Pass `interrupt` `null` for a
+ * durable wait.
+ */
+export function cancelWaitingToolCall(transitions, context, toolCall, interrupt, waitAgain) {
+    const persistence = transitions.persistence;
+    // The flags decide; a wake-up left from an earlier turn's call ID changes nothing.
+    const reason = transitions.readTurnControlReason(context, toolCall.turnId);
+    if (reason === null || !isCancellableByTurnControl(toolCall)) {
+        return goToMany(waitAgain);
+    }
+    if (interrupt !== null) {
+        const pendingInterrupts = transitions.readPendingInterrupts(context);
+        if (pendingInterrupts.some((pending) => pending.interruptId === interrupt.interruptId)) {
+            persistence.pendingInterrupts.set(context, pendingInterrupts.filter((pending) => pending.interruptId !== interrupt.interruptId));
+            transitions.writeInterruptCancelled(context, toolCall.turnId, interrupt.interruptId, interrupt.kind, reason);
+        }
+        else if (context.channelSize(persistence.interruptResolutions, interrupt.interruptId) > 0) {
+            // The answer committed first; the next wait consumes it.
+            return goToMany(waitAgain);
+        }
+    }
+    transitions.finishToolCall(context, cancelledToolCall(toolCall, reason));
+    return deadEnd();
+}
+export function isToolInputRequested(outcome) {
+    return outcome?.kind === "tool_input_requested";
+}
+function isToolTaskStarted(outcome) {
+    return outcome?.kind === "tool_task_started";
+}
 function requirePositiveResultCount(value) {
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new TypeError(`ResumeTurn input must be a positive integer: ${value}`);