@superdurable/dex-agents 0.0.0-stage → 0.2.0

package/dist/src/testing/step-history.d.ts

@@ -0,0 +1,40 @@
+/** History event type of a completed `waitFor` method. */
+export declare const waitForCompletedEvent = "StepWaitForCompleted";
+/** History event type of a completed `execute` method. */
+export declare const executeCompletedEvent = "StepExecuteCompleted";
+/** One completed Step method in a Flow's history, returned by {@link readStepHistory}. */
+export interface StepHistoryEntry {
+    /** {@link waitForCompletedEvent} or {@link executeCompletedEvent}. */
+    readonly eventType: string;
+    /** Step type, such as `"RunModel"`. */
+    readonly stepType: string;
+    /** Step execution ID, such as `"RunModel-2"`. */
+    readonly stepExecutionId: string;
+    /** One-based attempt that completed the method. */
+    readonly finalAttempt: number;
+}
+/** Options of {@link readStepHistory}. */
+export interface ReadStepHistoryOptions {
+    /** Path to `dexcli`. Defaults to the `DEXCLI` environment variable, then `dexcli` on `PATH`. */
+    readonly dexcliPath?: string;
+}
+/**
+ * Returns every completed Step method of a Flow's current run, in history order.
+ *
+ * It runs `dexcli flow history --all --output json`, as the Python core's `read_step_history` does. Use
+ * it to assert the Step shape of a turn, such as `RunModel`, `CallTool`, `ResumeTurn`, `RunModel`.
+ * Steps that are still waiting or running are not included.
+ *
+ * @example
+ * ```ts
+ * const executed = (await readStepHistory(engine.serverAddress, sessionId))
+ *   .filter((entry) => entry.eventType === executeCompletedEvent)
+ *   .map((entry) => entry.stepType);
+ * ```
+ * @param serverAddress - Dex Server address.
+ * @param flowId - Flow ID to read.
+ * @param options - `dexcli` path.
+ * @returns One entry per completed `waitFor` or `execute` method.
+ * @throws {Error} When `dexcli` fails or prints unexpected JSON.
+ */
+export declare function readStepHistory(serverAddress: string, flowId: string, options?: ReadStepHistoryOptions): Promise<StepHistoryEntry[]>;

package/dist/src/testing/step-history.js

