@superdurable/dex-agents 0.1.0 → 0.3.0

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

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+import { ActiveStepSearchMode } from "@superdurable/dex";
+import { validateSessionSettings } from "./agent-session-settings.js";
+/**
+ * The search mode {@link startAgentSession} gives a new session.
+ *
+ * It indexes the Steps that wait, such as `AwaitToolApproval`, `AwaitQuestionAnswer`, and `AwaitUserMessage`, and
+ * leaves out Steps that run straight away, such as `RunModel`. So a session's search entry changes when it enters or
+ * leaves a wait, not on every Step.
+ *
+ * Pass it as `activeStepSearchMode` in `StartFlowOptions.configOverride` to `Client.startFlow`, in a SubFlow's
+ * `configOverride`, or to `Client.updateFlowConfig` for a running session.
+ *
+ * The value is `ActiveStepSearchMode.DEFAULT` because the Dex SDK this core supports has no `WITH_WAIT_FOR` value.
+ * It sends the unspecified mode, which the server stores on the Flow and treats as Steps with a wait.
+ *
+ * @since 0.3.0
+ */
+export const agentSessionActiveStepSearchMode = ActiveStepSearchMode.DEFAULT;
+/**
+ * Starts one agent session, searchable by the Steps it waits in.
+ *
+ * `ActiveStepTypes = "AwaitToolApproval"` then finds the session while a tool call waits for a person. Prefer this to
+ * `Client.startFlow`, which leaves the session out of that search unless `configOverride` sets
+ * {@link agentSessionActiveStepSearchMode}.
+ *
+ * Set `configOverride.activeStepSearchMode` to choose another mode. To leave a session out of the search, start it
+ * with `Client.startFlow` and no mode: the Dex SDK this core supports cannot send the disabled mode. A session started
+ * as a SubFlow inherits its parent's mode unless its `configOverride` sets one.
+ *
+ * @example
+ * ```ts
+ * await startAgentSession(client, flow, "session-42", { initialMessage: "Refund order 7" });
+ * const page = await client.searchFlows('ActiveStepTypes = "AwaitToolApproval"', 50);
+ * ```
+ *
+ * @param client - An open Client whose Registry contains `flow`.
+ * @param flow - The registered agent session Flow.
+ * @param sessionId - Flow ID of the new session.
+ * @param input - The first user message and the session's settings.
+ * @param options - Start options, such as a Request ID for an idempotent start. `configOverride` keeps every field
+ * it sets.
+ * @returns The server-assigned run ID.
+ * @throws {TypeError | RangeError} From `validateSessionSettings`, before anything is sent.
+ * @throws {FlowAlreadyStartedError} When the Flow ID is already in use.
+ * @since 0.3.0
+ */
+export async function startAgentSession(client, flow, sessionId, input = {}, options = {}) {
+    const sessionSettings = input.sessionSettings ?? null;
+    if (sessionSettings !== null) {
+        validateSessionSettings(sessionSettings);
+    }
+    return client.startFlow(flow, sessionId, { initialMessage: input.initialMessage ?? null, sessionSettings }, {
+        ...options,
+        configOverride: {
+            ...options.configOverride,
+            activeStepSearchMode: options.configOverride?.activeStepSearchMode ?? agentSessionActiveStepSearchMode,
+        },
+    });
+}
+//# sourceMappingURL=agent-session-start.js.map

package/dist/src/agent-session-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-start.js","sourceRoot":"","sources":["../../src/agent-session-start.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,oBAAoB,EAAsC,MAAM,mBAAmB,CAAC;AAI7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAGtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAyB,oBAAoB,CAAC,OAAO,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc,EACd,IAAiE,EACjE,SAAiB,EACjB,QAAyC,EAAE,EAC3C,UAA4B,EAAE;IAE9B,MAAM,eAAe,GAAG,KAAK,CAAC,eAAe,IAAI,IAAI,CAAC;IACtD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,uBAAuB,CAAC,eAAe,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC,SAAS,CACrB,IAAI,EACJ,SAAS,EACT,EAAE,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,IAAI,EAAE,eAAe,EAAE,EACjE;QACE,GAAG,OAAO;QACV,cAAc,EAAE;YACd,GAAG,OAAO,CAAC,cAAc;YACzB,oBAAoB,EAAE,OAAO,CAAC,cAAc,EAAE,oBAAoB,IAAI,gCAAgC;SACvG;KACF,CACF,CAAC;AACJ,CAAC"}

