@superdurable/dex-agents 0.1.0 → 0.2.0

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

@@ -1,5 +1,5 @@
 import { Attribute, AttributeMap, Channel, ChannelMap, Stream } from "@superdurable/dex";
-import type { AgentEvent, AgentInterrupt, AgentInterruptResolution, AgentMessage, AgentState, AgentToolCall, AgentUsage, AgentUserMessage, ToolCallCompleted } from "./agent-session-values.js";
+import type { AgentEvent, AgentInterrupt, AgentInterruptResolution, AgentMessage, AgentMessageChunk, AgentMessageIndex, AgentPlan, AgentState, AgentToolCallRecord, AgentUsage, AgentUserMessage, PlanExecutionRequest, ContextSummary, SessionSettings, TurnReplySequence, TurnSessionSettings, ToolCallCancellation, ToolCallCompleted, TurnCancellationRequest, TurnControlRequest } from "./agent-session-values.js";
 /** Default byte budget of the `AgentEvents` Stream: 10 MiB. */
 export declare const defaultAgentEventsCapacityBytes: number;
 /**
@@ -19,12 +19,25 @@ export declare const defaultAgentEventsCapacityBytes: number;
 export interface AgentSessionPersistence {
     /** The `AgentState` Attribute. It is always set after `StartAgentSession`. */
     readonly agentState: Attribute<AgentState>;
-    /** The `AgentMessages` AttributeMap, keyed by sequence as 12-digit zero-padded decimal. */
+    /**
+     * The `AgentMessages` AttributeMap: the window of the newest messages, one instance per message, keyed by
+     * {@link messageSequenceKey}. Older messages are in {@link agentMessageChunks}; see {@link agentMessageIndex}.
+     */
     readonly agentMessages: AttributeMap<AgentMessage>;
+    /**
+     * The `AgentMessageChunks` AttributeMap: immutable archive chunks of older messages, keyed by
+     * {@link messageSequenceKey} of each chunk's first sequence.
+     */
+    readonly agentMessageChunks: AttributeMap<AgentMessageChunk>;
+    /**
+     * The `AgentMessageIndex` Attribute: where the window and the retained chunks start. A session that a 0.1.0
+     * Worker wrote has none until its first write on this version.
+     */
+    readonly agentMessageIndex: Attribute<AgentMessageIndex>;
     /** The `FrameworkRunState` Attribute: opaque framework JSON, set only while a turn is suspended. */
     readonly frameworkRunState: Attribute<string>;
     /** The `AgentToolCalls` AttributeMap, keyed by tool call ID; holds only the active turn's records. */
-    readonly agentToolCalls: AttributeMap<AgentToolCall>;
+    readonly agentToolCalls: AttributeMap<AgentToolCallRecord>;
     /** The `PendingInterrupts` Attribute: interrupts that `resolve_interrupt` still accepts. */
     readonly pendingInterrupts: Attribute<readonly AgentInterrupt[]>;
     /** The `AgentUsage` Attribute: cumulative usage of every turn. */
