@superdurable/dex-agents 0.1.0 → 0.3.0

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

@@ -0,0 +1,155 @@
+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 ends on its own only once the
+ * session's Flow failed and every event was sent; otherwise 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,167 @@
+// 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 { readAgentSnapshot, readSessionFailure } from "../agent-session-failure.js";
+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 ends on its own only once the
+ * session's Flow failed and every event was sent; otherwise 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;
+    let hasFlowFailed = false;
+    while (options.signal?.aborted !== true) {
+        const message = pendingMessage ??
+            (await readNextAgentEvent(options.client, options.flow, options.flowId, eventResumeToken, pollTimeoutMs));
+        pendingMessage = undefined;
+        if (message === undefined) {
+            // A poll that started after the Flow failed saw every event there will be.
+            if (hasFlowFailed) {
+                return;
+            }
+            hasFlowFailed = (await readSessionFailure(options.client, options.flowId)) !== 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 readAgentSnapshot(client, flow, 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;

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

@@ -0,0 +1,153 @@
+// 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 { setTimeout as delay } from "node:timers/promises";
+import { DexServiceError, LongPollTimeoutError } from "@superdurable/dex";
+/** Default long-poll duration of one `AgentEvents` read: 10 seconds. */
+export const defaultAgentEventPollTimeoutMs = 10_000;
+/** Long poll of the read that checks a resume token before a response commits to status 200. */
+export const resumeTokenProbeTimeoutMs = 1_000;
+const grpcInvalidArgument = 3;
+const grpcFailedPrecondition = 9;
+const turnStartSearchPageSize = 500;
+const turnStartSearchPageLimit = 20;
+const turnIdPattern = /^turn-(\d+)$/;
+/** Validates a long-poll duration; Dex Stream reads take whole seconds. */
+export function requireAgentEventPollTimeoutMs(pollTimeoutMs) {
+    const timeoutMs = pollTimeoutMs ?? defaultAgentEventPollTimeoutMs;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs % 1_000 !== 0) {
+        throw new RangeError("pollTimeoutMs must be a positive whole number of seconds, in milliseconds");
+    }
+    return timeoutMs;
+}
+/**
+ * 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 async function readNextAgentEvent(client, flow, flowId, eventResumeToken, pollTimeoutMs) {
+    try {
+        return await client.readStream(flowId, flow.agentEvents, eventResumeToken, pollTimeoutMs);
+    }
+    catch (error) {
+        if (error instanceof LongPollTimeoutError) {
+            return undefined;
+        }
+        if (isStreamStoreDisabledError(error)) {
+            await delay(Math.min(pollTimeoutMs, resumeTokenProbeTimeoutMs));
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** Reports whether Dex rejected a Stream resume token, such as one of another session. */
+export function isStreamResumeTokenRejectedError(error) {
+    return error instanceof DexServiceError && Number(error.code) === grpcInvalidArgument;
+}
+/** Reports whether a Stream call failed because the Server's Stream Store is disabled. */
+export function isStreamStoreDisabledError(error) {
+    return error instanceof DexServiceError && Number(error.code) === grpcFailedPrecondition;
+}
+/** Reads once with a short long poll to learn whether Dex accepts a resume token. */
+export async function probeAgentEventResumeToken(client, flow, flowId, eventResumeToken) {
+    try {
+        const firstMessage = await readNextAgentEvent(client, flow, flowId, eventResumeToken, resumeTokenProbeTimeoutMs);
+        return { isAccepted: true, firstMessage };
+    }
+    catch (error) {
+        if (isStreamResumeTokenRejectedError(error)) {
+            return { isAccepted: false };
+        }
+        throw error;
+    }
+}
+/** Returns the resume token of the newest retained event, or `""` when the Stream holds none. */
+export async function readAgentEventsTailResumeToken(client, flow, flowId) {
+    try {
+        const page = await client.listStreamMessages(flowId, flow.agentEvents, 1);
+        return page.messages[0]?.resumeToken ?? "";
+    }
+    catch (error) {
+        if (isStreamStoreDisabledError(error)) {
+            return "";
+        }
+        throw error;
+    }
+}
+/**
+ * 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 async function findAgentEventResumeTokenBeforeTurn(client, flow, flowId, turnId) {
+    try {
+        return await searchAgentEventResumeTokenBeforeTurn(client, flow, flowId, turnId);
+    }
+    catch (error) {
+        if (isStreamStoreDisabledError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function searchAgentEventResumeTokenBeforeTurn(client, flow, flowId, turnId) {
+    const turnNumber = parseTurnNumber(turnId);
+    let hasTurnEvent = false;
+    let pageToken = "";
+    for (let pageIndex = 0; pageIndex < turnStartSearchPageLimit; pageIndex += 1) {
+        const page = await client.listStreamMessages(flowId, flow.agentEvents, turnStartSearchPageSize, pageToken);
+        for (const [index, message] of page.messages.entries()) {
+            const event = message.value;
+            if (event.turnId === turnId) {
+                hasTurnEvent = true;
+                if (event.type !== "turn_started") {
+                    continue;
+                }
+            }
+            else if (!isEarlierTurn(event.turnId, turnNumber)) {
+                continue;
+            }
+            // The events of the turn are all newer than this message, or this message is turn_started.
+            const olderMessage = event.turnId === turnId ? page.messages[index + 1] : message;
+            if (olderMessage !== undefined) {
+                return hasTurnEvent ? olderMessage.resumeToken : undefined;
+            }
+            return readResumeTokenOlderThanPage(client, flow, flowId, page.nextPageToken);
+        }
+        if (page.nextPageToken === "") {
+            return hasTurnEvent ? "" : undefined;
+        }
+        pageToken = page.nextPageToken;
+    }
+    return undefined;
+}
+/** Returns the number `n` of a `turn-<n>` turn ID, or `undefined` for another format. */
+export function parseTurnNumber(turnId) {
+    const match = turnIdPattern.exec(turnId);
+    return match?.[1] === undefined ? undefined : Number(match[1]);
+}
+/** Returns the Step type of a `StepType-Number` Step execution ID, or `""` when it has no number. */
+export function readStepType(stepExecutionId) {
+    const separatorIndex = stepExecutionId.lastIndexOf("-");
+    return separatorIndex <= 0 ? "" : stepExecutionId.slice(0, separatorIndex);
+}
+async function readResumeTokenOlderThanPage(client, flow, flowId, nextPageToken) {
+    if (nextPageToken === "") {
+        return "";
+    }
+    const olderPage = await client.listStreamMessages(flowId, flow.agentEvents, 1, nextPageToken);
+    return olderPage.messages[0]?.resumeToken ?? "";
+}
+function isEarlierTurn(turnId, turnNumber) {
+    if (turnId === null || turnNumber === undefined) {
+        return false;
+    }
+    const otherTurnNumber = parseTurnNumber(turnId);
+    return otherTurnNumber !== undefined && otherTurnNumber < turnNumber;
+}
+//# sourceMappingURL=agent-event-stream-positions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-event-stream-positions.js","sourceRoot":"","sources":["../../../src/ui-stream/agent-event-stream-positions.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAmC,MAAM,mBAAmB,CAAC;AAM3G,wEAAwE;AACxE,MAAM,CAAC,MAAM,8BAA8B,GAAG,MAAM,CAAC;AAErD,gGAAgG;AAChG,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC;AAE/C,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACjC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AACpC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AACpC,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC,2EAA2E;AAC3E,MAAM,UAAU,8BAA8B,CAAC,aAAiC;IAC9E,MAAM,SAAS,GAAG,aAAa,IAAI,8BAA8B,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,KAAK,IAAI,SAAS,GAAG,KAAK,KAAK,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,UAAU,CAAC,2EAA2E,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAc,EACd,IAAiE,EACjE,MAAc,EACd,gBAAwB,EACxB,aAAqB;IAErB,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;IAC5F,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;YAC1C,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,yBAAyB,CAAC,CAAC,CAAC;YAChE,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,gCAAgC,CAAC,KAAc;IAC7D,OAAO,KAAK,YAAY,eAAe,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,mBAAmB,CAAC;AACxF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,OAAO,KAAK,YAAY,eAAe,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,sBAAsB,CAAC;AAC3F,CAAC;AAOD,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,MAAc,EACd,IAAiE,EACjE,MAAc,EACd,gBAAwB;IAExB,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,kBAAkB,CAC3C,MAAM,EACN,IAAI,EACJ,MAAM,EACN,gBAAgB,EAChB,yBAAyB,CAC1B,CAAC;QACF,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,gCAAgC,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;QAC/B,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,MAAc,EACd,IAAiE,EACjE,MAAc;IAEd,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mCAAmC,CACvD,MAAc,EACd,IAAiE,EACjE,MAAc,EACd,MAAc;IAEd,IAAI,CAAC;QACH,OAAO,MAAM,qCAAqC,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC;YACtC,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,qCAAqC,CAClD,MAAc,EACd,IAAiE,EACjE,MAAc,EACd,MAAc;IAEd,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,wBAAwB,EAAE,SAAS,IAAI,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAC1C,MAAM,EACN,IAAI,CAAC,WAAW,EAChB,uBAAuB,EACvB,SAAS,CACV,CAAC;QACF,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YACvD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;YAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC5B,YAAY,GAAG,IAAI,CAAC;gBACpB,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;oBAClC,SAAS;gBACX,CAAC;YACH,CAAC;iBAAM,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;gBACpD,SAAS;YACX,CAAC;YACD,2FAA2F;YAC3F,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YAClF,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;YAC7D,CAAC;YACD,OAAO,4BAA4B,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,EAAE,EAAE,CAAC;YAC9B,OAAO,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACvC,CAAC;QACD,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,eAAuB;IAClD,MAAM,cAAc,GAAG,eAAe,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,cAAc,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AAC7E,CAAC;AAED,KAAK,UAAU,4BAA4B,CACzC,MAAc,EACd,IAAiE,EACjE,MAAc,EACd,aAAqB;IAErB,IAAI,aAAa,KAAK,EAAE,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,aAAa,CAAC,CAAC;IAC9F,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,SAAS,aAAa,CAAC,MAAqB,EAAE,UAA8B;IAC1E,IAAI,MAAM,KAAK,IAAI,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,eAAe,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAChD,OAAO,eAAe,KAAK,SAAS,IAAI,eAAe,GAAG,UAAU,CAAC;AACvE,CAAC"}

package/dist/src/ui-stream/agent-session-record-reader.d.ts

@@ -0,0 +1,74 @@
+import { type Client } from "@superdurable/dex";
+import type { AgentFrameworkRunner, DeferredToolOutcome } from "../agent-framework-runner.js";
+import type { AgentSessionFlow } from "../agent-session-flow.js";
+import type { AgentState, AgentToolCallRecord } from "../agent-session-values.js";
+/** Reads committed session state for the UI streams; Attribute reads need no running Worker. */
+export declare class AgentSessionRecordReader {
+    private readonly client;
+    private readonly flow;
+    private readonly flowId;
+    constructor(client: Client, flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>, flowId: string);
+    readAgentState(): Promise<AgentState | undefined>;
+    /**
+     * Waits until a turn's end committed, because its end event reaches the Stream before the commit.
+     * @returns `true` once the turn is no longer active; `false` after 3 seconds without that commit.
+     */
+    waitForTurnToEnd(turnId: string): Promise<boolean>;
+    /**
+     * Reads the IDs of the tool calls whose approval `resolve_interrupt` still accepts.
+     * @returns The tool call IDs of the pending `tool_approval` interrupts.
+     */
+    readPendingApprovalToolCallIds(): Promise<ReadonlySet<string>>;
+    isFlowRunning(): Promise<boolean>;
+    /** Returns why the session's Flow failed, or `undefined` when it did not. */
+    readFlowFailure(): Promise<string | undefined>;
+    /**
+     * Reads what the session holds about one tool call of a turn.
+     *
+     * Events reach the Stream before their Step commits, so it polls the record until `isReady` holds, for
+     * up to 3 seconds. A turn that ended deleted its records; then it reads the turn's stored messages.
+     * @returns The record when it exists, plus the tool name, arguments, and stored result text from the
+     * record or the stored messages; each is `undefined` when neither holds it.
+     */
+    readToolCallDetails(turnId: string, toolCallId: string, isReady: (toolCall: AgentToolCallRecord) => boolean): Promise<ToolCallDetails>;
+    private waitForToolCall;
+    /**
+     * Waits up to 3 seconds for a tool call record to be committed, because events precede their commit.
+     * @returns The record, or `undefined` when it never appeared or the turn is no longer active.
+     */
+    readCommittedToolCall(turnId: string, toolCallId: string): Promise<AgentToolCallRecord | undefined>;
+    /**
+     * Reads one tool call record once, without waiting for a commit.
+     * @returns The record when it exists and belongs to `turnId`, otherwise `undefined`.
+     */
+    readToolCall(turnId: string, toolCallId: string): Promise<AgentToolCallRecord | undefined>;
+    /**
+     * Reads the stored tool results among the last 200 stored messages of any turn.
+     * @returns The results in sequence order, each with its turn, tool call ID, and the text the model saw.
+     */
+    readRecentStoredToolResults(): Promise<readonly StoredToolResult[]>;
+    /** Finds a tool call's stored request and result messages, newest pages first, within its turn. */
+    private readStoredToolMessages;
+    /**
+     * Reads stored messages with sequences in `[startSequence, endSequence)`, in sequence order, from the
+     * `AgentMessages` window and the `AgentMessageChunks` instances that `AgentMessageIndex` names. A message
+     * that retention deleted reads as `undefined`. A commit between the index read and the instance reads moves
+     * messages, so the read repeats with the new index.
+     * @returns The messages and the sequence of the oldest stored message.
+     * @throws Error when the index keeps changing for every attempt, or a stored message is missing.
+     */
+    private readStoredMessages;
+}
+/** What the session holds about one tool call; see {@link AgentSessionRecordReader.readToolCallDetails}. */
+export interface ToolCallDetails {
+    readonly record: AgentToolCallRecord | undefined;
+    readonly toolName: string | undefined;
+    readonly toolArguments: string | undefined;
+    readonly storedToolOutput: string | undefined;
+}
+/** One stored tool result; see {@link AgentSessionRecordReader.readRecentStoredToolResults}. */
+export interface StoredToolResult {
+    readonly turnId: string;
+    readonly toolCallId: string;
+    readonly toolOutput: string;
+}