package/dist/src/agent-session-step-options.d.ts

@@ -0,0 +1,78 @@
+import { ExecuteFailure, type AttributeMapLoad, type RetryPolicy, type StepOptions } from "@superdurable/dex";
+import type { AgentSessionPersistence } from "./agent-session-persistence.js";
+export declare const minuteMs = 60000;
+/**
+ * Sets how long one `RunModel` Step may run and how often it runs again.
+ *
+ * The defaults fit one model call. A harness runner, such as the Claude Agent SDK adapter, runs a whole turn segment
+ * in one `RunModel`: several model calls and inline tool calls. Raise {@link methodTimeoutMs} when a segment needs
+ * longer than 15 minutes.
+ *
+ * Background heartbeats continue through the Step, so a long silent call stays within the heartbeat timeout and
+ * `methodTimeoutMs` is its only cap. Dex ends an attempt at `methodTimeoutMs` and aborts its `cancellationSignal`. The
+ * next attempt reruns the whole segment and pays for it again, so consider `maximumAttempts: 1` for an expensive
+ * segment. A hung call holds its Worker slot until `methodTimeoutMs`, so do not set it higher than needed.
+ *
+ * The retry budget moves with these values. It is `methodTimeoutMs` times one less than `maximumAttempts`, and at least
+ * twice `methodTimeoutMs`, so the default limit gives 30 minutes. Dex checks it only after an attempt fails, and never
+ * ends a running attempt, so it must exceed `methodTimeoutMs` for a timed-out attempt to retry at all.
+ *
+ * `CompactContext` keeps the defaults, because it makes one model call. A changed limit applies to each `RunModel`
+ * scheduled after the Worker restarts. An attempt in flight, and its retries, keep their limit.
+ *
+ * @example
+ * ```ts
+ * const flow = createClaudeAgentSessionFlow(agent, "SupportAgent", {
+ *   runModelLimit: { methodTimeoutMs: 60 * 60_000, maximumAttempts: 2 },
+ * });
+ * ```
+ *
+ * @since 0.3.0
+ */
+export interface RunModelLimit {
+    /** Longest one attempt may run, in milliseconds, a whole number of seconds. Defaults to 15 minutes. */
+    readonly methodTimeoutMs?: number;
+    /** Attempts, including the first. `1` disables retries. Defaults to 3. */
+    readonly maximumAttempts?: number;
+}
+/** A {@link RunModelLimit} with every default filled in and the retry budget it implies. */
+export interface ResolvedRunModelLimit {
+    /** Longest one attempt may run, in milliseconds. */
+    readonly methodTimeoutMs: number;
+    /** Attempts, including the first. */
+    readonly maximumAttempts: number;
+    /** The retry budget in milliseconds. */
+    readonly totalDurationMs: number;
+}
+/**
+ * Fills in a {@link RunModelLimit}.
+ * @param limit - The application's limit.
+ * @returns The limit with its defaults and retry budget.
+ * @throws {RangeError} When `methodTimeoutMs` is not a positive whole number of seconds, `maximumAttempts` is not a
+ * positive integer, or the retry budget does not fit a signed 32-bit number of seconds.
+ */
+export declare function resolveRunModelLimit(limit?: RunModelLimit): ResolvedRunModelLimit;
+export declare const modelCallStepOptions: {
+    readonly executeMethodTimeoutMs: number;
+    readonly heartbeatTimeoutMs: number;
+    readonly executeRetry: {
+        readonly maximumAttempts: 3;
+        readonly totalDurationMs: number;
+    };
+    readonly executeFailure: ExecuteFailure;
+};
+export declare const recoveryRetry: RetryPolicy;
+export declare const syncDurability: {
+    readonly waitForDurability: "sync";
+    readonly executeDurability: "sync";
+};
+/**
+ * The archive chunks a Step reads on top of the whole `AgentMessages` window: exact instances, or every chunk
+ * when the model input covers them all.
+ */
+export interface MessageChunkLoads {
+    readonly isWholeMap: boolean;
+    readonly instances: readonly AttributeMapLoad[];
+}
+/** Returns the options of a Step that reads model input and stores messages, with its chunk loads. */
+export declare function messageStepOptions(persistence: AgentSessionPersistence, stepType: string, chunkLoads: MessageChunkLoads, runModelLimit: ResolvedRunModelLimit): StepOptions;

