@superdurable/dex-agents 0.1.0 → 0.3.0

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

@@ -0,0 +1,246 @@
+// 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 { FlowNotFoundError } from "@superdurable/dex";
+import { readSessionFailure } from "../agent-session-failure.js";
+import { messageSequenceKey } from "../agent-session-persistence.js";
+import { findMessageChunkRange } from "../agent-session-transitions.js";
+import { parseTurnNumber } from "./agent-event-stream-positions.js";
+const committedRecordWaitMs = 3_000;
+const committedRecordPollIntervalMs = 25;
+const storedMessagePageSize = 50;
+const recentStoredMessageCount = 200;
+const maximumStoredMessageReadAttempts = 3;
+/** Reads committed session state for the UI streams; Attribute reads need no running Worker. */
+export class AgentSessionRecordReader {
+    client;
+    flow;
+    flowId;
+    constructor(client, flow, flowId) {
+        this.client = client;
+        this.flow = flow;
+        this.flowId = flowId;
+    }
+    async readAgentState() {
+        const [state] = await this.client.getAttributes(this.flowId, this.flow.agentState);
+        return state;
+    }
+    /**
+     * 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.
+     */
+    async waitForTurnToEnd(turnId) {
+        const deadline = Date.now() + committedRecordWaitMs;
+        for (;;) {
+            const state = await this.readAgentState();
+            if (state?.activeTurnId !== turnId) {
+                return true;
+            }
+            if (Date.now() >= deadline) {
+                return false;
+            }
+            await delay(committedRecordPollIntervalMs);
+        }
+    }
+    /**
+     * Reads the IDs of the tool calls whose approval `resolve_interrupt` still accepts.
+     * @returns The tool call IDs of the pending `tool_approval` interrupts.
+     */
+    async readPendingApprovalToolCallIds() {
+        const [interrupts] = await this.client.getAttributes(this.flowId, this.flow.pendingInterrupts);
+        return new Set((interrupts ?? [])
+            .filter((interrupt) => interrupt.kind === "tool_approval")
+            .map((interrupt) => interrupt.toolCallId));
+    }
+    async isFlowRunning() {
+        try {
+            return (await this.client.describeFlow(this.flowId)).status === "running";
+        }
+        catch (error) {
+            if (error instanceof FlowNotFoundError) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /** Returns why the session's Flow failed, or `undefined` when it did not. */
+    readFlowFailure() {
+        return readSessionFailure(this.client, this.flowId);
+    }
+    /**
+     * 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.
+     */
+    async readToolCallDetails(turnId, toolCallId, isReady) {
+        const record = await this.waitForToolCall(turnId, toolCallId, isReady);
+        if (record !== undefined) {
+            return { record, toolName: record.toolName, toolArguments: record.arguments, storedToolOutput: undefined };
+        }
+        const storedMessages = await this.readStoredToolMessages(turnId, toolCallId);
+        return {
+            record: undefined,
+            toolName: storedMessages.toolCall?.toolName ?? storedMessages.toolResult?.toolName ?? undefined,
+            toolArguments: storedMessages.toolCall?.toolArguments ?? undefined,
+            storedToolOutput: storedMessages.toolResult?.toolOutput ?? undefined,
+        };
+    }
+    async waitForToolCall(turnId, toolCallId, isReady) {
+        const deadline = Date.now() + committedRecordWaitMs;
+        for (;;) {
+            const [record] = await this.client.getAttributes(this.flowId, this.flow.agentToolCalls.instance(toolCallId));
+            const turnRecord = record?.turnId === turnId ? record : undefined;
+            if ((turnRecord !== undefined && isReady(turnRecord)) || Date.now() >= deadline) {
+                return turnRecord;
+            }
+            if (turnRecord === undefined && (await this.readAgentState())?.activeTurnId !== turnId) {
+                return undefined;
+            }
+            await delay(committedRecordPollIntervalMs);
+        }
+    }
+    /**
+     * 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.
+     */
+    async readCommittedToolCall(turnId, toolCallId) {
+        return this.waitForToolCall(turnId, toolCallId, () => true);
+    }
+    /**
+     * Reads one tool call record once, without waiting for a commit.
+     * @returns The record when it exists and belongs to `turnId`, otherwise `undefined`.
+     */
+    async readToolCall(turnId, toolCallId) {
+        const [record] = await this.client.getAttributes(this.flowId, this.flow.agentToolCalls.instance(toolCallId));
+        return record?.turnId === turnId ? record : 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.
+     */
+    async readRecentStoredToolResults() {
+        const state = await this.readAgentState();
+        const endSequence = state?.nextMessageSequence ?? 1;
+        const startSequence = Math.max(1, endSequence - recentStoredMessageCount);
+        if (startSequence >= endSequence) {
+            return [];
+        }
+        const results = [];
+        for (const message of (await this.readStoredMessages(startSequence, endSequence)).messages) {
+            const toolOutput = message?.toolOutput ?? message?.text;
+            if (message?.role === "tool" && message.toolCallId !== null && toolOutput != null) {
+                results.push({ turnId: message.turnId, toolCallId: message.toolCallId, toolOutput });
+            }
+        }
+        return results;
+    }
+    /** Finds a tool call's stored request and result messages, newest pages first, within its turn. */
+    async readStoredToolMessages(turnId, toolCallId) {
+        const state = await this.readAgentState();
+        const turnNumber = parseTurnNumber(turnId);
+        const found = {};
+        let endSequence = state?.nextMessageSequence ?? 1;
+        let firstSequence = 1;
+        while (endSequence > firstSequence) {
+            const startSequence = Math.max(firstSequence, endSequence - storedMessagePageSize);
+            const page = await this.readStoredMessages(startSequence, endSequence);
+            const messages = page.messages;
+            firstSequence = page.firstSequence;
+            let hasEarlierTurn = false;
+            for (const message of messages) {
+                if (message === undefined) {
+                    continue;
+                }
+                if (message.turnId !== turnId) {
+                    hasEarlierTurn ||= (parseTurnNumber(message.turnId) ?? 0) < (turnNumber ?? 0);
+                    continue;
+                }
+                if (message.toolCallId === toolCallId) {
+                    if (message.role === "tool") {
+                        found.toolResult = message;
+                    }
+                    else {
+                        found.toolCall = message;
+                    }
+                }
+            }
+            if (hasEarlierTurn || (found.toolCall !== undefined && found.toolResult !== undefined)) {
+                return found;
+            }
+            endSequence = startSequence;
+        }
+        return found;
+    }
+    /**
+     * 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.
+     */
+    async readStoredMessages(startSequence, endSequence) {
+        let [index] = await this.client.getAttributes(this.flowId, this.flow.agentMessageIndex);
+        for (let attempt = 1;; attempt += 1) {
+            const firstSequence = index?.firstSequence ?? 1;
+            const chunkStarts = new Set();
+            const windowSequences = [];
+            for (let sequence = Math.max(firstSequence, startSequence); sequence < endSequence; sequence += 1) {
+                const range = index === undefined ? undefined : findMessageChunkRange(index, sequence);
+                if (range === undefined) {
+                    windowSequences.push(sequence);
+                }
+                else {
+                    chunkStarts.add(range.firstSequence);
+                }
+            }
+            const chunkReads = [...chunkStarts].map((chunkStart) => this.flow.agentMessageChunks.instance(messageSequenceKey(chunkStart)));
+            const windowReads = windowSequences.map((sequence) => this.flow.agentMessages.instance(messageSequenceKey(sequence)));
+            const values = (await this.client.getAttributes(this.flowId, ...[this.flow.agentMessageIndex, ...chunkReads, ...windowReads]));
+            const readIndex = values[0];
+            // A rollover or retention between the two reads moved messages, so read again with the new index.
+            if (!isSameMessageLayout(index, readIndex)) {
+                if (attempt >= maximumStoredMessageReadAttempts) {
+                    throw new Error(`the stored messages of session ${this.flowId} moved during ${maximumStoredMessageReadAttempts} reads`);
+                }
+                index = readIndex;
+                continue;
+            }
+            const bySequence = new Map();
+            for (const value of values.slice(1, 1 + chunkReads.length)) {
+                for (const message of value?.messages ?? []) {
+                    bySequence.set(message.sequence, message);
+                }
+            }
+            for (const [offset, value] of values.slice(1 + chunkReads.length).entries()) {
+                const sequence = windowSequences[offset];
+                if (sequence !== undefined && value !== undefined) {
+                    bySequence.set(sequence, value);
+                }
+            }
+            const messages = [];
+            for (let sequence = startSequence; sequence < endSequence; sequence += 1) {
+                const message = bySequence.get(sequence);
+                if (message === undefined && sequence >= firstSequence) {
+                    throw new Error(`session ${this.flowId} has no stored message ${sequence}`);
+                }
+                messages.push(message);
+            }
+            return { messages, firstSequence };
+        }
+    }
+}
+function isSameMessageLayout(left, right) {
+    return (left?.firstSequence === right?.firstSequence &&
+        left?.windowFirstSequence === right?.windowFirstSequence &&
+        left?.chunks.length === right?.chunks.length);
+}
+//# sourceMappingURL=agent-session-record-reader.js.map

package/dist/src/ui-stream/agent-session-record-reader.js.map

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

package/dist/src/ui-stream/agent-ui-message-stream-responses.d.ts

@@ -0,0 +1,219 @@
+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 AgentUIMessageStreamOptions } from "./agent-ui-message-stream.js";
+/**
+ * Request header name for a UI stream resume token.
+ *
+ * Send the token in this header rather than the URL: a token can reach 64 KiB, beyond many URL limits.
+ */
+export declare const agentResumeTokenHeaderName = "x-agent-resume-token";
+/** {@link AgentUIMessageStreamOptions} plus headers to add to the Response. */
+export interface AgentUIMessageStreamResponseOptions extends AgentUIMessageStreamOptions {
+    /** Extra response headers; they override the protocol headers with the same name. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Options of {@link sendAgentUserMessageWithUIMessageStream}. */
+export interface AgentUserMessageUIStreamOptions extends Omit<AgentUIMessageStreamResponseOptions, "resumeToken"> {
+    /** Text of the user message. */
+    readonly text: string;
+}
+/**
+ * One tool approval decision, the content of an AI SDK `tool-approval-response`.
+ *
+ * `useChat` records it on a tool part when the application calls `addToolApprovalResponse`.
+ */
+export interface AgentToolApprovalResponse {
+    /** Approval ID from the `tool-approval-request` part: the `interrupt_id` of the pending interrupt. */
+    readonly approvalId: string;
+    /** Whether the tool call may run. */
+    readonly approved: boolean;
+    /** Message the model sees after a rejection. Ignored on approval. */
+    readonly reason?: string | undefined;
+    /**
+     * Turn whose assistant message holds the decision, such as `"turn-3"`, or `undefined` when unknown.
+     * {@link resolveAgentToolApprovalsWithUIMessageStream} treats a decision bound to another turn than the
+     * active one as stale, so a stale browser tab cannot answer a later turn's call that reuses a tool call
+     * ID. {@link readAgentToolApprovalResponses} sets it from the message ID.
+     */
+    readonly turnId?: string | undefined;
+}
+/** Options of {@link resolveAgentToolApproval}. */
+export interface AgentToolApprovalOptions {
+    /** Client used for the RPC. */
+    readonly client: Client;
+    /** The agent session Flow. */
+    readonly flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>;
+    /** Session ID: the Flow ID of the agent session. */
+    readonly flowId: string;
+    /** The decision to send. */
+    readonly approval: AgentToolApprovalResponse;
+}
+/** Options of {@link resolveAgentToolApprovalsWithUIMessageStream}. */
+export interface AgentToolApprovalsUIStreamOptions extends AgentUIMessageStreamResponseOptions {
+    /**
+     * Decisions from the browser, such as the result of {@link readAgentToolApprovalResponses}. They are
+     * untrusted: only the first decision per approval ID counts, at most 100 are read, and only interrupts
+     * pending in the session's active turn are resolved, by decisions bound to that turn or to none.
+     */
+    readonly approvals: readonly AgentToolApprovalResponse[];
+}
+/**
+ * Returns a streaming AI SDK UI message stream Response for one agent turn, or 204 when there is none.
+ *
+ * Mount it as the reconnect endpoint of `useChat`, `GET <api>/<chatId>/stream` by default, with the chat ID
+ * as the session ID; the route must check that the caller may read that session. It writes
+ * {@link streamAgentUIMessageChunks} as Server-Sent Events with the protocol headers, a keep-alive
+ * comment after each empty long poll, and `data: [DONE]` at the end. It stops reading when the browser
+ * closes the response.
+ *
+ * Use the default `DefaultChatTransport`, whose resumed streams count as replays. A stream started with a
+ * token replays the token's turn, and one started without a token replays the active turn; either way
+ * its `start` part makes the browser reset the message and rebuild it, whatever it held. With
+ * `continueAfterResumeToken`, a stream continues exactly after the last part the browser received and
+ * sends no `start` part; use it only while the browser still holds that message. Before it answers 200,
+ * the helper reads once to check the token's Dex position; a position Dex rejects restarts the turn from
+ * its first retained event.
+ *
+ * @example
+ * ```ts
+ * // Server: GET /api/chat/:id/stream
+ * export async function GET(request: Request, sessionId: string): Promise<Response> {
+ *   await authorizeSession(request, sessionId);
+ *   return createAgentUIMessageStreamResponse({
+ *     client, flow, flowId: sessionId,
+ *     resumeToken: request.headers.get(agentResumeTokenHeaderName) ?? undefined,
+ *     signal: request.signal,
+ *   });
+ * }
+ *
+ * // Browser
+ * let resumeToken: string | undefined = initial.resumeToken ?? undefined;
+ * const chat = useChat({
+ *   id: sessionId,
+ *   messages: initial.messages,
+ *   resume: resumeToken !== undefined,
+ *   onData: (part) => {
+ *     if (part.type === "data-agent-resume-token") resumeToken = part.data as string;
+ *   },
+ *   transport: new DefaultChatTransport({
+ *     api: "/api/chat",
+ *     prepareReconnectToStreamRequest: ({ id }) => ({
+ *       api: `/api/chat/${id}/stream`,
+ *       headers: resumeToken === undefined ? {} : { "x-agent-resume-token": resumeToken },
+ *     }),
+ *   }),
+ *   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
+ * });
+ * ```
+ * @param options - Session, start position, polling, and extra headers.
+ * @returns 200 with the stream; 204 when the token's turn already finished, or when the turn to replay is
+ * not active or not on the Stream; 400 with a text body when `resumeToken` is invalid.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {DexServiceError} When reading the start position fails.
+ */
+export declare function createAgentUIMessageStreamResponse(options: AgentUIMessageStreamResponseOptions): Promise<Response>;
+/**
+ * Queues a user message and returns the AI SDK UI message stream Response of the turn it starts.
+ *
+ * Mount it as the send endpoint of `useChat`, `POST <api>` by default, when the last message in the
+ * request body is a user message. The chat ID in the body comes from the browser, so the route must check
+ * that the caller may write to that session. The helper reads the session's turn count and the Stream
+ * position first and then calls `send_user_message`, so the stream follows the next turn that starts
+ * after the message was queued. When an earlier turn is still running, the stream waits for it to end.
+ * When other messages were queued before this one, the stream follows the turn of the oldest of them.
+ *
+ * The session's committed state ends the stream even when no event of the turn reaches the Stream, such
+ * as with the Server's Stream Store disabled: once that turn ended, the stream finishes with reason
+ * `other`, and the application reloads the stored messages. The RPC needs a running Worker.
+ *
+ * @example
+ * ```ts
+ * // POST /api/chat
+ * export async function POST(request: Request): Promise<Response> {
+ *   const { id, messages } = await request.json();
+ *   await authorizeSession(request, id);
+ *   const lastMessage = messages.at(-1);
+ *   if (lastMessage.role === "assistant") {
+ *     return resolveAgentToolApprovalsWithUIMessageStream({
+ *       client, flow, flowId: id, approvals: readAgentToolApprovalResponses(lastMessage) });
+ *   }
+ *   const text = lastMessage.parts.filter((part) => part.type === "text").map((part) => part.text).join("");
+ *   return sendAgentUserMessageWithUIMessageStream({ client, flow, flowId: id, text, signal: request.signal });
+ * }
+ * ```
+ * @param options - Session, message text, polling, and extra headers.
+ * @returns 200 with the stream; 400 with a text body when the text is blank.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {FlowNotActiveOrNotFoundError} When the session is not running.
+ * @throws {DexServiceError} When a read or the RPC fails.
+ */
+export declare function sendAgentUserMessageWithUIMessageStream(options: AgentUserMessageUIStreamOptions): Promise<Response>;
+/**
+ * Sends one tool approval decision to the session's `resolve_interrupt` RPC.
+ *
+ * Call it with each AI SDK `tool-approval-response`: its `approvalId` is the `interrupt_id`, and its
+ * `reason` becomes the rejection message the model sees. It retries `RpcLockConflictError`, which a call
+ * that races the approval Step can raise, for up to 5 seconds. It resolves any pending interrupt of the
+ * session, so the route must check that the caller may decide for that session. The RPC needs a running
+ * Worker.
+ *
+ * @example
+ * ```ts
+ * const isResolved = await resolveAgentToolApproval({
+ *   client, flow, flowId: sessionId,
+ *   approval: { approvalId: "call_42", approved: false, reason: "Use the sandbox account" },
+ * });
+ * ```
+ * @param options - Session and decision.
+ * @returns `true` when the interrupt was pending and is now resolved; `false` when it is unknown, already
+ * resolved, or past its deadline.
+ * @throws {RpcLockConflictError} When the lock stays busy for 5 seconds.
+ * @throws {FlowNotActiveOrNotFoundError} When the session is not running.
+ */
+export declare function resolveAgentToolApproval(options: AgentToolApprovalOptions): Promise<boolean>;
+/**
+ * Returns the tool approval decisions recorded on an AI SDK assistant message.
+ *
+ * `useChat` sets a tool part to `approval-responded` when the application calls
+ * `addToolApprovalResponse`, then sends the message list with `sendAutomaticallyWhen`. Pass the last
+ * message of that request body. The message comes from the browser, so every field is checked; parts
+ * that are not well-formed responded approvals are skipped.
+ *
+ * Each decision is bound to the message's turn when the message ID is `<turnId>-assistant`, as the agent UI
+ * streams and snapshots name assistant messages; a message with another ID gives unbound decisions.
+ *
+ * @param message - An AI SDK `UIMessage`, typically the last message of a `useChat` request body.
+ * @returns One decision per `approval-responded` tool part, in part order; empty for anything else.
+ */
+export declare function readAgentToolApprovalResponses(message: unknown): AgentToolApprovalResponse[];
+/**
+ * Sends tool approval decisions and returns the AI SDK UI message stream Response that continues the turn.
+ *
+ * Mount it in the send endpoint of `useChat` for requests whose last message is an assistant message,
+ * which `sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses` sends after the
+ * application answered every approval. The decisions and the chat ID come from the browser, so the route
+ * must check that the caller may decide for that session. Only interrupts that are pending in the
+ * session's active turn are resolved.
+ *
+ * The stream continues the same assistant message. A decision that is no longer pending, because another
+ * client or a deadline settled the call or its turn ended, gets the call's known outcome, or an error
+ * part when none is known, so the browser leaves `approval-responded` and does not send the decision
+ * again. Decisions bound to another turn than the active one, such as from a stale browser tab, are all
+ * stale, and the stream then ends after their outcomes. With `resumeToken`, the latest `data-agent-resume-token`, the stream continues exactly after the
+ * paused stream. Without one it reads the Stream position and the active turn's tool calls before
+ * sending the decisions. The RPCs need a running Worker.
+ *
+ * @example
+ * ```ts
+ * return resolveAgentToolApprovalsWithUIMessageStream({
+ *   client, flow, flowId: id, approvals: readAgentToolApprovalResponses(messages.at(-1)) });
+ * ```
+ * @param options - Session, decisions, optional resume token, polling, and extra headers.
+ * @returns 200 with the stream, which holds only the stale decisions' outcomes and a `finish` part when
+ * no turn is active; 400 with a text body when `resumeToken` is invalid.
+ * @throws {RangeError} When `pollTimeoutMs` is not a positive whole number of seconds.
+ * @throws {RpcLockConflictError} When a decision's lock stays busy for 5 seconds.
+ * @throws {DexServiceError} When a read or an RPC fails.
+ */
+export declare function resolveAgentToolApprovalsWithUIMessageStream(options: AgentToolApprovalsUIStreamOptions): Promise<Response>;