@@ -38,12 +51,68 @@ export interface AgentSessionPersistence {
      * record becomes final, and `ResumeTurn` consumes them. Applications never publish to it.
      */
     readonly toolCallResults: Channel<ToolCallCompleted>;
+    /** The `SteeredUserMessages` Channel; `steer_user_message` publishes and `ApplyTurnControl` consumes. */
+    readonly steeredUserMessages: Channel<AgentUserMessage>;
+    /**
+     * The internal `TurnControlRequests` Channel. `steer_user_message` and `cancel_turn` publish to it, and its
+     * messages only wake `ResumeTurn` or `AwaitUserMessage`.
+     */
+    readonly turnControlRequests: Channel<TurnControlRequest>;
+    /** The `TurnCancellationRequest` Attribute: the latest `cancel_turn` request. Only `cancel_turn` writes it. */
+    readonly turnCancellationRequest: Attribute<TurnCancellationRequest>;
+    /**
+     * The internal `ToolCallCancellations` ChannelMap, keyed by tool call ID. `ResumeTurn` publishes to it to wake
+     * the Step that waits on a call of a steered or cancelled turn.
+     */
+    readonly toolCallCancellations: ChannelMap<ToolCallCancellation>;
     /** The best-effort `AgentEvents` Stream. Rebuild durable state with `get_agent_snapshot`. */
     readonly agentEvents: Stream<AgentEvent>;
+    /**
+     * The `AgentTraceContext` Attribute: the W3C `traceparent` of the current activation's root span when
+     * that span has a valid context, sampled or not; an activation whose root has none, such as one without
+     * an OpenTelemetry SDK, deletes it. `RunModel` reads it to join the activation's trace.
+     */
+    readonly agentTraceContext: Attribute<string>;
+    /** The `AgentPlan` Attribute: the session's plan, unset until `write_todos` first succeeds. */
+    readonly agentPlan: Attribute<AgentPlan>;
+    /**
+     * The `PlanExecutions` ChannelMap, keyed by {@link planExecutionKey}: approved plan executions that
+     * `execute_plan` publishes and `AwaitUserMessage` consumes.
+     */
+    readonly planExecutions: ChannelMap<PlanExecutionRequest>;
+    /**
+     * The `PendingPlanExecution` Attribute: the execution `execute_plan` accepted and `AwaitUserMessage` has
+     * not consumed yet.
+     */
+    readonly pendingPlanExecution: Attribute<PlanExecutionRequest>;
+    /**
+     * The `ContextSummary` Attribute: the summary that replaces the earlier messages in the model input,
+     * set once the session compacts. Only `CompactContext` writes it.
+     */
+    readonly contextSummary: Attribute<ContextSummary>;
+    /**
+     * The `SessionSettings` Attribute: the settings the next turn starts with, from the start input and then each
+     * `update_session_settings`. Unset when the session has none.
+     */
+    readonly sessionSettings: Attribute<SessionSettings>;
+    /**
+     * The `TurnSessionSettings` Attribute: the settings a turn started with, tagged with its turn, copied from
+     * `SessionSettings` when the turn began. A copy from an earlier turn reads as no settings.
+     */
+    readonly turnSessionSettings: Attribute<TurnSessionSettings>;
+    /**
+     * The `TurnReplySequence` Attribute: where the latest turn's replies start, tagged with its turn. The Step
+     * that starts a turn writes it; turn events count the replies from it.
+     */
+    readonly turnReplySequence: Attribute<TurnReplySequence>;
 }
 export declare function createAgentSessionPersistence(agentEventsCapacityBytes: number): AgentSessionPersistence;
 /**
- * Returns the `AgentMessages` map instance of a message sequence.
+ * Returns the `AgentMessages` map instance of a message sequence, which is also the `AgentMessageChunks`
+ * instance of a chunk that starts at that sequence.
+ *
+ * A message stays in `AgentMessages` only while it is in the window; read older ones from their chunk, or
+ * page through all of them with `list_agent_messages`.
  *
  * @example
  * ```ts
@@ -54,3 +123,11 @@ export declare function createAgentSessionPersistence(agentEventsCapacityBytes:
  * @throws {RangeError} When `sequence` is not a positive safe integer.
  */
 export declare function messageSequenceKey(sequence: number): string;
+/**
+ * Returns the `PlanExecutions` map instance of a plan revision.
+ *
+ * @param revision - Positive {@link AgentPlan.revision}.
+ * @returns The revision as a decimal, such as `"3"`.
+ * @throws {RangeError} When `revision` is not a positive safe integer.
+ */
+export declare function planExecutionKey(revision: number): string;

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

@@ -6,13 +6,15 @@
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
 import { Attribute, AttributeMap, Channel, ChannelMap, Stream, stringCodec } from "@superdurable/dex";