package/dist/src/agent-session-step-options.js

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+import { ExecuteFailure, StepRef } from "@superdurable/dex";
+import { agentSessionStepTypes } from "./agent-session-step-types.js";
+export const minuteMs = 60_000;
+const maxStepDurationMs = 2_147_483_647_000;
+/**
+ * Fills in a {@link RunModelLimit}.
+ * @param limit - The application's limit.
+ * @returns The limit with its defaults and retry budget.
+ * @throws {RangeError} When `methodTimeoutMs` is not a positive whole number of seconds, `maximumAttempts` is not a
+ * positive integer, or the retry budget does not fit a signed 32-bit number of seconds.
+ */
+export function resolveRunModelLimit(limit = {}) {
+    const methodTimeoutMs = limit.methodTimeoutMs ?? modelCallStepOptions.executeMethodTimeoutMs;
+    if (!Number.isSafeInteger(methodTimeoutMs) || methodTimeoutMs < 1_000 || methodTimeoutMs % 1_000 !== 0) {
+        throw new RangeError("runModelLimit.methodTimeoutMs must be a whole number of seconds, at least one");
+    }
+    const maximumAttempts = limit.maximumAttempts ?? modelCallStepOptions.executeRetry.maximumAttempts;
+    if (!Number.isSafeInteger(maximumAttempts) || maximumAttempts < 1) {
+        throw new RangeError("runModelLimit.maximumAttempts must be positive");
+    }
+    const totalDurationMs = methodTimeoutMs * Math.max(maximumAttempts - 1, 2);
+    if (totalDurationMs > maxStepDurationMs) {
+        throw new RangeError("runModelLimit.methodTimeoutMs times maximumAttempts is too long for Dex");
+    }
+    return Object.freeze({ methodTimeoutMs, maximumAttempts, totalDurationMs });
+}
+// CompactContext makes one model call, so it shares RunModel's timeouts and retries.
+export const modelCallStepOptions = {
+    executeMethodTimeoutMs: 15 * minuteMs,
+    heartbeatTimeoutMs: 2 * minuteMs,
+    executeRetry: { maximumAttempts: 3, totalDurationMs: 30 * minuteMs },
+    executeFailure: ExecuteFailure.proceedTo(new StepRef(agentSessionStepTypes.recordTurnFailure)),
+};
+// Recovery Steps must eventually run; cap their backoff so a returning Worker picks them up quickly.
+export const recoveryRetry = { maximumIntervalMs: 5_000 };
+// An ASYNC FlowConfig could replay a committed result after a Server failover, re-running a write.
+export const syncDurability = { waitForDurability: "sync", executeDurability: "sync" };
+/** Returns the options of a Step that reads model input and stores messages, with its chunk loads. */
+export function messageStepOptions(persistence, stepType, chunkLoads, runModelLimit) {
+    const loads = {
+        executeLoadAttributeMaps: chunkLoads.isWholeMap
+            ? [persistence.agentMessages, persistence.agentToolCalls, persistence.agentMessageChunks]
+            : [persistence.agentMessages, persistence.agentToolCalls],
+        ...(chunkLoads.instances.length === 0 ? {} : { executeLoadAttributeMapInstances: chunkLoads.instances }),
+    };
+    switch (stepType) {
+        case agentSessionStepTypes.runModel:
+            return {
+                ...syncDurability,
+                ...modelCallStepOptions,
+                executeMethodTimeoutMs: runModelLimit.methodTimeoutMs,
+                executeRetry: {
+                    maximumAttempts: runModelLimit.maximumAttempts,
+                    totalDurationMs: runModelLimit.totalDurationMs,
+                },
+                ...loads,
+            };
+        case agentSessionStepTypes.applyTurnControl:
+            return { ...syncDurability, executeRetry: recoveryRetry, ...loads };
+        default:
+            throw new TypeError(`Step type ${stepType} does not read the model input`);
+    }
+}
+//# sourceMappingURL=agent-session-step-options.js.map

package/dist/src/agent-session-step-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-step-options.js","sourceRoot":"","sources":["../../src/agent-session-step-options.ts"],"names":[],"mappings":"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"}

package/dist/src/agent-session-step-types.d.ts

