@superdurable/dex-agents 0.1.0 → 0.3.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-spend-limit.d.ts

@@ -0,0 +1,156 @@
+import type { AgentUsage, SessionSettings } from "./agent-session-values.js";
+/**
+ * How long the session waits for {@link ModelSpendLimit.checkModelCall} or {@link ModelSpendLimit.reportModelUsage},
+ * in milliseconds. Bound your own calls below it. A check that takes longer counts as a check that threw. A report
+ * that takes longer is dropped.
+ *
+ * @since 0.3.0
+ */
+export declare const spendLimitCallTimeoutMs = 30000;
+/**
+ * Starts `AgentState.lastTurnError` of a turn that a spend limit ended. The text goes on with `": "` and the reason
+ * from {@link ModelCallDecision}. Test for it to tell a refused call from a failed one.
+ *
+ * @since 0.3.0
+ */
+export declare const modelCallRefusedErrorPrefix = "the model call was refused";
+/**
+ * Describes one model call that is about to run. The session builds one for every attempt of `RunModel` and
+ * `CompactContext`, because every attempt can cost money.
+ *
+ * @since 0.3.0
+ */
+export interface ModelCallCheck {
+    /** The session's Flow ID. */
+    readonly flowId: string;
+    /** The turn that makes the call. */
+    readonly turnId: string;
+    /** `"RunModel"` or `"CompactContext"`. */
+    readonly stepType: string;
+    /** One-based attempt of the Step. */
+    readonly attempt: number;
+    /** The turn's session settings. Put the account or API key reference that the limit applies to here. Never a secret. */
+    readonly sessionSettings: SessionSettings;
+    /** Committed usage of this session so far. */
+    readonly sessionUsage: AgentUsage;
+}
+/**
+ * Says whether a model call may run. `reason` reaches `AgentState.lastTurnError`, so people read it, and it is stored.
+ * Never put a secret in it.
+ *
+ * @since 0.3.0
+ */
+export type ModelCallDecision = {
+    readonly isAllowed: true;
+} | {
+    readonly isAllowed: false;
+    readonly reason: string;
+};
+/**
+ * Reports what one finished model call used.
+ *
+ * @since 0.3.0
+ */
+export interface ModelUsageReport {
+    /**
+     * Stable ID of this attempt's call: `<flow>/<turn>/<step execution>/<attempt>`. Count each ID once. A retry has a new
+     * ID because it is a new paid call.
+     */
+    readonly reportId: string;
+    /** The session's Flow ID. */
+    readonly flowId: string;
+    /** The turn that made the call. */
+    readonly turnId: string;
+    /** `"RunModel"` or `"CompactContext"`. */
+    readonly stepType: string;
+    /** One-based attempt of the Step. */
+    readonly attempt: number;
+    /** The turn's session settings. */
+    readonly sessionSettings: SessionSettings;
+    /**
+     * What the runner reported. A harness runner, such as the Claude Agent SDK adapter, reports a whole segment here:
+     * several model calls in `usage.modelCalls`. Zero tokens with `modelCalls` above zero mean the framework did not
+     * expose token counts, not that the call was free.
+     */
+    readonly usage: AgentUsage;
+    /**
+     * `usage` added to the committed session usage. It includes a call whose report threw or timed out, for an
+     * application that counts per session.
+     */
+    readonly sessionUsage: AgentUsage;
+}
+/**
+ * Lets an application decide whether a session may spend on a model call.
+ *
+ * A spend limit is usually per account or per API key, across many sessions, so the counters and the limit belong to
+ * the application. Pass an implementation as `AgentSessionOptions.spendLimit`. Without one, the session makes no
+ * checks. The object lives in the Worker and is not stored.
+ *
+ * The session calls {@link checkModelCall} before each attempt of `RunModel` and `CompactContext`, and
+ * {@link reportModelUsage} after the attempt's model call returns. Both run inside the Step, on the Worker, so keep
+ * them fast and bound them below {@link spendLimitCallTimeoutMs}.
+ *
+ * A refused call ends the turn: the session records {@link modelCallRefusedErrorPrefix} and the reason in
+ * `AgentState.lastTurnError`, keeps the turn's finished tool results, and waits for the next user message, which is
+ * checked again. A check that throws or times out fails closed. It fails the attempt, Dex retries it under the Step's
+ * retry policy, and no model call runs without a passed check. When the retries run out the turn fails. To fail open,
+ * catch your own errors in `checkModelCall` and return `{ isAllowed: true }`.
+ *
+ * A report that throws or times out is logged and dropped, because failing the attempt would repeat a call that was
+ * already paid for.
+ *
+ * Limits to design for:
+ *
+ * - A check bounds the next call, not its cost. Sessions that pass together can overshoot a limit. A harness runner is
+ *   checked once per segment, so the overshoot can be a whole segment. Set the harness's own budget option too, such
+ *   as `maxBudgetUsd` for the Claude Agent SDK.
+ * - A call that fails, is cancelled, or is lost with its Worker reports nothing, though the provider may bill it. So
+ *   the reports can be lower than the bill. They can also exceed `AgentUsage`: a call whose Step did not commit reports
+ *   here and again on its retry, under a new `reportId`, while `AgentUsage` keeps only the committed attempt.
+ * - Reports are not durable. A report runs inside the Step, so a Worker that dies between the model's answer and the
+ *   report loses it. That attempt never commits, so `AgentUsage` does not hold the call either, and only the provider's
+ *   bill does. A report that threw or timed out is different: its attempt commits, so the next report's `sessionUsage`
+ *   includes it.
+ *
+ * @example
+ * ```ts
+ * const spendLimit: ModelSpendLimit = {
+ *   async checkModelCall(check) {
+ *     const account = check.sessionSettings.account as string;
+ *     return (await spentThisMonth(account)) >= limitOf(account)
+ *       ? { isAllowed: false, reason: "account over its monthly limit" }
+ *       : { isAllowed: true };
+ *   },
+ *   async reportModelUsage(report) {
+ *     await recordOnce(report.reportId, report.usage);
+ *   },
+ * };
+ * const flow = createAgentSessionFlow(runner, "SupportAgent", { spendLimit });
+ * ```
+ *
+ * @since 0.3.0
+ */
+export interface ModelSpendLimit {
+    /**
+     * Decides whether one model call may run.
+     * @param check - The call that is about to run.
+     * @returns The decision.
+     * @throws Any error fails the attempt, so the call does not run.
+     */
+    checkModelCall(check: ModelCallCheck): Promise<ModelCallDecision>;
+    /**
+     * Records what one finished model call used.
+     * @param report - The call's usage. Count each `reportId` once.
+     * @returns A Promise that settles when the usage is recorded.
+     * @throws Any error is logged and dropped.
+     */
+    reportModelUsage(report: ModelUsageReport): Promise<void>;
+}
+/**
+ * Settles with `operation`, or rejects after {@link spendLimitCallTimeoutMs}.
+ * @param description - What is running, for the timeout message.
+ * @param operation - The application's call.
+ * @returns The call's result.
+ * @throws {Error} When the call takes too long, or what the call threw.
+ */
+export declare function withinSpendLimitCallTimeout<Result>(description: string, operation: Promise<Result>): Promise<Result>;