@@ -0,0 +1,59 @@
+// 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 { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** History event type of a completed `waitFor` method. */
+export const waitForCompletedEvent = "StepWaitForCompleted";
+/** History event type of a completed `execute` method. */
+export const executeCompletedEvent = "StepExecuteCompleted";
+/**
+ * Returns every completed Step method of a Flow's current run, in history order.
+ *
+ * It runs `dexcli flow history --all --output json`, as the Python core's `read_step_history` does. Use
+ * it to assert the Step shape of a turn, such as `RunModel`, `CallTool`, `ResumeTurn`, `RunModel`.
+ * Steps that are still waiting or running are not included.
+ *
+ * @example
+ * ```ts
+ * const executed = (await readStepHistory(engine.serverAddress, sessionId))
+ *   .filter((entry) => entry.eventType === executeCompletedEvent)
+ *   .map((entry) => entry.stepType);
+ * ```
+ * @param serverAddress - Dex Server address.
+ * @param flowId - Flow ID to read.
+ * @param options - `dexcli` path.
+ * @returns One entry per completed `waitFor` or `execute` method.
+ * @throws {Error} When `dexcli` fails or prints unexpected JSON.
+ */
+export async function readStepHistory(serverAddress, flowId, options = {}) {
+    const dexcliPath = options.dexcliPath ?? process.env.DEXCLI ?? "dexcli";
+    const { stdout } = await execFileAsync(dexcliPath, ["flow", "history", flowId, "--server", serverAddress, "--all", "--output", "json"], { maxBuffer: 64 * 1024 * 1024 });
+    const history = JSON.parse(stdout);
+    if (!Array.isArray(history.events)) {
+        throw new Error(`dexcli flow history printed no events for ${flowId}`);
+    }
+    const entries = [];
+    for (const event of history.events) {
+        if (event.type !== waitForCompletedEvent && event.type !== executeCompletedEvent) {
+            continue;
+        }
+        const stepContext = event.payload?.context;
+        if (stepContext === undefined) {
+            throw new Error(`history event ${event.type} of ${flowId} has no Step context`);
+        }
+        entries.push({
+            eventType: event.type,
+            stepType: String(stepContext.stepType),
+            stepExecutionId: String(stepContext.stepExecutionId),
+            finalAttempt: Number(stepContext.finalAttempt),
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=step-history.js.map

package/dist/src/testing/step-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-history.js","sourceRoot":"","sources":["../../../src/testing/step-history.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAC5D,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAoB5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,aAAqB,EACrB,MAAc,EACd,UAAkC,EAAE;IAEpC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,QAAQ,CAAC;IACxE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CACpC,UAAU,EACV,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,EACnF,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAChC,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAyB,CAAC;IAC3D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,6CAA6C,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAsD,EAAE,CAAC;QACnF,IAAI,KAAK,CAAC,IAAI,KAAK,qBAAqB,IAAI,KAAK,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACjF,SAAS;QACX,CAAC;QACD,MAAM,WAAW,GAAI,KAAK,CAAC,OAA6D,EAAE,OAAO,CAAC;QAClG,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,CAAC,IAAI,OAAO,MAAM,sBAAsB,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,SAAS,EAAE,KAAK,CAAC,IAAI;YACrB,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC;YACtC,eAAe,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe,CAAC;YACpD,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC;SAC/C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/ui-stream/agent-event-json.d.ts

@@ -0,0 +1,30 @@
+import type { AgentEvent, AgentSnapshot } from "../agent-session-values.js";
+import type { AgentEventJson } from "./agent-ui-message-types.js";
+/**
+ * Converts an `AgentEvent` to its snake_case wire JSON, the format of the plain Server-Sent Events stream.
+ *
+ * @example
+ * ```ts
+ * const message = await client.readStream(sessionId, flow.agentEvents, resumeToken);
+ * response.write(`data: ${JSON.stringify(convertAgentEventToJson(message.value))}\n\n`);
+ * ```
+ * @param event - Event read from the `AgentEvents` Stream.
+ * @returns A new object with `type`, `turn_id`, `attempt`, `step_execution_id`, and `payload` text.
+ */
+export declare function convertAgentEventToJson(event: AgentEvent): AgentEventJson;
+/**
+ * Converts an `AgentSnapshot` to the snake_case JSON a browser reads, the same JSON the Python core produces.
+ *
+ * Use it when a browser shared with Python backends reads the snapshot. It is the `get_agent_snapshot` wire
+ * format without the fields only the session's Steps use. Messages leave out `framework_item`, the
+ * framework's replay data, which can hold the agent's instructions. Tool calls leave out
+ * `tool_source_reference`, `trace_context`, `input_continuation`, `input_answers`, and `task_answer_pending`.
+ *
+ * `session_settings` is included as stored, so the browser sees the settings the next turn starts with. Keep
+ * anything a browser must not see out of session settings, or remove the key before serving the JSON.
+ *
+ * @param snapshot - Output of the `get_agent_snapshot` RPC.
+ * @returns A new JSON object with `state`, `messages`, `pending_interrupts`, `tool_calls`, `usage`, and
+ * `queued_message_count`.
+ */
+export declare function convertAgentSnapshotToJson(snapshot: AgentSnapshot): Readonly<Record<string, unknown>>;

package/dist/src/ui-stream/agent-event-json.js

@@ -0,0 +1,64 @@
+// 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 { encodeAgentSnapshot } from "../agent-session-codecs.js";
+/**
+ * Converts an `AgentEvent` to its snake_case wire JSON, the format of the plain Server-Sent Events stream.
+ *
+ * @example
+ * ```ts
+ * const message = await client.readStream(sessionId, flow.agentEvents, resumeToken);
+ * response.write(`data: ${JSON.stringify(convertAgentEventToJson(message.value))}\n\n`);
+ * ```
+ * @param event - Event read from the `AgentEvents` Stream.
+ * @returns A new object with `type`, `turn_id`, `attempt`, `step_execution_id`, and `payload` text.
+ */
+export function convertAgentEventToJson(event) {
+    return {
+        type: event.type,
+        turn_id: event.turnId,
+        attempt: event.attempt,
+        step_execution_id: event.stepExecutionId,
+        payload: event.payload,
+    };
+}
+// Replay, routing, tracing, and tool resume state that only the session's Steps read.
+const workerOnlyMessageFieldNames = new Set(["framework_item"]);
+const workerOnlyToolCallFieldNames = new Set([
+    "tool_source_reference",
+    "trace_context",
+    "input_continuation",
+    "input_answers",
+    "task_answer_pending",
+]);
+/**
+ * Converts an `AgentSnapshot` to the snake_case JSON a browser reads, the same JSON the Python core produces.
+ *
+ * Use it when a browser shared with Python backends reads the snapshot. It is the `get_agent_snapshot` wire
+ * format without the fields only the session's Steps use. Messages leave out `framework_item`, the
+ * framework's replay data, which can hold the agent's instructions. Tool calls leave out
+ * `tool_source_reference`, `trace_context`, `input_continuation`, `input_answers`, and `task_answer_pending`.
+ *
+ * `session_settings` is included as stored, so the browser sees the settings the next turn starts with. Keep
+ * anything a browser must not see out of session settings, or remove the key before serving the JSON.
+ *
+ * @param snapshot - Output of the `get_agent_snapshot` RPC.
+ * @returns A new JSON object with `state`, `messages`, `pending_interrupts`, `tool_calls`, `usage`, and
+ * `queued_message_count`.
+ */
+export function convertAgentSnapshotToJson(snapshot) {
+    const snapshotJson = encodeAgentSnapshot(snapshot);
+    return {
+        ...snapshotJson,
+        messages: snapshotJson["messages"].map((message) => omitJsonFields(message, workerOnlyMessageFieldNames)),
+        tool_calls: snapshotJson["tool_calls"].map((toolCall) => omitJsonFields(toolCall, workerOnlyToolCallFieldNames)),
+    };
+}
+function omitJsonFields(value, fieldNames) {
+    return Object.fromEntries(Object.entries(value).filter(([fieldName]) => !fieldNames.has(fieldName)));
+}
+//# sourceMappingURL=agent-event-json.js.map

package/dist/src/ui-stream/agent-event-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event-json.js","sourceRoot":"","sources":["../../../src/ui-stream/agent-event-json.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAIjE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAiB;IACvD,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO,EAAE,KAAK,CAAC,MAAM;QACrB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,iBAAiB,EAAE,KAAK,CAAC,eAAe;QACxC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,2BAA2B,GAAwB,IAAI,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC;AACrF,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC;IAChE,uBAAuB;IACvB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,qBAAqB;CACtB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAuB;IAChE,MAAM,YAAY,GAAG,mBAAmB,CAAC,QAAQ,CAA4B,CAAC;IAC9E,OAAO;QACL,GAAG,YAAY;QACf,QAAQ,EAAG,YAAY,CAAC,UAAU,CAA+B,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAChF,cAAc,CAAC,OAAO,EAAE,2BAA2B,CAAC,CACrD;QACD,UAAU,EAAG,YAAY,CAAC,YAAY,CAA+B,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CACrF,cAAc,CAAC,QAAQ,EAAE,4BAA4B,CAAC,CACvD;KACF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,KAA8B,EAC9B,UAA+B;IAE/B,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AACvG,CAAC"}

package/dist/src/ui-stream/agent-event-sse.d.ts

@@ -0,0 +1,154 @@
+import type { Client, StreamMessage } from "@superdurable/dex";
+import type { AgentFrameworkRunner, DeferredToolOutcome } from "../agent-framework-runner.js";
+import type { AgentSessionFlow } from "../agent-session-flow.js";
+import type { AgentEvent, AgentSnapshot } from "../agent-session-values.js";
+/** HTTP headers of the plain `AgentEvents` Server-Sent Events response. */
+export declare const agentEventStreamHeaders: Readonly<Record<string, string>>;
+/**
+ * Selects the agent session and Stream position of a plain `AgentEvents` Server-Sent Events stream.
+ *
+ * Pass it to {@link streamAgentEventSseFrames} or {@link createAgentEventSseResponse}.
+ */
+export interface AgentEventSseOptions {
+    /** Client used for every Stream read. The caller keeps ownership. */
+    readonly client: Client;
+    /** The agent session Flow, the same object the Worker registered. */
+    readonly flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>;
+    /** Session ID: the Flow ID of the agent session. */
+    readonly flowId: string;
+    /**
+     * Dex resume token of the last event the browser received: the `Last-Event-ID` request header, or the
+     * `resumeToken` of {@link readAgentEventStreamSnapshot} on the first connection. Omit it, or pass `""`,
+     * to start at the oldest retained event.
+     */
+    readonly resumeToken?: string | undefined;
+    /**
+     * Long-poll duration of one Stream read, in milliseconds. It must be a whole number of seconds. The
+     * stream sends a keep-alive comment after each empty poll. Defaults to 10,000.
+     */
+    readonly pollTimeoutMs?: number;
+    /** Ends the stream before its next Stream read once aborted, such as the request's `signal`. */
+    readonly signal?: AbortSignal | undefined;
+}
+/** A session snapshot and the Dex resume token that a plain event stream opened with it starts from. */
+export interface AgentEventStreamSnapshot {
+    /** Output of the `get_agent_snapshot` RPC. */
+    readonly snapshot: AgentSnapshot;
+    /**
+     * Dex resume token to open the event stream with. While a turn is active it replays that turn's events
+     * from its first retained event; otherwise it starts after the newest event read before the snapshot.
+     */
+    readonly resumeToken: string;
+}
+/** Snake_case wire JSON of an {@link AgentEventStreamSnapshot}, the same JSON as the Python core. */
+export interface AgentEventStreamSnapshotJson {
+    /** The `AgentSnapshot` wire JSON. */
+    readonly snapshot: Readonly<Record<string, unknown>>;
+    /** Dex resume token to open the event stream with. */
+    readonly resume_token: string;
+}
+/**
+ * Formats one `AgentEvents` message as a Server-Sent Event whose `id` is its Dex resume token.
+ *
+ * An `EventSource` sends the `id` back as the `Last-Event-ID` header when it reconnects. The event has no
+ * `event:` field, so `EventSource.onmessage` receives every event; switch on `type` in the data.
+ *
+ * @param message - Message read from the `AgentEvents` Stream.
+ * @returns `id: <resume token>`, then `data: <AgentEvent wire JSON>`, then a blank line.
+ */
+export declare function formatAgentEventSseFrame(message: StreamMessage<AgentEvent>): string;
+/**
+ * Yields an agent session's `AgentEvents` as Server-Sent Event frames, resuming after a Dex resume token.
+ *
+ * Each event becomes one frame whose `id` is its Dex resume token and whose data is the `AgentEvent` wire
+ * JSON: `type`, `turn_id`, `attempt`, `step_execution_id`, and `payload` text. Reconnecting with the last
+ * `id` continues with the next event, with no repeated or missing event while the Stream retains them.
+ * After each empty long poll it yields a keep-alive comment. The stream never ends on its own; stop
+ * iterating, or abort `signal`, when the browser goes away.
+ *
+ * The browser applies the event rules of the session contract. Within one `step_execution_id` it keeps
+ * only the highest `attempt` and drops the partial text of lower attempts. After `turn_completed`,
+ * `turn_failed`, `turn_steered`, or `turn_cancelled` it replaces the turn's live text with the stored
+ * messages. On every connection, load
+ * {@link readAgentEventStreamSnapshot} first and open the stream from its `resumeToken`.
+ *
+ * @example
+ * ```ts
+ * for await (const frame of streamAgentEventSseFrames({
+ *   client, flow, flowId: sessionId, resumeToken: request.headers["last-event-id"] })) {
+ *   response.write(frame);
+ * }
+ * ```
+ * @param options - Session, start position, and polling.
+ * @returns An async generator of SSE frames and keep-alive comments.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {DexServiceError} When a Stream read fails.
+ */
+export declare function streamAgentEventSseFrames(options: AgentEventSseOptions): AsyncGenerator<string, void, undefined>;
+/**
+ * Returns a streaming `text/event-stream` Response of an agent session's `AgentEvents`.
+ *
+ * It writes {@link streamAgentEventSseFrames} and stops reading when the browser closes the response.
+ * Mount it in any server that returns a Fetch API `Response`. The session ID usually comes from the
+ * browser, so the route must check that the caller may read that session.
+ *
+ * Before it answers 200, it reads once, with a long poll of up to 1 second, to check the resume token.
+ * When Dex rejects the token, such as one of another session, it answers 400, which stops an
+ * `EventSource` from reconnecting with it; the browser then loads the snapshot again. A token from
+ * before a Stream Store restart is accepted and continues at the oldest retained event.
+ *
+ * @example
+ * ```ts
+ * // GET /sessions/:id/events
+ * export async function GET(request: Request, sessionId: string): Promise<Response> {
+ *   const url = new URL(request.url);
+ *   return createAgentEventSseResponse({
+ *     client, flow, flowId: sessionId,
+ *     resumeToken: request.headers.get("last-event-id") ?? url.searchParams.get("resumeToken") ?? "",
+ *     signal: request.signal,
+ *   });
+ * }
+ * // In the browser:
+ * const { resumeToken } = await (await fetch(`/sessions/${sessionId}/snapshot`)).json();
+ * const events = new EventSource(`/sessions/${sessionId}/events?resumeToken=${encodeURIComponent(resumeToken)}`);
+ * events.onmessage = (message) => render(JSON.parse(message.data));
+ * ```
+ * @param options - Session, start position, polling, and extra response headers.
+ * @returns A 200 Response with {@link agentEventStreamHeaders} and the application's `headers`; 400 with
+ * a text body when Dex rejects the resume token.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {DexServiceError} When the first Stream read fails for another reason.
+ */
+export declare function createAgentEventSseResponse(options: AgentEventSseOptions & {
+    readonly headers?: Readonly<Record<string, string>>;
+}): Promise<Response>;
+/**
+ * Reads the session snapshot together with the Dex resume token to open the plain event stream from.
+ *
+ * Call it whenever the browser connects or reconnects after a gap. It reads the newest event first and
+ * the snapshot second, so events after the token may repeat what the snapshot shows but none is missing.
+ * While a turn is active the token replays that turn's events, so the browser can rebuild its live text.
+ * The `get_agent_snapshot` RPC needs a running Worker.
+ *
+ * @example
+ * ```ts
+ * // GET /sessions/:id/snapshot
+ * const value = await readAgentEventStreamSnapshot({ client, flow, flowId: sessionId });
+ * return Response.json(convertAgentEventStreamSnapshotToJson(value));
+ * ```
+ * @param options - Client, Flow, and session ID.
+ * @returns The snapshot and the resume token.
+ * @throws {DexServiceError} When the Stream read or the RPC fails.
+ */
+export declare function readAgentEventStreamSnapshot(options: {
+    readonly client: Client;
+    readonly flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>;
+    readonly flowId: string;
+}): Promise<AgentEventStreamSnapshot>;
+/**
+ * Converts an {@link AgentEventStreamSnapshot} to snake_case wire JSON for an HTTP response.
+ *
+ * @param value - Snapshot and resume token.
+ * @returns `{ snapshot, resume_token }`, with the snapshot in its `AgentSnapshot` wire format.
+ */
+export declare function convertAgentEventStreamSnapshotToJson(value: AgentEventStreamSnapshot): AgentEventStreamSnapshotJson;

package/dist/src/ui-stream/agent-event-sse.js

@@ -0,0 +1,159 @@
+// 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 { convertAgentEventToJson, convertAgentSnapshotToJson } from "./agent-event-json.js";
+import { findAgentEventResumeTokenBeforeTurn, probeAgentEventResumeToken, readAgentEventsTailResumeToken, readNextAgentEvent, requireAgentEventPollTimeoutMs, } from "./agent-event-stream-positions.js";
+import { createServerSentEventResponse, mergeHeaders, serverSentEventKeepAliveFrame, } from "./server-sent-event-responses.js";
+/** HTTP headers of the plain `AgentEvents` Server-Sent Events response. */
+export const agentEventStreamHeaders = Object.freeze({
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+    "x-accel-buffering": "no",
+});
+/**
+ * Formats one `AgentEvents` message as a Server-Sent Event whose `id` is its Dex resume token.
+ *
+ * An `EventSource` sends the `id` back as the `Last-Event-ID` header when it reconnects. The event has no
+ * `event:` field, so `EventSource.onmessage` receives every event; switch on `type` in the data.
+ *
+ * @param message - Message read from the `AgentEvents` Stream.
+ * @returns `id: <resume token>`, then `data: <AgentEvent wire JSON>`, then a blank line.
+ */
+export function formatAgentEventSseFrame(message) {
+    return `id: ${message.resumeToken}\ndata: ${JSON.stringify(convertAgentEventToJson(message.value))}\n\n`;
+}
+/**
+ * Yields an agent session's `AgentEvents` as Server-Sent Event frames, resuming after a Dex resume token.
+ *
+ * Each event becomes one frame whose `id` is its Dex resume token and whose data is the `AgentEvent` wire
+ * JSON: `type`, `turn_id`, `attempt`, `step_execution_id`, and `payload` text. Reconnecting with the last
+ * `id` continues with the next event, with no repeated or missing event while the Stream retains them.
+ * After each empty long poll it yields a keep-alive comment. The stream never ends on its own; stop
+ * iterating, or abort `signal`, when the browser goes away.
+ *
+ * The browser applies the event rules of the session contract. Within one `step_execution_id` it keeps
+ * only the highest `attempt` and drops the partial text of lower attempts. After `turn_completed`,
+ * `turn_failed`, `turn_steered`, or `turn_cancelled` it replaces the turn's live text with the stored
+ * messages. On every connection, load
+ * {@link readAgentEventStreamSnapshot} first and open the stream from its `resumeToken`.
+ *
+ * @example
+ * ```ts
+ * for await (const frame of streamAgentEventSseFrames({
+ *   client, flow, flowId: sessionId, resumeToken: request.headers["last-event-id"] })) {
+ *   response.write(frame);
+ * }
+ * ```
+ * @param options - Session, start position, and polling.
+ * @returns An async generator of SSE frames and keep-alive comments.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {DexServiceError} When a Stream read fails.
+ */
+export async function* streamAgentEventSseFrames(options) {
+    yield* formatAgentEventSseFramesFrom(options, undefined);
+}
+async function* formatAgentEventSseFramesFrom(options, firstMessage) {
+    const pollTimeoutMs = requireAgentEventPollTimeoutMs(options.pollTimeoutMs);
+    let eventResumeToken = options.resumeToken ?? "";
+    let pendingMessage = firstMessage;
+    while (options.signal?.aborted !== true) {
+        const message = pendingMessage ??
+            (await readNextAgentEvent(options.client, options.flow, options.flowId, eventResumeToken, pollTimeoutMs));
+        pendingMessage = undefined;
+        if (message === undefined) {
+            yield serverSentEventKeepAliveFrame;
+            continue;
+        }
+        eventResumeToken = message.resumeToken;
+        yield formatAgentEventSseFrame(message);
+    }
+}
+/**
+ * Returns a streaming `text/event-stream` Response of an agent session's `AgentEvents`.
+ *
+ * It writes {@link streamAgentEventSseFrames} and stops reading when the browser closes the response.
+ * Mount it in any server that returns a Fetch API `Response`. The session ID usually comes from the
+ * browser, so the route must check that the caller may read that session.
+ *
+ * Before it answers 200, it reads once, with a long poll of up to 1 second, to check the resume token.
+ * When Dex rejects the token, such as one of another session, it answers 400, which stops an
+ * `EventSource` from reconnecting with it; the browser then loads the snapshot again. A token from
+ * before a Stream Store restart is accepted and continues at the oldest retained event.
+ *
+ * @example
+ * ```ts
+ * // GET /sessions/:id/events
+ * export async function GET(request: Request, sessionId: string): Promise<Response> {
+ *   const url = new URL(request.url);
+ *   return createAgentEventSseResponse({
+ *     client, flow, flowId: sessionId,
+ *     resumeToken: request.headers.get("last-event-id") ?? url.searchParams.get("resumeToken") ?? "",
+ *     signal: request.signal,
+ *   });
+ * }
+ * // In the browser:
+ * const { resumeToken } = await (await fetch(`/sessions/${sessionId}/snapshot`)).json();
+ * const events = new EventSource(`/sessions/${sessionId}/events?resumeToken=${encodeURIComponent(resumeToken)}`);
+ * events.onmessage = (message) => render(JSON.parse(message.data));
+ * ```
+ * @param options - Session, start position, polling, and extra response headers.
+ * @returns A 200 Response with {@link agentEventStreamHeaders} and the application's `headers`; 400 with
+ * a text body when Dex rejects the resume token.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {DexServiceError} When the first Stream read fails for another reason.
+ */
+export async function createAgentEventSseResponse(options) {
+    requireAgentEventPollTimeoutMs(options.pollTimeoutMs);
+    const probe = await probeAgentEventResumeToken(options.client, options.flow, options.flowId, options.resumeToken ?? "");
+    if (!probe.isAccepted) {
+        return new Response("the resume token does not belong to this session; load the snapshot again", {
+            status: 400,
+            headers: mergeHeaders({ "content-type": "text/plain; charset=utf-8" }, options.headers),
+        });
+    }
+    return createServerSentEventResponse(formatAgentEventSseFramesFrom(options, probe.firstMessage), agentEventStreamHeaders, options.headers);
+}
+/**
+ * Reads the session snapshot together with the Dex resume token to open the plain event stream from.
+ *
+ * Call it whenever the browser connects or reconnects after a gap. It reads the newest event first and
+ * the snapshot second, so events after the token may repeat what the snapshot shows but none is missing.
+ * While a turn is active the token replays that turn's events, so the browser can rebuild its live text.
+ * The `get_agent_snapshot` RPC needs a running Worker.
+ *
+ * @example
+ * ```ts
+ * // GET /sessions/:id/snapshot
+ * const value = await readAgentEventStreamSnapshot({ client, flow, flowId: sessionId });
+ * return Response.json(convertAgentEventStreamSnapshotToJson(value));
+ * ```
+ * @param options - Client, Flow, and session ID.
+ * @returns The snapshot and the resume token.
+ * @throws {DexServiceError} When the Stream read or the RPC fails.
+ */
+export async function readAgentEventStreamSnapshot(options) {
+    const { client, flow, flowId } = options;
+    const tailResumeToken = await readAgentEventsTailResumeToken(client, flow, flowId);
+    const snapshot = await client.invokeRPC(flow.getAgentSnapshot, flowId);
+    const activeTurnId = snapshot.state?.activeTurnId ?? null;
+    if (activeTurnId === null) {
+        return { snapshot, resumeToken: tailResumeToken };
+    }
+    const turnResumeToken = await findAgentEventResumeTokenBeforeTurn(client, flow, flowId, activeTurnId);
+    return { snapshot, resumeToken: turnResumeToken ?? tailResumeToken };
+}
+/**
+ * Converts an {@link AgentEventStreamSnapshot} to snake_case wire JSON for an HTTP response.
+ *
+ * @param value - Snapshot and resume token.
+ * @returns `{ snapshot, resume_token }`, with the snapshot in its `AgentSnapshot` wire format.
+ */
+export function convertAgentEventStreamSnapshotToJson(value) {
+    return { snapshot: convertAgentSnapshotToJson(value.snapshot), resume_token: value.resumeToken };
+}
+//# sourceMappingURL=agent-event-sse.js.map

package/dist/src/ui-stream/agent-event-sse.js.map

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

package/dist/src/ui-stream/agent-event-stream-positions.d.ts

@@ -0,0 +1,42 @@
+import { type Client, type StreamMessage } from "@superdurable/dex";
+import type { AgentFrameworkRunner, DeferredToolOutcome } from "../agent-framework-runner.js";
+import type { AgentSessionFlow } from "../agent-session-flow.js";
+import type { AgentEvent } from "../agent-session-values.js";
+/** Default long-poll duration of one `AgentEvents` read: 10 seconds. */
+export declare const defaultAgentEventPollTimeoutMs = 10000;
+/** Long poll of the read that checks a resume token before a response commits to status 200. */
+export declare const resumeTokenProbeTimeoutMs = 1000;
+/** Validates a long-poll duration; Dex Stream reads take whole seconds. */
+export declare function requireAgentEventPollTimeoutMs(pollTimeoutMs: number | undefined): number;
+/**
+ * Reads the next `AgentEvents` message, or `undefined` when the long poll ends without one.
+ * A disabled Stream Store holds no events, so the read waits as an empty poll would.
+ */
+export declare function readNextAgentEvent(client: Client, flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>, flowId: string, eventResumeToken: string, pollTimeoutMs: number): Promise<StreamMessage<AgentEvent> | undefined>;
+/** Reports whether Dex rejected a Stream resume token, such as one of another session. */
+export declare function isStreamResumeTokenRejectedError(error: unknown): boolean;
+/** Reports whether a Stream call failed because the Server's Stream Store is disabled. */
+export declare function isStreamStoreDisabledError(error: unknown): boolean;
+/** The first read after a resume token, done before a response commits to its status. */
+export type AgentEventResumeTokenProbe = {
+    readonly isAccepted: true;
+    readonly firstMessage: StreamMessage<AgentEvent> | undefined;
+} | {
+    readonly isAccepted: false;
+};
+/** Reads once with a short long poll to learn whether Dex accepts a resume token. */
+export declare function probeAgentEventResumeToken(client: Client, flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>, flowId: string, eventResumeToken: string): Promise<AgentEventResumeTokenProbe>;
+/** Returns the resume token of the newest retained event, or `""` when the Stream holds none. */
+export declare function readAgentEventsTailResumeToken(client: Client, flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>, flowId: string): Promise<string>;
+/**
+ * Finds the position just before a turn's first retained event.
+ *
+ * @returns The resume token whose next event is the turn's `turn_started`, or the turn's oldest retained
+ * event; `""` when that event is the oldest retained one; `undefined` when the Stream holds no event of
+ * the turn or the search reached its page limit.
+ */
+export declare function findAgentEventResumeTokenBeforeTurn(client: Client, flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>, flowId: string, turnId: string): Promise<string | undefined>;
+/** Returns the number `n` of a `turn-<n>` turn ID, or `undefined` for another format. */
+export declare function parseTurnNumber(turnId: string): number | undefined;
+/** Returns the Step type of a `StepType-Number` Step execution ID, or `""` when it has no number. */
+export declare function readStepType(stepExecutionId: string): string;