@@ -0,0 +1,20 @@
+/** Step types of every agent session Flow, shared with the Python core. */
+export declare const agentSessionStepTypes: {
+    readonly startAgentSession: "StartAgentSession";
+    readonly awaitUserMessage: "AwaitUserMessage";
+    readonly runModel: "RunModel";
+    readonly compactContext: "CompactContext";
+    readonly awaitToolApproval: "AwaitToolApproval";
+    readonly awaitQuestionAnswer: "AwaitQuestionAnswer";
+    readonly awaitTimer: "AwaitTimer";
+    readonly callTool: "CallTool";
+    readonly callSingleAttemptTool: "CallSingleAttemptTool";
+    readonly pollToolTask: "PollToolTask";
+    readonly recordToolFailure: "RecordToolFailure";
+    readonly recordToolOutcomeUnknown: "RecordToolOutcomeUnknown";
+    readonly resumeTurn: "ResumeTurn";
+    readonly applyTurnControl: "ApplyTurnControl";
+    readonly recordTurnFailure: "RecordTurnFailure";
+    readonly finishTurnCancellation: "FinishTurnCancellation";
+    readonly cancelToolTask: "CancelToolTask";
+};

package/dist/src/agent-session-step-types.js

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+/** Step types of every agent session Flow, shared with the Python core. */
+export const agentSessionStepTypes = {
+    startAgentSession: "StartAgentSession",
+    awaitUserMessage: "AwaitUserMessage",
+    runModel: "RunModel",
+    compactContext: "CompactContext",
+    awaitToolApproval: "AwaitToolApproval",
+    awaitQuestionAnswer: "AwaitQuestionAnswer",
+    awaitTimer: "AwaitTimer",
+    callTool: "CallTool",
+    callSingleAttemptTool: "CallSingleAttemptTool",
+    pollToolTask: "PollToolTask",
+    recordToolFailure: "RecordToolFailure",
+    recordToolOutcomeUnknown: "RecordToolOutcomeUnknown",
+    resumeTurn: "ResumeTurn",
+    applyTurnControl: "ApplyTurnControl",
+    recordTurnFailure: "RecordTurnFailure",
+    finishTurnCancellation: "FinishTurnCancellation",
+    cancelToolTask: "CancelToolTask",
+};
+//# sourceMappingURL=agent-session-step-types.js.map

package/dist/src/agent-session-step-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-step-types.js","sourceRoot":"","sources":["../../src/agent-session-step-types.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,iBAAiB,EAAE,mBAAmB;IACtC,gBAAgB,EAAE,kBAAkB;IACpC,QAAQ,EAAE,UAAU;IACpB,cAAc,EAAE,gBAAgB;IAChC,iBAAiB,EAAE,mBAAmB;IACtC,mBAAmB,EAAE,qBAAqB;IAC1C,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,UAAU;IACpB,qBAAqB,EAAE,uBAAuB;IAC9C,YAAY,EAAE,cAAc;IAC5B,iBAAiB,EAAE,mBAAmB;IACtC,wBAAwB,EAAE,0BAA0B;IACpD,UAAU,EAAE,YAAY;IACxB,gBAAgB,EAAE,kBAAkB;IACpC,iBAAiB,EAAE,mBAAmB;IACtC,sBAAsB,EAAE,wBAAwB;IAChD,cAAc,EAAE,gBAAgB;CACxB,CAAC"}

package/dist/src/agent-session-steps.d.ts

@@ -1,6 +1,10 @@
-import { Wait, type AsyncContext, type Codec, type Context, type Step, type StepDecision, type StepOptions } from "@superdurable/dex";
+import { StepMovement, Wait, type AsyncContext, type Codec, type Context, type RecoveryErrorInfo, type Step, type StepDecision, type StepOptions } from "@superdurable/dex";
+import { type ToolInputRequested } from "./agent-framework-runner.js";
 import { type AgentSessionTransitions } from "./agent-session-transitions.js";
-import { type AgentSessionStartInput } from "./agent-session-values.js";
+import { type AgentSessionPersistence } from "./agent-session-persistence.js";
+import { type AgentInterruptKind, type AgentSessionStartInput, type AgentToolCallRecord, type CompactContextInput, type PlanStatus } from "./agent-session-values.js";
+/** Start of the Flow failure reason when `StartAgentSession` refuses the start input's settings. */
+export declare const invalidStartSessionSettingsReason = "dex-agents: the start input's session_settings are not valid session settings";
 export declare class StartAgentSessionStep implements Step<AgentSessionStartInput> {
     private readonly transitions;
     readonly inputCodec: Codec<AgentSessionStartInput>;
@@ -9,15 +13,19 @@ export declare class StartAgentSessionStep implements Step<AgentSessionStartInpu
     getStepOptions(): StepOptions;
     execute(context: Context, input: AgentSessionStartInput): StepDecision;
 }