package/dist/src/agent-session-spend-limit.js

@@ -0,0 +1,42 @@
+// 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
+/**
+ * How long the session waits for {@link ModelSpendLimit.checkModelCall} or {@link ModelSpendLimit.reportModelUsage},
+ * in milliseconds. Bound your own calls below it. A check that takes longer counts as a check that threw. A report
+ * that takes longer is dropped.
+ *
+ * @since 0.3.0
+ */
+export const spendLimitCallTimeoutMs = 30_000;
+/**
+ * Starts `AgentState.lastTurnError` of a turn that a spend limit ended. The text goes on with `": "` and the reason
+ * from {@link ModelCallDecision}. Test for it to tell a refused call from a failed one.
+ *
+ * @since 0.3.0
+ */
+export const modelCallRefusedErrorPrefix = "the model call was refused";
+/**
+ * Settles with `operation`, or rejects after {@link spendLimitCallTimeoutMs}.
+ * @param description - What is running, for the timeout message.
+ * @param operation - The application's call.
+ * @returns The call's result.
+ * @throws {Error} When the call takes too long, or what the call threw.
+ */
+export async function withinSpendLimitCallTimeout(description, operation) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${description} took more than ${spendLimitCallTimeoutMs} ms`)), spendLimitCallTimeoutMs);
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=agent-session-spend-limit.js.map

package/dist/src/agent-session-spend-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-spend-limit.js","sourceRoot":"","sources":["../../src/agent-session-spend-limit.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAI1D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,4BAA4B,CAAC;AAqIxE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,WAAmB,EACnB,SAA0B;IAE1B,IAAI,KAAiC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC/C,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,WAAW,mBAAmB,uBAAuB,KAAK,CAAC,CAAC,EACtF,uBAAuB,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,49 @@
+import { ActiveStepSearchMode, type Client, type StartFlowOptions } from "@superdurable/dex";
+import type { AgentFrameworkRunner, DeferredToolOutcome } from "./agent-framework-runner.js";
+import type { AgentSessionFlow } from "./agent-session-flow.js";
+import type { AgentSessionStartInput } from "./agent-session-values.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 declare const agentSessionActiveStepSearchMode: ActiveStepSearchMode;
+/**
+ * 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 declare function startAgentSession(client: Client, flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>, sessionId: string, input?: Partial<AgentSessionStartInput>, options?: StartFlowOptions): Promise<string>;