@superdurable/dex-agents 0.1.0 → 0.2.0

package/dist/src/testing/agent-session-test-client.js

@@ -7,6 +7,7 @@
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
 import { setTimeout as delay } from "node:timers/promises";
 import { RpcLockConflictError } from "@superdurable/dex";
+import { validateSessionSettings } from "../agent-session-settings.js";
 import { pollUntil } from "./polling.js";
 const lockConflictRetryTimeoutMs = 30_000;
 const lockConflictRetryIntervalMs = 50;
@@ -48,19 +49,82 @@ export class AgentSessionTestClient {
      * @param sessionId - Flow ID of the new session.
      * @param initialMessage - First user message, or `null` to start idle. Defaults to `null`.
      * @param startFlowOptions - Start options, such as a `configOverride` with `stepDurability`.
+     * @param sessionSettings - The session's settings, or `null` to start without settings. Defaults to `null`.
      * @returns A Promise that resolves after Dex accepted the start.
+     * @throws {TypeError | RangeError} From `validateSessionSettings`, before anything is sent.
      */
-    async startSession(sessionId, initialMessage = null, startFlowOptions = {}) {
-        await this.client.startFlow(this.flow, sessionId, { initialMessage }, startFlowOptions);
+    async startSession(sessionId, initialMessage = null, startFlowOptions = {}, sessionSettings = null) {
+        if (sessionSettings !== null) {
+            validateSessionSettings(sessionSettings);
+        }
+        await this.client.startFlow(this.flow, sessionId, { initialMessage, sessionSettings }, startFlowOptions);
+    }
+    /**
+     * Calls `update_session_settings`.
+     * @param sessionId - Session Flow ID.
+     * @param sessionSettings - The complete new settings; `{}` clears them.
+     * @returns The RPC result: `false` before the session initialized or for settings over the limit.
+     */
+    updateSessionSettings(sessionId, sessionSettings) {
+        return this.client.invokeRPC(this.flow.updateSessionSettings, sessionId, { sessionSettings });
     }
     /**
      * Calls `send_user_message`.
      * @param sessionId - Session Flow ID.
      * @param text - Message text.
-     * @returns The RPC result: `false` for blank text.
+     * @param planMode - Whether the message starts a planning turn. Defaults to `false`.
+     * @returns The RPC result: `false` for blank text, or for a `planMode` message when plan mode is off.
      */
-    sendUserMessage(sessionId, text) {
-        return this.client.invokeRPC(this.flow.sendUserMessage, sessionId, { text });
+    sendUserMessage(sessionId, text, planMode = false) {
+        return this.client.invokeRPC(this.flow.sendUserMessage, sessionId, { text, planMode });
+    }
+    /**
+     * Calls `execute_plan`, retrying an `RpcLockConflictError` for up to 30 seconds.
+     * @param sessionId - Session Flow ID.
+     * @param revision - Plan revision to execute.
+     * @returns The RPC result: `false` when the revision is stale, already pending, or the session is busy.
+     */
+    executePlan(sessionId, revision) {
+        return retryLockConflicts(() => this.client.invokeRPC(this.flow.executePlan, sessionId, { revision }));
+    }
+    /**
+     * Calls `steer_user_message` with new text; while no turn is active, the RPC queues it.
+     * @param sessionId - Session Flow ID.
+     * @param text - Text of the steered message.
+     * @returns The RPC result: `false` for blank text or a turn that does not accept steering.
+     */
+    steerUserMessage(sessionId, text) {
+        return this.client.invokeRPC(this.flow.steerUserMessage, sessionId, { messageId: null, text });
+    }
+    /**
+     * Calls `steer_user_message` with a queued message's ID, which moves that message.
+     * @param sessionId - Session Flow ID.
+     * @param messageId - {@link PendingUserMessage.messageId} of a queued message.
+     * @returns The RPC result: `false` when the message is no longer queued.
+     * @throws {ChannelMessageNotFoundError} When the session consumed the message while the RPC ran.
+     */
+    steerQueuedMessage(sessionId, messageId) {
+        return this.client.invokeRPC(this.flow.steerUserMessage, sessionId, { messageId, text: null });
+    }
+    /**
+     * Calls `delete_queued_message`.
+     * @param sessionId - Session Flow ID.
+     * @param messageId - {@link PendingUserMessage.messageId} of a queued message.
+     * @returns The RPC result: `false` when the message is no longer queued.
+     * @throws {ChannelMessageNotFoundError} When the session consumed the message while the RPC ran.
+     */
+    deleteQueuedMessage(sessionId, messageId) {
+        return this.client.invokeRPC(this.flow.deleteQueuedMessage, sessionId, { messageId });
+    }
+    /**
+     * Calls `cancel_turn`, retrying an `RpcLockConflictError` for up to 30 seconds.
+     * @param sessionId - Session Flow ID.
+     * @param turnId - The turn to stop, or `null` for the active turn. Defaults to `null`.
+     * @returns The RPC result: `false` when no turn is active, `turnId` names another turn, or the turn does not
+     * accept cancellation.
+     */
+    cancelTurn(sessionId, turnId = null) {
+        return retryLockConflicts(() => this.client.invokeRPC(this.flow.cancelTurn, sessionId, { turnId }));
     }
     /**
      * Calls `resolve_interrupt`, retrying an `RpcLockConflictError` for up to 30 seconds.
@@ -70,23 +134,18 @@ export class AgentSessionTestClient {
      * @param rejectionMessage - Text shown to the model on rejection. Defaults to `null`.
      * @returns The RPC result: `false` when the interrupt was not pending.
      */
-    async resolveInterrupt(sessionId, interruptId, approved, rejectionMessage = null) {
-        const deadline = Date.now() + lockConflictRetryTimeoutMs;
-        for (;;) {
-            try {
-                return await this.client.invokeRPC(this.flow.resolveInterrupt, sessionId, {
-                    interruptId,
-                    approved,
-                    rejectionMessage,
-                });
-            }
-            catch (error) {
-                if (!(error instanceof RpcLockConflictError) || Date.now() >= deadline) {
-                    throw error;
-                }
-            }
-            await delay(lockConflictRetryIntervalMs);
-        }
+    resolveInterrupt(sessionId, interruptId, approved, rejectionMessage = null) {
+        return retryLockConflicts(() => this.client.invokeRPC(this.flow.resolveInterrupt, sessionId, { interruptId, approved, rejectionMessage }));
+    }
+    /**
+     * Calls `answer_question`, retrying an `RpcLockConflictError` for up to 30 seconds.
+     * @param sessionId - Session Flow ID.
+     * @param interruptId - Pending `question` interrupt to answer.
+     * @param answer - The answer text.
+     * @returns The RPC result: `false` when the question was not pending or the answer was refused.
+     */
+    answerQuestion(sessionId, interruptId, answer) {
+        return retryLockConflicts(() => this.client.invokeRPC(this.flow.answerQuestion, sessionId, { interruptId, answer }));
     }
     /**
      * Calls `get_agent_snapshot`.
@@ -214,4 +273,18 @@ export class AgentSessionTestClient {
         return newestFirst.reverse();
     }
 }
+async function retryLockConflicts(invoke) {
+    const deadline = Date.now() + lockConflictRetryTimeoutMs;
+    for (;;) {
+        try {
+            return await invoke();
+        }
+        catch (error) {
+            if (!(error instanceof RpcLockConflictError) || Date.now() >= deadline) {
+                throw error;
+            }
+        }
+        await delay(lockConflictRetryIntervalMs);
+    }
+}
 //# sourceMappingURL=agent-session-test-client.js.map

package/dist/src/testing/agent-session-test-client.js.map

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

package/dist/src/testing/index.d.ts

@@ -3,5 +3,6 @@ export { AgentTestEnvironment, type AgentTestEnvironmentOptions, } from "./agent
 export { KillableWorkerProcess, agentWorkerBlobCacheDirectoryVariable, agentWorkerReadyLine, agentWorkerServerAddressVariable, runAgentWorkerProcess, type KillableWorkerProcessOptions, } from "./agent-worker-process.js";
 export { FileGate, InvocationLog } from "./coordination.js";
 export { pollUntil, type PollOptions } from "./polling.js";
+export { ScriptedModelClient, scriptedModelApi, scriptedModelProvider, type ScriptedModelReply, type ScriptedModelResponder, type ScriptedToolCall, } from "./scripted-model-client.js";
 export { executeCompletedEvent, readStepHistory, waitForCompletedEvent, type ReadStepHistoryOptions, type StepHistoryEntry, } from "./step-history.js";
 export { PrivateDexEngine, findFreeLoopbackPort, findFreeLoopbackPorts, type PrivateDexEngineOptions, } from "./private-dex-engine.js";

package/dist/src/testing/index.js

@@ -10,6 +10,7 @@ export { AgentTestEnvironment, } from "./agent-test-environment.js";
 export { KillableWorkerProcess, agentWorkerBlobCacheDirectoryVariable, agentWorkerReadyLine, agentWorkerServerAddressVariable, runAgentWorkerProcess, } from "./agent-worker-process.js";
 export { FileGate, InvocationLog } from "./coordination.js";
 export { pollUntil } from "./polling.js";
+export { ScriptedModelClient, scriptedModelApi, scriptedModelProvider, } from "./scripted-model-client.js";
 export { executeCompletedEvent, readStepHistory, waitForCompletedEvent, } from "./step-history.js";
 export { PrivateDexEngine, findFreeLoopbackPort, findFreeLoopbackPorts, } from "./private-dex-engine.js";
 //# sourceMappingURL=index.js.map

package/dist/src/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,sBAAsB,GAEvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,qCAAqC,EACrC,oBAAoB,EACpB,gCAAgC,EAChC,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAoB,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,sBAAsB,GAEvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,qCAAqC,EACrC,oBAAoB,EACpB,gCAAgC,EAChC,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAoB,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GAItB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC"}

package/dist/src/testing/private-dex-engine.d.ts

@@ -17,6 +17,15 @@ export interface PrivateDexEngineOptions {
     readonly stateDirectory?: string;
     /** Milliseconds to wait for the engine to report readiness. Defaults to 60,000. */
     readonly readyTimeoutMs?: number;
+    /**
+     * Path of a `dex-server-zd` YAML file with configuration overrides, passed as `dexcli dev -zd-config`.
+     * Use it to test server settings, such as `streamStore: { backend: disabled }`, which drops
+     * Step Stream writes. When omitted, the engine gets a file that sets only
+     * `dev.durabilityMode: processCrashSafe`, which skips fsync and survives a process kill but not a host
+     * crash. A file of your own replaces it, so set `dev.durabilityMode` there too, or the engine uses the
+     * slower `strict` default of `dex-server-zd` 0.1.18 and later.
+     */
+    readonly serverZdConfigPath?: string;
 }
 /**
  * A private `dexcli dev --engine zd` instance on free loopback ports, owned by one test process.

package/dist/src/testing/private-dex-engine.js

@@ -5,13 +5,15 @@
 // See the LICENSE file in the repository root.
 //
 // SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
-import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { ChildProcessGroup } from "./child-process-group.js";
 const engineReadyLine = "Dex development environment is ready";
 const startAttempts = 3;
+// A config file also works with dexcli releases that predate --durability.
+const processCrashSafeServerZdConfig = "dev:\n  durabilityMode: processCrashSafe\n";
 /**
  * A private `dexcli dev --engine zd` instance on free loopback ports, owned by one test process.
  *
@@ -69,6 +71,11 @@ export class PrivateDexEngine {
         const stateDirectory = options.stateDirectory ?? mkdtempSync(join(tmpdir(), "dex-agents-engine-"));
         mkdirSync(stateDirectory, { recursive: true });
         const logPath = join(stateDirectory, "dexcli.log");
+        let configPath = options.serverZdConfigPath;
+        if (configPath === undefined) {
+            configPath = join(stateDirectory, "zd-overrides.yaml");
+            writeFileSync(configPath, processCrashSafeServerZdConfig);
+        }
         let lastFailure;
         for (let attempt = 1; attempt <= startAttempts; attempt += 1) {
             const [dexPort, webPort] = await findFreeLoopbackPorts(2);
@@ -94,6 +101,7 @@ export class PrivateDexEngine {
             if (serverZdPath !== undefined) {
                 commandArguments.push("-zd-binary", serverZdPath);
             }
+            commandArguments.push("-zd-config", configPath);
             try {
                 const processGroup = await ChildProcessGroup.start({
                     description: "dexcli dev",

package/dist/src/testing/private-dex-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"private-dex-engine.js","sourceRoot":"","sources":["../../../src/testing/private-dex-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"private-dex-engine.js","sourceRoot":"","sources":["../../../src/testing/private-dex-engine.ts"],"names":[],"mappings":"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"}

package/dist/src/testing/scripted-model-client.d.ts

@@ -0,0 +1 @@
+export { ScriptedModelClient, scriptedModelApi, scriptedModelProvider, type ScriptedModelReply, type ScriptedModelResponder, type ScriptedToolCall, } from "../stepwise/scripted-model-client.js";

package/dist/src/testing/scripted-model-client.js

@@ -0,0 +1,10 @@
+// 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
+// The scripted model client lives in the stepwise entry point; this path keeps the 0.1.0 module.
+export { ScriptedModelClient, scriptedModelApi, scriptedModelProvider, } from "../stepwise/scripted-model-client.js";
+//# sourceMappingURL=scripted-model-client.js.map

package/dist/src/testing/scripted-model-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripted-model-client.js","sourceRoot":"","sources":["../../../src/testing/scripted-model-client.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAG1D,iGAAiG;AACjG,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GAItB,MAAM,sCAAsC,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;