@superdurable/dex-agents 0.0.0-stage → 0.2.0

package/dist/src/testing/agent-session-test-client.d.ts

@@ -0,0 +1,205 @@
+import { type Client, type StartFlowOptions } from "@superdurable/dex";
+import type { AgentFrameworkRunner, DeferredToolOutcome } from "../agent-framework-runner.js";
+import type { AgentSessionFlow } from "../agent-session-flow.js";
+import type { AgentEvent, AgentInterrupt, AgentMessagesPage, AgentSnapshot, AgentState, AgentToolCallRecord, SessionSettings } from "../agent-session-values.js";
+/** Options of the `waitFor*` methods of {@link AgentSessionTestClient}. */
+export interface AgentSessionWaitOptions {
+    /** Total milliseconds to wait. Defaults to 60,000. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Typed Client calls for one agent session Flow, with waits suited to integration tests.
+ *
+ * RPC methods need a running Worker. The `read*` and `waitFor*` methods use `Client.getAttributes`,
+ * which reads committed Attributes without a Worker, so they also work while a killed Worker is down.
+ *
+ * @example
+ * ```ts
+ * const sessions = new AgentSessionTestClient(environment.client, flow);
+ * await sessions.startSession(sessionId, "send the report");
+ * const interrupt = await sessions.waitForPendingInterrupt(sessionId, "send_email");
+ * assert.equal(await sessions.resolveInterrupt(sessionId, interrupt.interruptId, true), true);
+ * const state = await sessions.waitForCompletedTurns(sessionId, 1);
+ * const snapshot = await sessions.getAgentSnapshot(sessionId);
+ * ```
+ */
+export declare class AgentSessionTestClient {
+    /** Client used for every call. */
+    readonly client: Client;
+    /** Flow whose sessions this helper drives. */
+    readonly flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>;
+    /**
+     * Creates the helper.
+     * @param client - Client whose Registry contains `flow`.
+     * @param flow - The agent session Flow, the same object registered in the Client's Registry.
+     */
+    constructor(
+    /** Client used for every call. */
+    client: Client, 
+    /** Flow whose sessions this helper drives. */
+    flow: AgentSessionFlow<AgentFrameworkRunner<DeferredToolOutcome>>);
+    /**
+     * Starts a session.
+     * @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.
+     */
+    startSession(sessionId: string, initialMessage?: string | null, startFlowOptions?: StartFlowOptions, sessionSettings?: SessionSettings | null): Promise<void>;
+    /**
+     * 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: string, sessionSettings: SessionSettings): Promise<boolean>;
+    /**
+     * Calls `send_user_message`.
+     * @param sessionId - Session Flow ID.
+     * @param text - Message 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: string, text: string, planMode?: boolean): Promise<boolean>;
+    /**
+     * 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: string, revision: number): Promise<boolean>;
+    /**
+     * 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: string, text: string): Promise<boolean>;
+    /**
+     * 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: string, messageId: string): Promise<boolean>;
+    /**
+     * 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: string, messageId: string): Promise<boolean>;
+    /**
+     * 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: string, turnId?: string | null): Promise<boolean>;
+    /**
+     * Calls `resolve_interrupt`, retrying an `RpcLockConflictError` for up to 30 seconds.
+     * @param sessionId - Session Flow ID.
+     * @param interruptId - Interrupt to resolve.
+     * @param approved - Whether the tool call may run.
+     * @param rejectionMessage - Text shown to the model on rejection. Defaults to `null`.
+     * @returns The RPC result: `false` when the interrupt was not pending.
+     */
+    resolveInterrupt(sessionId: string, interruptId: string, approved: boolean, rejectionMessage?: string | null): Promise<boolean>;
+    /**
+     * 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: string, interruptId: string, answer: string): Promise<boolean>;
+    /**
+     * Calls `get_agent_snapshot`.
+     * @param sessionId - Session Flow ID.
+     * @returns The snapshot.
+     */
+    getAgentSnapshot(sessionId: string): Promise<AgentSnapshot>;
+    /**
+     * Calls `list_agent_messages`.
+     * @param sessionId - Session Flow ID.
+     * @param beforeSequence - Exclusive upper bound, or `null` for the newest page.
+     * @param limit - Page size, clamped by the session to 1..200.
+     * @returns The page.
+     */
+    listAgentMessages(sessionId: string, beforeSequence: number | null, limit: number): Promise<AgentMessagesPage>;
+    /**
+     * Reads the committed `AgentState` without a Worker.
+     * @param sessionId - Session Flow ID.
+     * @returns The state, or `undefined` before `StartAgentSession` committed.
+     */
+    readAgentState(sessionId: string): Promise<AgentState | undefined>;
+    /**
+     * Reads one committed tool call record without a Worker.
+     * @param sessionId - Session Flow ID.
+     * @param toolCallId - Tool call ID.
+     * @returns The record, or `undefined` when it does not exist or its turn completed.
+     */
+    readToolCall(sessionId: string, toolCallId: string): Promise<AgentToolCallRecord | undefined>;
+    /**
+     * Reads the committed `PendingInterrupts` without a Worker.
+     * @param sessionId - Session Flow ID.
+     * @returns The pending interrupts, or an empty array.
+     */
+    readPendingInterrupts(sessionId: string): Promise<readonly AgentInterrupt[]>;
+    /**
+     * Polls `get_agent_snapshot` until a predicate holds; RPC failures while no Worker runs count as not ready.
+     * @param sessionId - Session Flow ID.
+     * @param predicate - Returns `true` for the awaited snapshot.
+     * @param description - What is awaited, for the timeout error.
+     * @param options - Timeout.
+     * @returns The first matching snapshot.
+     * @throws {Error} When the timeout passes.
+     */
+    waitForAgentSnapshot(sessionId: string, predicate: (snapshot: AgentSnapshot) => boolean, description: string, options?: AgentSessionWaitOptions): Promise<AgentSnapshot>;
+    /**
+     * Polls the committed `AgentState` until a predicate holds.
+     * @param sessionId - Session Flow ID.
+     * @param predicate - Returns `true` for the awaited state.
+     * @param description - What is awaited, for the timeout error.
+     * @param options - Timeout.
+     * @returns The first matching state.
+     * @throws {Error} When the timeout passes.
+     */
+    waitForAgentState(sessionId: string, predicate: (state: AgentState) => boolean, description: string, options?: AgentSessionWaitOptions): Promise<AgentState>;
+    /**
+     * Waits until the session is idle after at least `turnCount` completed or failed turns.
+     * @param sessionId - Session Flow ID.
+     * @param turnCount - Minimum `turnCount`.
+     * @param options - Timeout.
+     * @returns The idle state.
+     */
+    waitForCompletedTurns(sessionId: string, turnCount: number, options?: AgentSessionWaitOptions): Promise<AgentState>;
+    /**
+     * Polls `PendingInterrupts` until an interrupt appears.
+     * @param sessionId - Session Flow ID.
+     * @param toolName - Tool whose interrupt is awaited, or `undefined` for any tool.
+     * @param options - Timeout.
+     * @returns The first matching pending interrupt.
+     */
+    waitForPendingInterrupt(sessionId: string, toolName?: string, options?: AgentSessionWaitOptions): Promise<AgentInterrupt>;
+    /**
+     * Polls one tool call record until a predicate holds.
+     * @param sessionId - Session Flow ID.
+     * @param toolCallId - Tool call ID.
+     * @param predicate - Returns `true` for the awaited record.
+     * @param options - Timeout.
+     * @returns The first matching record.
+     */
+    waitForToolCall(sessionId: string, toolCallId: string, predicate: (toolCall: AgentToolCallRecord) => boolean, options?: AgentSessionWaitOptions): Promise<AgentToolCallRecord>;
+    /**
+     * Reads every retained `AgentEvents` message, oldest first.
+     * @param sessionId - Session Flow ID.
+     * @returns The retained events; trimming may have removed the oldest.
+     */
+    listAgentEvents(sessionId: string): Promise<AgentEvent[]>;
+}

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

@@ -0,0 +1,290 @@
+// 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 { RpcLockConflictError } from "@superdurable/dex";
+import { validateSessionSettings } from "../agent-session-settings.js";
+import { pollUntil } from "./polling.js";
+const lockConflictRetryTimeoutMs = 30_000;
+const lockConflictRetryIntervalMs = 50;
+const streamPageSize = 500;
+/**
+ * Typed Client calls for one agent session Flow, with waits suited to integration tests.
+ *
+ * RPC methods need a running Worker. The `read*` and `waitFor*` methods use `Client.getAttributes`,
+ * which reads committed Attributes without a Worker, so they also work while a killed Worker is down.
+ *
+ * @example
+ * ```ts
+ * const sessions = new AgentSessionTestClient(environment.client, flow);
+ * await sessions.startSession(sessionId, "send the report");
+ * const interrupt = await sessions.waitForPendingInterrupt(sessionId, "send_email");
+ * assert.equal(await sessions.resolveInterrupt(sessionId, interrupt.interruptId, true), true);
+ * const state = await sessions.waitForCompletedTurns(sessionId, 1);
+ * const snapshot = await sessions.getAgentSnapshot(sessionId);
+ * ```
+ */
+export class AgentSessionTestClient {
+    client;
+    flow;
+    /**
+     * Creates the helper.
+     * @param client - Client whose Registry contains `flow`.
+     * @param flow - The agent session Flow, the same object registered in the Client's Registry.
+     */
+    constructor(
+    /** Client used for every call. */
+    client, 
+    /** Flow whose sessions this helper drives. */
+    flow) {
+        this.client = client;
+        this.flow = flow;
+    }
+    /**
+     * Starts a session.
+     * @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 = {}, 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.
+     * @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, 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.
+     * @param sessionId - Session Flow ID.
+     * @param interruptId - Interrupt to resolve.
+     * @param approved - Whether the tool call may run.
+     * @param rejectionMessage - Text shown to the model on rejection. Defaults to `null`.
+     * @returns The RPC result: `false` when the interrupt was not pending.
+     */
+    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`.
+     * @param sessionId - Session Flow ID.
+     * @returns The snapshot.
+     */
+    getAgentSnapshot(sessionId) {
+        return this.client.invokeRPC(this.flow.getAgentSnapshot, sessionId);
+    }
+    /**
+     * Calls `list_agent_messages`.
+     * @param sessionId - Session Flow ID.
+     * @param beforeSequence - Exclusive upper bound, or `null` for the newest page.
+     * @param limit - Page size, clamped by the session to 1..200.
+     * @returns The page.
+     */
+    listAgentMessages(sessionId, beforeSequence, limit) {
+        return this.client.invokeRPC(this.flow.listAgentMessages, sessionId, { beforeSequence, limit });
+    }
+    /**
+     * Reads the committed `AgentState` without a Worker.
+     * @param sessionId - Session Flow ID.
+     * @returns The state, or `undefined` before `StartAgentSession` committed.
+     */
+    async readAgentState(sessionId) {
+        const [state] = await this.client.getAttributes(sessionId, this.flow.agentState);
+        return state;
+    }
+    /**
+     * Reads one committed tool call record without a Worker.
+     * @param sessionId - Session Flow ID.
+     * @param toolCallId - Tool call ID.
+     * @returns The record, or `undefined` when it does not exist or its turn completed.
+     */
+    async readToolCall(sessionId, toolCallId) {
+        const [toolCall] = await this.client.getAttributes(sessionId, this.flow.agentToolCalls.instance(toolCallId));
+        return toolCall;
+    }
+    /**
+     * Reads the committed `PendingInterrupts` without a Worker.
+     * @param sessionId - Session Flow ID.
+     * @returns The pending interrupts, or an empty array.
+     */
+    async readPendingInterrupts(sessionId) {
+        const [interrupts] = await this.client.getAttributes(sessionId, this.flow.pendingInterrupts);
+        return interrupts ?? [];
+    }
+    /**
+     * Polls `get_agent_snapshot` until a predicate holds; RPC failures while no Worker runs count as not ready.
+     * @param sessionId - Session Flow ID.
+     * @param predicate - Returns `true` for the awaited snapshot.
+     * @param description - What is awaited, for the timeout error.
+     * @param options - Timeout.
+     * @returns The first matching snapshot.
+     * @throws {Error} When the timeout passes.
+     */
+    waitForAgentSnapshot(sessionId, predicate, description, options = {}) {
+        return pollUntil(async () => {
+            const snapshot = await this.getAgentSnapshot(sessionId);
+            return predicate(snapshot) ? snapshot : undefined;
+        }, { description: `${description} in session ${sessionId}`, ...options });
+    }
+    /**
+     * Polls the committed `AgentState` until a predicate holds.
+     * @param sessionId - Session Flow ID.
+     * @param predicate - Returns `true` for the awaited state.
+     * @param description - What is awaited, for the timeout error.
+     * @param options - Timeout.
+     * @returns The first matching state.
+     * @throws {Error} When the timeout passes.
+     */
+    waitForAgentState(sessionId, predicate, description, options = {}) {
+        return pollUntil(async () => {
+            const state = await this.readAgentState(sessionId);
+            return state !== undefined && predicate(state) ? state : undefined;
+        }, { description: `${description} in session ${sessionId}`, ...options });
+    }
+    /**
+     * Waits until the session is idle after at least `turnCount` completed or failed turns.
+     * @param sessionId - Session Flow ID.
+     * @param turnCount - Minimum `turnCount`.
+     * @param options - Timeout.
+     * @returns The idle state.
+     */
+    waitForCompletedTurns(sessionId, turnCount, options = {}) {
+        return this.waitForAgentState(sessionId, (state) => state.status === "waiting_for_user_message" && state.turnCount >= turnCount, `${turnCount} finished turns`, options);
+    }
+    /**
+     * Polls `PendingInterrupts` until an interrupt appears.
+     * @param sessionId - Session Flow ID.
+     * @param toolName - Tool whose interrupt is awaited, or `undefined` for any tool.
+     * @param options - Timeout.
+     * @returns The first matching pending interrupt.
+     */
+    waitForPendingInterrupt(sessionId, toolName, options = {}) {
+        return pollUntil(async () => (await this.readPendingInterrupts(sessionId)).find((interrupt) => toolName === undefined || interrupt.toolName === toolName), { description: `pending interrupt for ${toolName ?? "any tool"} in session ${sessionId}`, ...options });
+    }
+    /**
+     * Polls one tool call record until a predicate holds.
+     * @param sessionId - Session Flow ID.
+     * @param toolCallId - Tool call ID.
+     * @param predicate - Returns `true` for the awaited record.
+     * @param options - Timeout.
+     * @returns The first matching record.
+     */
+    waitForToolCall(sessionId, toolCallId, predicate, options = {}) {
+        return pollUntil(async () => {
+            const toolCall = await this.readToolCall(sessionId, toolCallId);
+            return toolCall !== undefined && predicate(toolCall) ? toolCall : undefined;
+        }, { description: `tool call ${toolCallId} in session ${sessionId}`, ...options });
+    }
+    /**
+     * Reads every retained `AgentEvents` message, oldest first.
+     * @param sessionId - Session Flow ID.
+     * @returns The retained events; trimming may have removed the oldest.
+     */
+    async listAgentEvents(sessionId) {
+        const newestFirst = [];
+        let pageToken = "";
+        do {
+            const page = await this.client.listStreamMessages(sessionId, this.flow.agentEvents, streamPageSize, pageToken);
+            newestFirst.push(...page.messages.map((message) => message.value));
+            pageToken = page.nextPageToken;
+        } while (pageToken !== "");
+        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

@@ -0,0 +1 @@
+{"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/agent-test-environment.d.ts

@@ -0,0 +1,52 @@
+import { Client, Registry, Worker, type Flow } from "@superdurable/dex";
+/** Options of {@link AgentTestEnvironment.start}. */
+export interface AgentTestEnvironmentOptions {
+    /** Dex Server address, usually {@link PrivateDexEngine.serverAddress}. */
+    readonly serverAddress: string;
+    /** Flows registered in the environment's Registry. */
+    readonly flows: readonly Flow<any>[];
+    /**
+     * Whether to run a pull Worker in this process. Pass `false` when the Worker runs in a
+     * {@link KillableWorkerProcess}; the Client still needs the same Flows in its Registry.
+     */
+    readonly isWorkerInProcess: boolean;
+}
+/**
+ * A Registry, BlobCache, Client, and optional in-process Worker for one test file.
+ *
+ * @example
+ * ```ts
+ * const environment = await AgentTestEnvironment.start({
+ *   serverAddress: engine.serverAddress, flows: [flow], isWorkerInProcess: true });
+ * try {
+ *   const sessions = new AgentSessionTestClient(environment.client, flow);
+ *   // ...
+ * } finally {
+ *   await environment.close();
+ * }
+ * ```
+ */
+export declare class AgentTestEnvironment {
+    /** Registry shared by the Client and the in-process Worker. */
+    readonly registry: Registry;
+    /** Client connected to the server. */
+    readonly client: Client;
+    /** In-process Worker, or `undefined` when the Worker runs elsewhere. */
+    readonly worker: Worker | undefined;
+    private readonly blobCache;
+    private readonly cacheDirectory;
+    private constructor();
+    /**
+     * Creates the environment and, when requested, starts the Worker and waits for its registration.
+     * @param options - Server address, Flows, and Worker placement.
+     * @returns The ready environment.
+     * @throws {FlowDefinitionError} When the Flows are invalid.
+     * @throws {Error} When the Worker cannot register within 30 seconds.
+     */
+    static start(options: AgentTestEnvironmentOptions): Promise<AgentTestEnvironment>;
+    /**
+     * Closes the Client, the in-process Worker, and the BlobCache, then deletes the cache directory.
+     * @returns A Promise that resolves after everything closed.
+     */
+    close(): Promise<void>;
+}

package/dist/src/testing/agent-test-environment.js

@@ -0,0 +1,86 @@
+// 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 { randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client, Registry, Worker, openBlobCache, } from "@superdurable/dex";
+/**
+ * A Registry, BlobCache, Client, and optional in-process Worker for one test file.
+ *
+ * @example
+ * ```ts
+ * const environment = await AgentTestEnvironment.start({
+ *   serverAddress: engine.serverAddress, flows: [flow], isWorkerInProcess: true });
+ * try {
+ *   const sessions = new AgentSessionTestClient(environment.client, flow);
+ *   // ...
+ * } finally {
+ *   await environment.close();
+ * }
+ * ```
+ */
+export class AgentTestEnvironment {
+    registry;
+    client;
+    worker;
+    blobCache;
+    cacheDirectory;
+    constructor(
+    /** Registry shared by the Client and the in-process Worker. */
+    registry, 
+    /** Client connected to the server. */
+    client, 
+    /** In-process Worker, or `undefined` when the Worker runs elsewhere. */
+    worker, blobCache, cacheDirectory) {
+        this.registry = registry;
+        this.client = client;
+        this.worker = worker;
+        this.blobCache = blobCache;
+        this.cacheDirectory = cacheDirectory;
+    }
+    /**
+     * Creates the environment and, when requested, starts the Worker and waits for its registration.
+     * @param options - Server address, Flows, and Worker placement.
+     * @returns The ready environment.
+     * @throws {FlowDefinitionError} When the Flows are invalid.
+     * @throws {Error} When the Worker cannot register within 30 seconds.
+     */
+    static async start(options) {
+        const registry = new Registry(options.flows);
+        const cacheDirectory = mkdtempSync(join(tmpdir(), "dex-agents-test-cache-"));
+        const blobCache = openBlobCache({ directory: cacheDirectory, maxBytes: 64 * 1024 * 1024 });
+        let worker;
+        if (options.isWorkerInProcess) {
+            worker = new Worker(registry, blobCache, {
+                serverAddress: options.serverAddress,
+                // Parallel tool Steps must not depend on the CI machine's CPU count.
+                pull: { appWorkerID: `dex-agents-test-worker-${randomUUID()}`, maxConcurrentTasks: 8 },
+            });
+            await worker.start();
+            await worker.waitPullRegistered({ timeoutMs: 30_000 });
+        }
+        const client = new Client(registry, blobCache, { serverAddress: options.serverAddress });
+        return new AgentTestEnvironment(registry, client, worker, blobCache, cacheDirectory);
+    }
+    /**
+     * Closes the Client, the in-process Worker, and the BlobCache, then deletes the cache directory.
+     * @returns A Promise that resolves after everything closed.
+     */
+    async close() {
+        try {
+            await this.client.close();
+            await this.worker?.close();
+            this.blobCache.close();
+        }
+        finally {
+            rmSync(this.cacheDirectory, { recursive: true, force: true });
+        }
+    }
+}
+//# sourceMappingURL=agent-test-environment.js.map

package/dist/src/testing/agent-test-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-test-environment.js","sourceRoot":"","sources":["../../../src/testing/agent-test-environment.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,MAAM,EACN,QAAQ,EACR,MAAM,EACN,aAAa,GAGd,MAAM,mBAAmB,CAAC;AAe3B;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,oBAAoB;IAGb;IAEA;IAEA;IACC;IACA;IARnB;IACE,+DAA+D;IAC/C,QAAkB;IAClC,sCAAsC;IACtB,MAAc;IAC9B,wEAAwE;IACxD,MAA0B,EACzB,SAAoB,EACpB,cAAsB;QANvB,aAAQ,GAAR,QAAQ,CAAU;QAElB,WAAM,GAAN,MAAM,CAAQ;QAEd,WAAM,GAAN,MAAM,CAAoB;QACzB,cAAS,GAAT,SAAS,CAAW;QACpB,mBAAc,GAAd,cAAc,CAAQ;IACtC,CAAC;IAEJ;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAoC;QAC5D,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,wBAAwB,CAAC,CAAC,CAAC;QAC7E,MAAM,SAAS,GAAG,aAAa,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;QAC3F,IAAI,MAA0B,CAAC;QAC/B,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAC9B,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE;gBACvC,aAAa,EAAE,OAAO,CAAC,aAAa;gBACpC,qEAAqE;gBACrE,IAAI,EAAE,EAAE,WAAW,EAAE,0BAA0B,UAAU,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE;aACvF,CAAC,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,kBAAkB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;QACzF,OAAO,IAAI,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;IACvF,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,KAAK;QAChB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;CACF"}