@superdurable/dex-agents 0.1.0 → 0.3.0

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

@@ -1,8 +1,29 @@
 import { type Context, type Flow, type RPCResult } from "@superdurable/dex";
-import type { AgentFrameworkRunner, ToolPolicy } from "./agent-framework-runner.js";
+import { type BuiltInTool } from "./agent-built-in-tools.js";
+import { type CompactionPolicy, type ResolvedCompactionPolicy } from "./agent-context-compaction.js";
+import type { AgentFrameworkRunner, DeferredToolOutcome, ToolPolicy } from "./agent-framework-runner.js";
 import { type AgentSessionPersistence } from "./agent-session-persistence.js";
-import type { AgentMessagesPage, AgentSessionStartInput, AgentSnapshot, AgentUserMessage, ListAgentMessagesInput, ResolveInterruptInput, ToolEffect } from "./agent-session-values.js";
-/** Tool policies, live events, and approval deadline of one agent, passed to {@link createAgentSessionFlow}. */
+import type { ModelSpendLimit } from "./agent-session-spend-limit.js";
+import { type ResolvedRunModelLimit, type RunModelLimit } from "./agent-session-step-options.js";
+import { messageRolloverMaxBytesPerCommit, messageRolloverMaxChunksPerCommit } from "./agent-session-transitions.js";
+import type { AgentMessagesPage, AgentSessionStartInput, AgentSnapshot, AgentUserMessage, AnswerQuestionRequest, CancelTurnRequest, DeleteQueuedMessageRequest, ExecutePlanRequest, ListAgentMessagesInput, ResolveInterruptInput, SteerUserMessageRequest, ToolEffect, UpdateSessionSettingsRequest } from "./agent-session-values.js";
+import { type AgentTracingOptions, type ResolvedAgentTracingOptions } from "./agent-tracing-options.js";
+export declare const snapshotMessageLimit = 200;
+export declare const defaultMaxDurableWaitMs: number;
+export declare const messagePageLimit = 200;
+/** Default {@link AgentSessionOptions.messageWindowSize}. */
+export declare const defaultMessageWindowSize = 64;
+/** Default {@link AgentSessionOptions.messageChunkSize}. */
+export declare const defaultMessageChunkSize = 32;
+/** Default {@link AgentSessionOptions.messageChunkMaxBytes}: 1 MiB. */
+export declare const defaultMessageChunkMaxBytes = 1048576;
+/** Default {@link AgentSessionOptions.retainedMessageLimit}. */
+export declare const defaultRetainedMessageLimit = 1000;
+export { messageRolloverMaxBytesPerCommit, messageRolloverMaxChunksPerCommit };
+/**
+ * Tool policies, built-in tools, live events, interrupt deadline, tracing, and compaction of one agent,
+ * passed to {@link createAgentSessionFlow}.
+ */
 export interface AgentSessionOptions {
     /**
      * Policies by tool name. A policy overrides framework metadata and {@link defaultToolEffect}.
@@ -20,10 +41,91 @@ export interface AgentSessionOptions {
      */
     readonly eventStreamCapacityBytes?: number;
     /**
-     * Milliseconds an approval may stay pending before `AwaitToolApproval` rejects it with
-     * `"approval deadline passed"`. Defaults to no deadline: approvals wait indefinitely.
+     * Milliseconds an approval or a question may stay pending before the session rejects it with
+     * `"approval deadline passed"` or `"question deadline passed"`. Defaults to no deadline: interrupts wait
+     * indefinitely.
      */
     readonly interruptDeadlineMs?: number;
+    /**
+     * OpenTelemetry GenAI span options. Defaults to spans through the global tracer provider when
+     * `@opentelemetry/api` is installed, and nothing otherwise. See {@link AgentTracingOptions}.
+     */
+    readonly tracing?: AgentTracingOptions;
+    /**
+     * Built-in tools the session handles, such as `["ask_user", "durable_wait"]`. Defaults to none.
+     *
+     * The runner offers the enabled ones to its model from {@link builtInToolDefinitions}; see
+     * {@link BuiltInTool}. An enabled built-in name is reserved: a tool policy for it is refused here, and
+     * the session routes every call with that name to the built-in tool. Enable a built-in tool only after
+     * every Worker of the Flow type runs a release that supports it.
+     */
+    readonly builtInTools?: readonly BuiltInTool[];
+    /**
+     * Longest `durable_wait` in milliseconds; a longer `duration_seconds` fails the call at once.
+     * Defaults to 365 days. It must be a positive multiple of 1,000, because Dex Timers take whole seconds.
+     * The Python core's `max_durable_wait` is a `timedelta`; this option is the same limit in milliseconds.
+     */
+    readonly maxDurableWaitMs?: number;
+    /**
+     * Whether `send_user_message` accepts a message with `planMode`, which starts a `planning` turn that drafts
+     * a plan for `execute_plan`. A `draft` plan makes every new turn a `planning` turn until it runs. Defaults
+     * to `false`.
+     *
+     * It requires `write_todos` in {@link builtInTools} and a runner whose
+     * {@link AgentFrameworkRunner.supportsPlanMode} is `true`, such as the Stepwise runner.
+     */
+    readonly planModeEnabled?: boolean;
+    /**
+     * When to summarize earlier messages so the model input stays under the context window. Defaults to no
+     * compaction. It needs a runner that implements {@link AgentFrameworkRunner.estimateInputTokens},
+     * {@link AgentFrameworkRunner.selectCompactionCutoff}, and {@link AgentFrameworkRunner.summarizeContext}.
+     * The summarized messages stay stored until {@link retainedMessageLimit} deletes them. Enable it only after
+     * every Worker of the Flow type runs a release with the `CompactContext` Step. See {@link CompactionPolicy}.
+     */
+    readonly compaction?: CompactionPolicy;
+    /**
+     * Most messages the `AgentMessages` window holds. Defaults to 64. When an append takes the window past it,
+     * its oldest messages move into immutable `AgentMessageChunks` instances in the same commit, at most
+     * {@link messageRolloverMaxChunksPerCommit} chunks per commit. Every Step that stores messages loads the
+     * whole window, so it bounds that load. It must be at least {@link messageChunkSize}.
+     */
+    readonly messageWindowSize?: number;
+    /** Most messages one archive chunk holds. Defaults to 32. A change applies to the next chunk written. */
+    readonly messageChunkSize?: number;
+    /**
+     * Most bytes one archive chunk holds, measured on the JSON this core writes. Defaults to 1 MiB, between 1 and
+     * 8,388,608. A chunk closes at {@link messageChunkSize} messages or at this size, whichever comes first. A
+     * message whose chunk of one, the message plus 15 bytes, would pass it never enters the window: the Step that
+     * stores it writes it straight into its own chunk, so a message too large for the server's
+     * `values.maxValueBytes` fails that Step instead of a later rollover. Keep it well under that limit.
+     */
+    readonly messageChunkMaxBytes?: number;
+    /**
+     * Retention of summarized messages: the session deletes its oldest archive chunk once every message in it is
+     * at or before `ContextSummary.lastSequence` and at least this many stored messages come after the chunk.
+     * Defaults to 1,000. `null` keeps every message. It applies only with {@link compaction}, so Flow state stays
+     * bounded however long the session runs.
+     *
+     * The newest `retainedMessageLimit` messages and every message after the summary always stay. Deleted
+     * messages leave `list_agent_messages` and `get_agent_snapshot`, and each `list_agent_messages` page then
+     * carries `deletedBeforeSequence`. An application that keeps the full transcript copies new messages with
+     * `list_agent_messages` before more than `retainedMessageLimit` messages follow them.
+     */
+    readonly retainedMessageLimit?: number | null;
+    /**
+     * Method timeout and attempts of `RunModel`, for a runner whose `RunModel` takes longer than one model call, such as
+     * a harness. Defaults to 15 minutes and 3 attempts in 30 minutes. See {@link RunModelLimit}.
+     *
+     * @since 0.3.0
+     */
+    readonly runModelLimit?: RunModelLimit;
+    /**
+     * The application's spend limit, called before and after each model call of `RunModel` and `CompactContext`.
+     * Omit it to make no checks. See {@link ModelSpendLimit}.
+     *
+     * @since 0.3.0
+     */
+    readonly spendLimit?: ModelSpendLimit;
 }
 /** Options applied by an {@link AgentSessionFlow}, with every default filled in. */
 export interface ResolvedAgentSessionOptions {
@@ -33,17 +135,51 @@ export interface ResolvedAgentSessionOptions {
     readonly defaultToolEffect: ToolEffect;
     /** Byte budget of the `AgentEvents` Stream. */
     readonly eventStreamCapacityBytes: number;
-    /** Approval deadline in milliseconds, or `undefined` for none. */
+    /** Approval and question deadline in milliseconds, or `undefined` for none. */
     readonly interruptDeadlineMs: number | undefined;
+    /**
+     * Tracing options. A Flow always sets this field; it is optional so that 0.1.0 code that builds these
+     * options keeps compiling.
+     */
+    readonly tracing?: ResolvedAgentTracingOptions;
+    /**
+     * Enabled built-in tools, in {@link builtInToolDefinitions} order. A Flow always sets this field and
+     * the one below; they are optional so that 0.1.0 code that builds these options keeps compiling.
+     */
+    readonly builtInTools?: readonly BuiltInTool[];
+    /** Longest `durable_wait` in milliseconds. */
+    readonly maxDurableWaitMs?: number;
+    /** Whether plan mode is enabled. A Flow always sets it; it is optional for the same reason. */
+    readonly planModeEnabled?: boolean;
+    /** The compaction policy with its defaults, or `undefined` when the session never compacts. */
+    readonly compaction?: ResolvedCompactionPolicy;
+    /** Most messages the `AgentMessages` window holds. A Flow always sets it; optional for 0.1.0 code. */
+    readonly messageWindowSize?: number;
+    /** Most messages per archive chunk. A Flow always sets it; optional for 0.1.0 code. */
+    readonly messageChunkSize?: number;
+    /** Most bytes per archive chunk. A Flow always sets it; optional for 0.1.0 code. */
+    readonly messageChunkMaxBytes?: number;
+    /** The retention limit, or `null` to keep every message. A Flow always sets it; optional for 0.1.0 code. */
+    readonly retainedMessageLimit?: number | null;
+    /** The `RunModel` limit and its retry budget. A Flow always sets it; optional for 0.2.0 code. */
+    readonly runModelLimit?: ResolvedRunModelLimit;
+    /** The application's spend limit, or `undefined` for none. */
+    readonly spendLimit?: ModelSpendLimit;
 }
 /**
  * Durable agent session Flow: one Flow execution is one agent session, and its Flow ID is the session ID.
  *
  * Create one per agent with {@link createAgentSessionFlow}, register it in the process `Registry`, and
- * call its RPCs with `Client.invokeRPC`. The RPC names are `send_user_message`, `resolve_interrupt`,
- * `get_agent_snapshot`, and `list_agent_messages`, the same as the Python core. The session never
- * completes on its own: it waits for the next user message after every turn. Stop it with
- * `Client.stopFlow`.
+ * call its RPCs with `Client.invokeRPC`. The RPC names are `send_user_message`, `steer_user_message`,
+ * `delete_queued_message`, `cancel_turn`, `resolve_interrupt`, `answer_question`, `execute_plan`,
+ * `update_session_settings`, `get_agent_snapshot`, and `list_agent_messages`, the same as the Python core. The session never completes on its
+ * own: it waits for the next user message after every turn. Stop it with `Client.stopFlow`.
+ *
+ * `steer_user_message` ends the running turn at its next safe Step boundary. It never interrupts a model call or a
+ * tool call that has already started. `cancel_turn` aborts the running model call and every wait for a person, a
+ * Timer, or a remote task too, but a tool call Step that has started still runs to the end. The calls that have
+ * not started record `rejected` with a `cancellationReason`, an abandoned task records `outcome_unknown`, and
+ * `ApplyTurnControl` ends the turn. A steered turn is followed by a new turn with the steered messages.
  *
  * The Flow's persistence definitions are properties of the Flow; pass them to `Client.getAttributes`
  * or the Stream reads.
@@ -53,7 +189,7 @@ export interface ResolvedAgentSessionOptions {
  * const flow = createAgentSessionFlow(runner, "SupportAgent");
  * const registry = new Registry([flow]);
  * // ... start a Worker and a Client with this registry ...
- * await client.startFlow(flow, sessionId, { initialMessage: null });
+ * await startAgentSession(client, flow, sessionId);
  * await client.invokeRPC(flow.sendUserMessage, sessionId, { text: "Where is order 42?" });
  * const snapshot = await client.invokeRPC(flow.getAgentSnapshot, sessionId);
  * for (const interrupt of snapshot.pendingInterrupts) {
@@ -61,10 +197,11 @@ export interface ResolvedAgentSessionOptions {
  *     interruptId: interrupt.interruptId, approved: true, rejectionMessage: null });
  * }
  * ```
+ * @typeParam Runner - Type of {@link runner}. It defaults to {@link AgentFrameworkRunner}.
  */
-export interface AgentSessionFlow extends Flow<AgentSessionStartInput>, AgentSessionPersistence {
+export interface AgentSessionFlow<Runner extends AgentFrameworkRunner<DeferredToolOutcome> = AgentFrameworkRunner> extends Flow<AgentSessionStartInput>, AgentSessionPersistence {
     /** The framework runner passed to {@link createAgentSessionFlow}. */
-    readonly runner: AgentFrameworkRunner;
+    readonly runner: Runner;
     /** The options this Flow applies, with defaults filled in. */
     readonly options: ResolvedAgentSessionOptions;
     /**
@@ -75,45 +212,191 @@ export interface AgentSessionFlow extends Flow<AgentSessionStartInput>, AgentSes
      *
      * @param context - RPC Context supplied by Dex.
      * @param message - Message to queue.
-     * @returns `true` when queued; `false` when the text is blank.
+     * @returns `true` when queued; `false` when the text is blank, or for a `planMode` message when
+     * {@link AgentSessionOptions.planModeEnabled} is not set.
      */
     sendUserMessage(context: Context, message: AgentUserMessage): RPCResult<boolean>;
     /**
-     * RPC `resolve_interrupt`: approves or rejects one pending interrupt.
+     * RPC `execute_plan`: approves one plan revision, so the session starts a turn that runs it.
+     *
+     * Call it after the user reviewed the `draft` plan that a `planMode` message drafted, or to run an `active`
+     * plan again. The next `AwaitUserMessage` starts an `executing` turn with every tool, whose user message is
+     * `[Dex] The user approved plan revision <n>. Execute it and keep the task statuses current with
+     * write_todos.`. A queued message that the session took first runs its turn first; when that turn changes
+     * the plan, the approval is stale and never runs.
+     *
+     * The RPC records the approval in `PendingPlanExecution` until the session starts the turn, so a revision
+     * runs once per approval. It locks `PendingPlanExecution`: a concurrent `execute_plan` can make it fail with
+     * `RpcLockConflictError`, which is safe to retry.
+     *
+     * @example
+     * ```ts
+     * const snapshot = await client.invokeRPC(flow.getAgentSnapshot, sessionId);
+     * if (snapshot.plan?.status === "draft") {
+     *   await client.invokeRPC(flow.executePlan, sessionId, { revision: snapshot.plan.revision });
+     * }
+     * ```
+     * @param context - RPC Context supplied by Dex.
+     * @param input - The plan revision the user reviewed.
+     * @returns `true` when the execution is accepted; `false` unless the session waits for a user message, the
+     * plan has this revision and is `draft` or `active`, no execution of it is pending, and no queued or steered
+     * message or interrupt is pending.
+     */
+    executePlan(context: Context, input: ExecutePlanRequest): RPCResult<boolean>;
+    /**
+     * RPC `steer_user_message`: steers the running turn with new text or with a queued message.
+     *
+     * A steered message applies at the turn's next safe Step boundary. The session never interrupts a model call or
+     * a tool call that has started. It records the calls that have not started as `rejected` with
+     * `cancellationReason` `"steered"`, ends the turn, and starts a new turn whose user messages are every steered
+     * message, in order.
+     *
+     * While no turn is active, there is nothing to steer: new `text` is queued like `send_user_message`, so it
+     * starts the next turn at once, and a `messageId` that is still queued stays queued. A turn that a Worker
+     * without steering started or advanced cannot be steered; see {@link AgentState.acceptsTurnControl}.
+     *
+     * With `messageId`, the RPC moves that queued message: it deletes it from `QueuedUserMessages` and publishes it
+     * to `SteeredUserMessages` in one commit. It locks nothing. When another Step or RPC consumes the message
+     * between the RPC's read and its commit, the RPC fails with `ChannelMessageNotFoundError` and commits nothing;
+     * reload the snapshot and let the user choose again.
+     *
+     * @example
+     * ```ts
+     * const [queued] = (await client.invokeRPC(flow.getAgentSnapshot, sessionId)).queuedMessages ?? [];
+     * if (queued !== undefined) {
+     *   await client.invokeRPC(flow.steerUserMessage, sessionId, { messageId: queued.messageId, text: null });
+     * }
+     * ```
+     * @param context - RPC Context supplied by Dex.
+     * @param input - Exactly one of a queued message ID and new text.
+     * @returns `true` when the message is steered, or queued while no turn is active; `false` when both or neither
+     * field is set, the text is blank, the message is no longer queued, or the active turn does not accept steering.
+     */
+    steerUserMessage(context: Context, input: SteerUserMessageRequest): RPCResult<boolean>;
+    /**
+     * RPC `delete_queued_message`: deletes one queued user message before it starts a turn.
+     *
+     * It locks nothing. When the session consumes the message between the RPC's read and its commit, the RPC fails
+     * with `ChannelMessageNotFoundError` and commits nothing.
+     *
+     * @param context - RPC Context supplied by Dex.
+     * @param input - {@link PendingUserMessage.messageId} from `get_agent_snapshot`.
+     * @returns `true` when the message was deleted; `false` when it is no longer queued.
+     */
+    deleteQueuedMessage(context: Context, input: DeleteQueuedMessageRequest): RPCResult<boolean>;
+    /**
+     * RPC `cancel_turn`: stops the running turn now, with no new turn.
+     *
+     * The RPC cancels the turn's running model call or compaction, and every Step that waits for an approval, an
+     * answer, a `durable_wait` Timer, or a remote task's next poll. A cancelled model call's `cancellationSignal`
+     * aborts at once and its answer is dropped. A tool call Step that has started runs to the end, and the turn ends
+     * after it. The calls that have not started record `rejected` with `cancellationReason` `"turn_cancelled"`. A
+     * started remote task is abandoned: the call records `outcome_unknown`, and a runner that implements
+     * {@link AgentFrameworkRunner.cancelToolTask} is asked to cancel the task. Then the session waits for the next
+     * user message.
+     *
+     * The RPC locks `TurnCancellationRequest` and `PendingInterrupts`. No long-running Step locks them, so it never
+     * waits for a model call. It can fail with `RpcLockConflictError` while a short Step holds a lock, which is safe
+     * to retry. A second call for the same turn changes nothing and returns `true`.
+     *
+     * @param context - RPC Context supplied by Dex.
+     * @param input - The turn to stop, or `turnId` `null` for the active turn.
+     * @returns `true` when the request is recorded, although a turn whose model call already committed its final
+     * answer completes instead; `false` when no turn is active, `turnId` names another turn, or the active turn does
+     * not accept cancellation.
+     */
+    cancelTurn(context: Context, input: CancelTurnRequest): RPCResult<boolean>;
+    /**
+     * RPC `update_session_settings`: replaces the session's settings from the next turn on.
+     *
+     * The new settings apply when the next turn starts, the same boundary at which a `planMode` message takes
+     * effect. A running turn keeps the settings it started with for every model call, retry, and compaction, so one
+     * turn never mixes two models. The settings replace the old ones; nothing is merged, and `{}` clears them, so
+     * `get_agent_snapshot` returns `null`.
+     *
+     * Settings are stored in the session and returned by `get_agent_snapshot`, and the browser snapshot JSON of
+     * `@superdurable/dex-agents/ui-stream` includes them. Never put a secret or anything a browser must not see in
+     * them; put a reference, such as a credential name, that the Worker resolves. Call the RPC only after every
+     * Worker of the Flow type runs dex-agents 0.2.0.
+     *
+     * The RPC locks nothing. When two updates race, the one that commits last wins. A turn that starts between
+     * this RPC's read and its commit runs with the earlier settings, and the next turn gets these.
+     *
+     * @example
+     * ```ts
+     * await client.invokeRPC(flow.updateSessionSettings, sessionId, { sessionSettings: { model: "gpt-5" } });
+     * ```
+     * @param context - RPC Context supplied by Dex.
+     * @param input - The complete new settings.
+     * @returns `true` when the settings are stored; `false` before `StartAgentSession` committed, or when the
+     * settings are `null` (a missing or `null` field), are not a JSON object, or are larger than
+     * `MAX_SESSION_SETTINGS_BYTES` plus `SESSION_SETTINGS_SIZE_TOLERANCE_BYTES`.
+     */
+    updateSessionSettings(context: Context, input: UpdateSessionSettingsRequest): RPCResult<boolean>;
+    /**
+     * RPC `resolve_interrupt`: approves or rejects one pending tool approval, or declines one question.
      *
      * It removes the interrupt from `PendingInterrupts` and publishes the answer in one commit, so only
      * one call succeeds per interrupt. It locks `PendingInterrupts`, so a call that races
-     * `AwaitToolApproval` can fail with `RpcLockConflictError`, which is safe to retry. The
-     * rejection message is dropped when `approved` is `true`.
+     * `AwaitToolApproval`, `AwaitQuestionAnswer`, `ResumeTurn`, `FinishTurnCancellation`, or `cancel_turn` can fail
+     * with `RpcLockConflictError`, which is safe to retry. The caller sends the RPC's locks: SDK clients and Dex Web do,
+     * but a raw `InvokeRPC` request without them runs unlocked, and then more than one call can succeed. The rejection message is dropped when `approved` is `true`. A question needs an answer, so
+     * `approved` `true` on a `question` interrupt is refused; answer it with {@link answerQuestion}.
      *
      * @param context - RPC Context supplied by Dex.
      * @param input - Interrupt ID and decision.
      * @returns `true` when the interrupt was pending and is now resolved; `false` when it is unknown,
-     * already resolved, or past its deadline.
+     * already resolved, past its deadline, or a question with `approved` `true`.
      */
     resolveInterrupt(context: Context, input: ResolveInterruptInput): RPCResult<boolean>;
+    /**
+     * RPC `answer_question`: answers one pending `question` interrupt.
+     *
+     * The answer becomes the result of the `ask_user` call, `{"status":"answered","answer":"<text>"}`, so
+     * the model continues the same turn. For a tool's question, the tool runs again with the answer. The
+     * RPC removes the interrupt and publishes the answer in one commit, so only one call succeeds per
+     * question. It locks `PendingInterrupts` and can fail with `RpcLockConflictError`, which is safe to
+     * retry. Decline a question with {@link resolveInterrupt} and `approved` `false`.
+     *
+     * @example
+     * ```ts
+     * const snapshot = await client.invokeRPC(flow.getAgentSnapshot, sessionId);
+     * const question = snapshot.pendingInterrupts.find((interrupt) => interrupt.kind === "question");
+     * if (question !== undefined) {
+     *   await client.invokeRPC(flow.answerQuestion, sessionId, { interruptId: question.interruptId, answer: "blue" });
+     * }
+     * ```
+     * @param context - RPC Context supplied by Dex.
+     * @param input - Interrupt ID and answer.
+     * @returns `true` when the question was pending and is now answered; `false` when the interrupt is
+     * not pending, is not a question, or is past its deadline, and when the answer is blank or is not one
+     * of the choices while free text is not allowed.
+     */
+    answerQuestion(context: Context, input: AnswerQuestionRequest): RPCResult<boolean>;
     /**
      * RPC `get_agent_snapshot`: returns the durable session view a UI renders.
      *
      * It reads committed state without locks, so it also serves a retained closed session. It loads the
-     * whole `AgentMessages` map.
+     * `AgentMessages` window and every retained `AgentMessageChunks` instance.
      *
      * @param context - RPC Context supplied by Dex.
-     * @returns State, the last 200 messages, pending interrupts, the active turn's tool calls, usage,
-     * and the queued message count. Before `StartAgentSession` commits, `state` is `null` and the lists
-     * are empty.
+     * @returns State, the last 200 messages, pending interrupts, the active turn's tool calls, usage, the queued
+     * message count, the plan, the queued and steered messages with their Channel message IDs, and the context
+     * summary; summarized messages stay in `messages` until retention deletes them. Before `StartAgentSession` commits, `state` is `null` and
+     * the lists are empty.
      */
     getAgentSnapshot(context: Context): RPCResult<AgentSnapshot>;
     /**
      * RPC `list_agent_messages`: returns one page of stored messages, oldest first.
      *
      * Start with `beforeSequence` `null` for the newest page, then pass each page's
-     * `nextBeforeSequence` to walk back. It also serves a retained closed session.
+     * `nextBeforeSequence` to walk back. It also serves a retained closed session. Messages that retention
+     * deleted are gone: the oldest page starts at the oldest stored message.
      *
      * @param context - RPC Context supplied by Dex.
      * @param input - Exclusive upper sequence bound, or `null`, and a page size clamped to 1..200.
      * @returns Up to `limit` messages below `beforeSequence` in ascending order, and the bound of the
-     * next older page, or `null` when the page starts at the first message.
+     * next older page, or `null` when the page starts at the oldest stored message.
      */
     listAgentMessages(context: Context, input: ListAgentMessagesInput): RPCResult<AgentMessagesPage>;
 }
@@ -137,12 +420,18 @@ export interface AgentSessionFlow extends Flow<AgentSessionStartInput>, AgentSes
  * const billing = createAgentSessionFlow(billingRunner, "BillingAgent");
  * const registry = new Registry([triage, billing]);
  * ```
+ * @typeParam Runner - Type of the runner, kept as the Flow's `runner` property type.
  * @param runner - Framework runner; the Flow owns no other dependency.
  * @param flowType - Flow type, unique within the Registry, such as `"TriageAgent"`. Keep it stable:
  * running sessions resume by it.
- * @param options - Tool policies, Stream capacity, and approval deadline. Defaults to all defaults.
+ * @param options - Tool policies, Stream capacity, approval deadline, and tracing. Defaults to all
+ * defaults.
  * @returns A new Flow to register in one Registry.
- * @throws {TypeError} When `flowType` is blank, the runner is incomplete, or an effect is unknown.
- * @throws {RangeError} When `eventStreamCapacityBytes` or `interruptDeadlineMs` is not positive.
+ * @throws {TypeError} When `flowType` is blank, the runner is incomplete, an effect or built-in tool is
+ * unknown, a tool policy names an enabled built-in tool, a tracing option is invalid, `planModeEnabled`
+ * is set without `write_todos` or for a runner without {@link AgentFrameworkRunner.supportsPlanMode}, or
+ * `compaction` is set for a runner without the compaction methods.
+ * @throws {RangeError} When `eventStreamCapacityBytes` or `interruptDeadlineMs` is not positive,
+ * `maxDurableWaitMs` is not a positive whole number of seconds, or the compaction policy is out of range.
  */
-export declare function createAgentSessionFlow(runner: AgentFrameworkRunner, flowType: string, options?: AgentSessionOptions): AgentSessionFlow;
+export declare function createAgentSessionFlow<Runner extends AgentFrameworkRunner<DeferredToolOutcome>>(runner: Runner, flowType: string, options?: AgentSessionOptions): AgentSessionFlow<Runner>;