+/** Waits for one queued user message, or an approved plan execution, and starts its turn. */
 export declare class AwaitUserMessageStep implements Step<void> {
     private readonly transitions;
     readonly inputCodec: Codec<void>;
     constructor(transitions: AgentSessionTransitions);
     getStepType(): string;
     getStepOptions(): StepOptions;
-    waitFor(): Wait;
+    waitFor(context: Context): Wait;
     execute(context: Context): StepDecision;
+    private beginUserMessageTurn;
 }
+/** Plan statuses that `execute_plan` accepts and `AwaitUserMessage` waits for. */
+export declare function isExecutablePlanStatus(status: PlanStatus): boolean;
 /** Makes the turn's next model call and fans the requested tool calls out to parallel Steps. */
 export declare class RunModelStep implements Step<void> {
     private readonly transitions;
@@ -26,8 +34,31 @@ export declare class RunModelStep implements Step<void> {
     getStepType(): string;
     getStepOptions(): StepOptions;
     execute(context: AsyncContext): Promise<StepDecision>;
+    /** Returns RunModel's move instead of a model call, or `null` to call the model. */
+    private decideBeforeModelCall;
     private completeTurn;
+    /** Returns the sequence to summarize through before this model call, or `null` to make the call. */
+    private selectCompactionBeforeModelCall;
+    private startCompaction;
     private requestToolCalls;
+    /** A planning turn hides executable tools; a call to one never runs. */
+    private rejectPlanningTurnToolCall;
+    private deferApplicationToolCall;
+    /** Records a built-in call with its fixed policy and routes it to its wait Step; invalid arguments fail at once. */
+    private deferBuiltInToolCall;
+    /** Replaces the plan and records the call final, in this commit; no tool Step runs. */
+    private writeTodos;
+    private failBuiltInToolCall;
+}
+/** Summarizes the messages through a sequence for the model input, then moves back to `RunModel`. */
+export declare class CompactContextStep implements Step<CompactContextInput | undefined> {
+    private readonly transitions;
+    readonly inputCodec: Codec<CompactContextInput | undefined>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: AsyncContext, input: CompactContextInput | undefined): Promise<StepDecision>;
+    private summarize;
 }
 /** Waits for one tool call's approval or its deadline, then runs or rejects the call. */
 export declare class AwaitToolApprovalStep implements Step<string> {
@@ -38,8 +69,8 @@ export declare class AwaitToolApprovalStep implements Step<string> {
     getStepOptions(): StepOptions;
     waitFor(context: Context, toolCallId: string): Wait;
     execute(context: Context, toolCallId: string): StepDecision;
+    private applyResolution;
     private rejectToolCall;
-    private writeInterruptResolved;
 }
 /** Runs one tool call; one class serves `CallTool` and `CallSingleAttemptTool`. */
 export declare class ToolCallStep implements Step<string> {
@@ -50,11 +81,16 @@ export declare class ToolCallStep implements Step<string> {
     getStepType(): string;
     getStepOptions(): StepOptions;
     execute(context: AsyncContext, toolCallId: string): Promise<StepDecision>;
+    /** Records `awaiting_answer` with the tool's question; `AwaitQuestionAnswer` raises it under the lock. */
+    private requestToolInput;
+    /** Records `waiting_for_task` and moves to `PollToolTask`, or records a task it cannot poll by effect. */
+    private startToolTask;
 }
 /**
  * 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 declare class ToolCallFailureRecordingStep implements Step<string> {
     private readonly transitions;
@@ -66,7 +102,14 @@ export declare class ToolCallFailureRecordingStep implements Step<string> {
     getStepOptions(): StepOptions;
     execute(context: Context, toolCallId: string): StepDecision;
 }
-/** 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 declare function recoveredToolCall(toolCall: AgentToolCallRecord, recoveryError: RecoveryErrorInfo | undefined, status: "failed" | "outcome_unknown"): AgentToolCallRecord;
+/**
+ * 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 declare class ResumeTurnStep implements Step<number> {
     private readonly transitions;
     readonly inputCodec: Codec<number>;
@@ -74,13 +117,65 @@ export declare class ResumeTurnStep implements Step<number> {
     getStepType(): string;
     getStepOptions(): StepOptions;
     waitFor(_context: Context, expectedResultCount: number): Wait;
-    execute(context: Context): StepDecision;
+    execute(context: Context, expectedResultCount: number): StepDecision;
+    /** Cancels the turn's pending interrupts and wakes each Step waiting for a person or a Timer. */
+    private wakeWaitingToolCalls;
 }
-export declare class RecordTurnFailureStep implements Step<void> {
+/** Ends a steered or cancelled turn, then starts a turn with the steered messages. */
+export declare class ApplyTurnControlStep implements Step<void> {
     private readonly transitions;
     readonly inputCodec: Codec<void>;
     constructor(transitions: AgentSessionTransitions);
     getStepType(): string;
     getStepOptions(): StepOptions;
+    waitFor(): Wait;
     execute(context: Context): StepDecision;
 }
+/** Ends a failed turn; it is the failure route of `RunModel` and `CompactContext`, so it takes either's input. */
+export declare class RecordTurnFailureStep implements Step<CompactContextInput | undefined> {
+    private readonly transitions;
+    readonly inputCodec: Codec<CompactContextInput | undefined>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: Context): StepDecision;
+}
+/** Reports whether a Step failed because its commit would exceed the Flow's state limit. */
+export declare function isStateLimitFailure(recoveryError: RecoveryErrorInfo | undefined): boolean;
+/** `last_turn_error` of a turn whose runner stored messages incrementally without the builder. */
+export declare const missingUnfinishedTurnMessageBuilder = "a runner that sets ToolCallsRequested.newMessages must implement buildUnfinishedTurnMessages";
+/**
+ * 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.
+ */
+export declare function toolStepOptions(persistence: AgentSessionPersistence, stepType: string, toolCallId?: string): StepOptions;
+export declare function toolStepMovement(persistence: AgentSessionPersistence, stepType: string, toolCallId: string): StepMovement<string>;
+/** Moves to `PollToolTask`; a poll that keeps failing leaves the task running, so the call is recorded by effect. */
+export declare function toolTaskPollMovement(persistence: AgentSessionPersistence, toolCall: AgentToolCallRecord): StepMovement<string>;
+/** Returns the record of a tool's question: `awaiting_answer`, or `failed` when it is blank. */
+export declare function recordToolInputRequest(toolCall: AgentToolCallRecord, request: ToolInputRequested): AgentToolCallRecord;
+/** Returns a final record for a task that cannot be polled: `failed` for a read, else `outcome_unknown`. */
+export declare function recordToolTaskDefect(toolCall: AgentToolCallRecord, error: string): AgentToolCallRecord;
+/** Returns a poll interval in whole seconds from 1 to a day, or `null` when it is not a finite number. */
+export declare function toolTaskPollIntervalSeconds(seconds: unknown): number | null;
+/** Record fields of a call without a pending tool question. */
+export declare const noPendingToolQuestion: {
+    readonly inputQuestion: null;
+    readonly inputChoices: readonly [];
+    readonly inputAllowsFreeText: true;
+};
+/** Moves to `AwaitQuestionAnswer`, which reads the answer count to tell an unraised question from an answer. */
+export declare function questionAnswerMovement(persistence: AgentSessionPersistence, toolCall: AgentToolCallRecord): StepMovement<string>;
+/** An `ask_user` question uses the tool call ID; a tool's `n`-th question appends `-input-<n>`. */
+export declare function questionInterruptId(toolCall: AgentToolCallRecord): string;
+/** The interrupt a waiting tool call answers to: its ID and kind. */
+export interface WaitingToolCallInterrupt {
+    readonly interruptId: string;
+    readonly kind: AgentInterruptKind;
+}
+/**
+ * Records a call that `ToolCallCancellations` woke as cancelled, or waits again. Pass `interrupt` `null` for a
+ * durable wait.
+ */
+export declare function cancelWaitingToolCall(transitions: AgentSessionTransitions, context: Context, toolCall: AgentToolCallRecord, interrupt: WaitingToolCallInterrupt | null, waitAgain: StepMovement<string>): StepDecision;
+export declare function isToolInputRequested(outcome: unknown): outcome is ToolInputRequested;