-import { agentEventCodec, agentInterruptListCodec, agentInterruptResolutionCodec, agentMessageCodec, agentStateCodec, agentToolCallCodec, agentUsageCodec, agentUserMessageCodec, toolCallCompletedCodec, } from "./agent-session-codecs.js";
+import { agentEventCodec, agentInterruptListCodec, agentInterruptResolutionCodec, agentMessageChunkCodec, agentMessageCodec, agentMessageIndexCodec, agentPlanCodec, agentStateCodec, agentToolCallCodec, agentUsageCodec, agentUserMessageCodec, planExecutionRequestCodec, contextSummaryCodec, sessionSettingsCodec, turnSessionSettingsCodec, turnReplySequenceCodec, toolCallCancellationCodec, toolCallCompletedCodec, turnCancellationRequestCodec, turnControlRequestCodec, } from "./agent-session-codecs.js";
 /** Default byte budget of the `AgentEvents` Stream: 10 MiB. */
 export const defaultAgentEventsCapacityBytes = 10 * 1024 * 1024;
 export function createAgentSessionPersistence(agentEventsCapacityBytes) {
     return {
         agentState: new Attribute("AgentState", agentStateCodec),
         agentMessages: new AttributeMap("AgentMessages", agentMessageCodec),
+        agentMessageChunks: new AttributeMap("AgentMessageChunks", agentMessageChunkCodec),
+        agentMessageIndex: new Attribute("AgentMessageIndex", agentMessageIndexCodec),
         frameworkRunState: new Attribute("FrameworkRunState", stringCodec),
         agentToolCalls: new AttributeMap("AgentToolCalls", agentToolCallCodec),
         pendingInterrupts: new Attribute("PendingInterrupts", agentInterruptListCodec),
@@ -20,11 +22,27 @@ export function createAgentSessionPersistence(agentEventsCapacityBytes) {
         queuedUserMessages: new Channel("QueuedUserMessages", agentUserMessageCodec),
         interruptResolutions: new ChannelMap("InterruptResolutions", agentInterruptResolutionCodec),
         toolCallResults: new Channel("ToolCallResults", toolCallCompletedCodec),
+        steeredUserMessages: new Channel("SteeredUserMessages", agentUserMessageCodec),
+        turnControlRequests: new Channel("TurnControlRequests", turnControlRequestCodec),
+        turnCancellationRequest: new Attribute("TurnCancellationRequest", turnCancellationRequestCodec),
+        toolCallCancellations: new ChannelMap("ToolCallCancellations", toolCallCancellationCodec),
         agentEvents: new Stream("AgentEvents", agentEventCodec, agentEventsCapacityBytes),
+        agentTraceContext: new Attribute("AgentTraceContext", stringCodec),
+        agentPlan: new Attribute("AgentPlan", agentPlanCodec),
+        planExecutions: new ChannelMap("PlanExecutions", planExecutionRequestCodec),
+        pendingPlanExecution: new Attribute("PendingPlanExecution", planExecutionRequestCodec),
+        contextSummary: new Attribute("ContextSummary", contextSummaryCodec),
+        sessionSettings: new Attribute("SessionSettings", sessionSettingsCodec),
+        turnSessionSettings: new Attribute("TurnSessionSettings", turnSessionSettingsCodec),
+        turnReplySequence: new Attribute("TurnReplySequence", turnReplySequenceCodec),
     };
 }
 /**
- * Returns the `AgentMessages` map instance of a message sequence.
+ * Returns the `AgentMessages` map instance of a message sequence, which is also the `AgentMessageChunks`
+ * instance of a chunk that starts at that sequence.
+ *
+ * A message stays in `AgentMessages` only while it is in the window; read older ones from their chunk, or
+ * page through all of them with `list_agent_messages`.
  *
  * @example
  * ```ts
@@ -40,4 +58,17 @@ export function messageSequenceKey(sequence) {
     }
     return String(sequence).padStart(12, "0");
 }
+/**
+ * Returns the `PlanExecutions` map instance of a plan revision.
+ *
+ * @param revision - Positive {@link AgentPlan.revision}.
+ * @returns The revision as a decimal, such as `"3"`.
+ * @throws {RangeError} When `revision` is not a positive safe integer.
+ */
+export function planExecutionKey(revision) {
+    if (!Number.isSafeInteger(revision) || revision <= 0) {
+        throw new RangeError(`plan revision must be a positive integer: ${revision}`);
+    }
+    return String(revision);
+}
 //# sourceMappingURL=agent-session-persistence.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"agent-session-persistence.js","sourceRoot":"","sources":["../../src/agent-session-persistence.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEtG,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,6BAA6B,EAC7B,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAanC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AA0ChE,MAAM,UAAU,6BAA6B,CAC3C,wBAAgC;IAEhC,OAAO;QACL,UAAU,EAAE,IAAI,SAAS,CAAC,YAAY,EAAE,eAAe,CAAC;QACxD,aAAa,EAAE,IAAI,YAAY,CAAC,eAAe,EAAE,iBAAiB,CAAC;QACnE,iBAAiB,EAAE,IAAI,SAAS,CAAC,mBAAmB,EAAE,WAAW,CAAC;QAClE,cAAc,EAAE,IAAI,YAAY,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;QACtE,iBAAiB,EAAE,IAAI,SAAS,CAAC,mBAAmB,EAAE,uBAAuB,CAAC;QAC9E,UAAU,EAAE,IAAI,SAAS,CAAC,YAAY,EAAE,eAAe,CAAC;QACxD,kBAAkB,EAAE,IAAI,OAAO,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;QAC5E,oBAAoB,EAAE,IAAI,UAAU,CAAC,sBAAsB,EAAE,6BAA6B,CAAC;QAC3F,eAAe,EAAE,IAAI,OAAO,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;QACvE,WAAW,EAAE,IAAI,MAAM,CAAC,aAAa,EAAE,eAAe,EAAE,wBAAwB,CAAC;KAClF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAAC,gDAAgD,QAAQ,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"agent-session-persistence.js","sourceRoot":"","sources":["../../src/agent-session-persistence.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,58 @@
+import type { SessionSettings } from "./agent-session-values.js";
+/** Largest {@link SessionSettings}, as the UTF-8 bytes of their compact JSON text: 16 KiB. Same in every core. */
+export declare const MAX_SESSION_SETTINGS_BYTES: number;
+/**
+ * Extra bytes the session's own Steps and RPC accept over {@link MAX_SESSION_SETTINGS_BYTES}.
+ *
+ * The cores write some numbers and characters differently, so settings that one core's Client accepted can
+ * measure a few bytes more in another core's Worker. The tolerance keeps that from failing a session.
+ * {@link validateSessionSettings} checks the exact limit.
+ */
+export declare const SESSION_SETTINGS_SIZE_TOLERANCE_BYTES = 1024;
+/**
+ * Returns the size of session settings that {@link MAX_SESSION_SETTINGS_BYTES} limits.
+ *
+ * The size is the UTF-8 byte length of `JSON.stringify(sessionSettings)`: compact, with characters outside ASCII
+ * written as themselves. The Python and Go cores measure their own JSON text, which is the same for strings,
+ * integers, booleans, `null`, objects, and arrays, with two exceptions: Python writes floats in their shortest
+ * form, such as `1.0` and `1e+16`, where this core writes `1` and `10000000000000000`, and Go escapes U+2028
+ * and U+2029. So sizes can differ by a few bytes per float or per such character. The session's Steps and RPC
+ * accept {@link SESSION_SETTINGS_SIZE_TOLERANCE_BYTES} more than the limit, so settings that another core's
+ * Client accepted never fail a session.
+ *
+ * @example
+ * ```ts
+ * sessionSettingsSize({ model: "gpt-5-mini" }); // 22
+ * ```
+ * @param sessionSettings - The settings.
+ * @returns The size in bytes.
+ * @throws {TypeError} When the settings cannot be written as JSON, such as with a cycle or a `bigint`.
+ */
+export declare function sessionSettingsSize(sessionSettings: SessionSettings): number;
+/**
+ * Checks that a value can be a session's settings: a JSON object whose compact JSON text fits in
+ * {@link MAX_SESSION_SETTINGS_BYTES}.
+ *
+ * Call it before `Client.startFlow` or the `update_session_settings` RPC, such as in a form handler. A start whose
+ * settings the session refuses fails the session at once, and the RPC returns `false`.
+ * `AgentSessionTestClient.startSession` calls it.
+ *
+ * @example
+ * ```ts
+ * validateSessionSettings({ model: "gpt-5-mini" });
+ * await client.startFlow(flow, sessionId, { initialMessage: null, sessionSettings: { model: "gpt-5-mini" } });
+ * ```
+ * @param sessionSettings - The candidate settings.
+ * @throws {TypeError} When the value is not a plain JSON object or cannot be written as JSON.
+ * @throws {RangeError} When its compact JSON text is larger than {@link MAX_SESSION_SETTINGS_BYTES}.
+ */
+export declare function validateSessionSettings(sessionSettings: unknown): asserts sessionSettings is SessionSettings;
+/**
+ * Checks settings as the session's Steps and RPC do: {@link validateSessionSettings} with a limit of
+ * {@link MAX_SESSION_SETTINGS_BYTES} plus {@link SESSION_SETTINGS_SIZE_TOLERANCE_BYTES}.
+ *
+ * @param sessionSettings - The candidate settings.
+ * @throws {TypeError} When the value is not a plain JSON object or cannot be written as JSON.
+ * @throws {RangeError} When its compact JSON text is larger than the session's limit.
+ */
+export declare function checkStoredSessionSettings(sessionSettings: unknown): asserts sessionSettings is SessionSettings;

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

@@ -0,0 +1,81 @@
+// 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
+/** Largest {@link SessionSettings}, as the UTF-8 bytes of their compact JSON text: 16 KiB. Same in every core. */
+export const MAX_SESSION_SETTINGS_BYTES = 16 * 1024;
+/**
+ * Extra bytes the session's own Steps and RPC accept over {@link MAX_SESSION_SETTINGS_BYTES}.
+ *
+ * The cores write some numbers and characters differently, so settings that one core's Client accepted can
+ * measure a few bytes more in another core's Worker. The tolerance keeps that from failing a session.
+ * {@link validateSessionSettings} checks the exact limit.
+ */
+export const SESSION_SETTINGS_SIZE_TOLERANCE_BYTES = 1024;
+const utf8Encoder = new TextEncoder();
+/**
+ * Returns the size of session settings that {@link MAX_SESSION_SETTINGS_BYTES} limits.
+ *
+ * The size is the UTF-8 byte length of `JSON.stringify(sessionSettings)`: compact, with characters outside ASCII
+ * written as themselves. The Python and Go cores measure their own JSON text, which is the same for strings,
+ * integers, booleans, `null`, objects, and arrays, with two exceptions: Python writes floats in their shortest
+ * form, such as `1.0` and `1e+16`, where this core writes `1` and `10000000000000000`, and Go escapes U+2028
+ * and U+2029. So sizes can differ by a few bytes per float or per such character. The session's Steps and RPC
+ * accept {@link SESSION_SETTINGS_SIZE_TOLERANCE_BYTES} more than the limit, so settings that another core's
+ * Client accepted never fail a session.
+ *
+ * @example
+ * ```ts
+ * sessionSettingsSize({ model: "gpt-5-mini" }); // 22
+ * ```
+ * @param sessionSettings - The settings.
+ * @returns The size in bytes.
+ * @throws {TypeError} When the settings cannot be written as JSON, such as with a cycle or a `bigint`.
+ */
+export function sessionSettingsSize(sessionSettings) {
+    return utf8Encoder.encode(JSON.stringify(sessionSettings)).length;
+}
+/**
+ * Checks that a value can be a session's settings: a JSON object whose compact JSON text fits in
+ * {@link MAX_SESSION_SETTINGS_BYTES}.
+ *
+ * Call it before `Client.startFlow` or the `update_session_settings` RPC, such as in a form handler. A start whose
+ * settings the session refuses fails the session at once, and the RPC returns `false`.
+ * `AgentSessionTestClient.startSession` calls it.
+ *
+ * @example
+ * ```ts
+ * validateSessionSettings({ model: "gpt-5-mini" });
+ * await client.startFlow(flow, sessionId, { initialMessage: null, sessionSettings: { model: "gpt-5-mini" } });
+ * ```
+ * @param sessionSettings - The candidate settings.
+ * @throws {TypeError} When the value is not a plain JSON object or cannot be written as JSON.
+ * @throws {RangeError} When its compact JSON text is larger than {@link MAX_SESSION_SETTINGS_BYTES}.
+ */
+export function validateSessionSettings(sessionSettings) {
+    checkSessionSettings(sessionSettings, MAX_SESSION_SETTINGS_BYTES);
+}
+/**
+ * Checks settings as the session's Steps and RPC do: {@link validateSessionSettings} with a limit of
+ * {@link MAX_SESSION_SETTINGS_BYTES} plus {@link SESSION_SETTINGS_SIZE_TOLERANCE_BYTES}.
+ *
+ * @param sessionSettings - The candidate settings.
+ * @throws {TypeError} When the value is not a plain JSON object or cannot be written as JSON.
+ * @throws {RangeError} When its compact JSON text is larger than the session's limit.
+ */
+export function checkStoredSessionSettings(sessionSettings) {
+    checkSessionSettings(sessionSettings, MAX_SESSION_SETTINGS_BYTES + SESSION_SETTINGS_SIZE_TOLERANCE_BYTES);
+}
+function checkSessionSettings(sessionSettings, limitBytes) {
+    if (typeof sessionSettings !== "object" || sessionSettings === null || Array.isArray(sessionSettings)) {
+        throw new TypeError("session settings must be a JSON object");
+    }
+    const size = sessionSettingsSize(sessionSettings);
+    if (size > limitBytes) {
+        throw new RangeError(`session settings are ${size} bytes, more than the ${limitBytes} allowed`);
+    }
+}
+//# sourceMappingURL=agent-session-settings.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-settings.js","sourceRoot":"","sources":["../../src/agent-session-settings.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAI1D,kHAAkH;AAClH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,IAAI,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG,IAAI,CAAC;AAE1D,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,eAAgC;IAClE,OAAO,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,eAAwB;IAC9D,oBAAoB,CAAC,eAAe,EAAE,0BAA0B,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,eAAwB;IACjE,oBAAoB,CAAC,eAAe,EAAE,0BAA0B,GAAG,qCAAqC,CAAC,CAAC;AAC5G,CAAC;AAED,SAAS,oBAAoB,CAAC,eAAwB,EAAE,UAAkB;IACxE,IAAI,OAAO,eAAe,KAAK,QAAQ,IAAI,eAAe,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QACtG,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,IAAI,GAAG,mBAAmB,CAAC,eAAkC,CAAC,CAAC;IACrE,IAAI,IAAI,GAAG,UAAU,EAAE,CAAC;QACtB,MAAM,IAAI,UAAU,CAAC,wBAAwB,IAAI,yBAAyB,UAAU,UAAU,CAAC,CAAC;IAClG,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,27 @@
+import { ExecuteFailure, type AttributeMapLoad, type RetryPolicy, type StepOptions } from "@superdurable/dex";
+import type { AgentSessionPersistence } from "./agent-session-persistence.js";
+export declare const minuteMs = 60000;
+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): StepOptions;

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

@@ -0,0 +1,39 @@
+// 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;
+// 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) {
+    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, ...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":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,cAAc,EAAE,OAAO,EAA6D,MAAM,mBAAmB,CAAC;AAGvH,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,sBAAsB,EAAE,EAAE,GAAG,QAAQ;IACrC,kBAAkB,EAAE,CAAC,GAAG,QAAQ;IAChC,YAAY,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,EAAE,EAAE,GAAG,QAAQ,EAAE;IACpE,cAAc,EAAE,cAAc,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;CAChE,CAAC;AACjC,qGAAqG;AACrG,MAAM,CAAC,MAAM,aAAa,GAAgB,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC;AACvE,mGAAmG;AACnG,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAW,CAAC;AAWhG,sGAAsG;AACtG,MAAM,UAAU,kBAAkB,CAChC,WAAoC,EACpC,QAAgB,EAChB,UAA6B;IAE7B,MAAM,KAAK,GAAG;QACZ,wBAAwB,EAAE,UAAU,CAAC,UAAU;YAC7C,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa,EAAE,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,kBAAkB,CAAC;YACzF,CAAC,CAAC,CAAC,WAAW,CAAC,aAAa,EAAE,WAAW,CAAC,cAAc,CAAC;QAC3D,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gCAAgC,EAAE,UAAU,CAAC,SAAS,EAAE,CAAC;KACzG,CAAC;IACF,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,qBAAqB,CAAC,QAAQ;YACjC,OAAO,EAAE,GAAG,cAAc,EAAE,GAAG,oBAAoB,EAAE,GAAG,KAAK,EAAE,CAAC;QAClE,KAAK,qBAAqB,CAAC,gBAAgB;YACzC,OAAO,EAAE,GAAG,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,KAAK,EAAE,CAAC;QACtE;YACE,MAAM,IAAI,SAAS,CAAC,aAAa,QAAQ,gCAAgC,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC"}

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,63 @@ 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;
+}
+/** `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;