@superdurable/dex-agents 0.0.0-stage → 0.1.0

package/dist/src/agent-session-values.js

@@ -0,0 +1,127 @@
+// 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
+/**
+ * Returns usage with every counter at zero.
+ *
+ * @returns A new {@link AgentUsage} whose counters are all `0`.
+ */
+export function emptyAgentUsage() {
+    return {
+        modelCalls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedInputTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+/**
+ * Adds two usage values counter by counter.
+ *
+ * @example
+ * ```ts
+ * let usage = emptyAgentUsage();
+ * usage = addAgentUsage(usage, { ...emptyAgentUsage(), modelCalls: 1, inputTokens: 120, outputTokens: 30 });
+ * ```
+ * @param left - First usage value.
+ * @param right - Second usage value.
+ * @returns A new {@link AgentUsage} holding the sums; neither input is changed.
+ */
+export function addAgentUsage(left, right) {
+    return {
+        modelCalls: left.modelCalls + right.modelCalls,
+        inputTokens: left.inputTokens + right.inputTokens,
+        outputTokens: left.outputTokens + right.outputTokens,
+        cachedInputTokens: left.cachedInputTokens + right.cachedInputTokens,
+        reasoningTokens: left.reasoningTokens + right.reasoningTokens,
+    };
+}
+/**
+ * Reports whether a tool call status is final.
+ *
+ * @param status - Status to classify.
+ * @returns `true` for `rejected`, `succeeded`, `failed`, and `outcome_unknown`; `false` for
+ * `awaiting_approval` and `approved`.
+ */
+export function isFinalToolCallStatus(status) {
+    return status !== "awaiting_approval" && status !== "approved";
+}
+/** Tool result text the model sees for an `outcome_unknown` call; the same text as the Python core. */
+export const outcomeUnknownToolResult = "The tool call's outcome is unknown: it stopped without returning a result, so it may " +
+    "or may not have taken effect. It will not be retried automatically.";
+/** First line of the note `RecordTurnFailure` stores after a failed turn ran tools. */
+export const turnFailureNoteHeader = "[Dex] The previous turn failed after these tool calls ran:";
+/** Last line of that note. */
+export const turnFailureNoteFooter = "Do not repeat these tool calls unless the user asks again.";
+/** Tool result text the model sees for a rejection without a message; the same text as the Python core. */
+export const defaultRejectionToolResult = "The user rejected this tool call.";
+/** Rejection message recorded when an approval deadline passes. */
+export const approvalDeadlinePassed = "approval deadline passed";
+/**
+ * Returns the note text that tells the model what a failed turn already did.
+ *
+ * `RecordTurnFailure` stores this note through {@link AgentFrameworkRunner.buildUserMessage} when a
+ * failed turn has final tool call records, as the failed turn's last message, so the next turn's model
+ * does not repeat a write. The text matches the Python core's `build_turn_failure_note`:
+ *
+ * ```text
+ * [Dex] The previous turn failed after these tool calls ran:
+ * - charge {"amount": 5} -> succeeded: charged 5
+ * Do not repeat these tool calls unless the user asks again.
+ * ```
+ *
+ * @param toolCalls - Final records of the failed turn; they are listed in `deferralOrder`.
+ * @returns {@link turnFailureNoteHeader}, one `- <toolName> <arguments> -> <status>: <outcome>` line
+ * per record, with the outcome from {@link describeToolCallOutcome}, and {@link turnFailureNoteFooter},
+ * joined with newlines.
+ * @throws {TypeError} When a record is not final.
+ */
+export function buildTurnFailureNote(toolCalls) {
+    const lines = [turnFailureNoteHeader];
+    for (const toolCall of [...toolCalls].sort((left, right) => left.deferralOrder - right.deferralOrder)) {
+        const outcome = describeToolCallOutcome(toolCall);
+        lines.push(`- ${toolCall.toolName} ${toolCall.arguments} -> ${toolCall.status}: ${outcome}`);
+    }
+    lines.push(turnFailureNoteFooter);
+    return lines.join("\n");
+}
+/**
+ * Returns the tool result text a runner shows the model for a final tool call record.
+ *
+ * Use it when resuming a framework whose tool result must be text. A runner whose framework has a
+ * native rejection, such as a rejection message argument, may pass `rejectionMessage` there instead.
+ * The texts match the Python core's `describe_tool_call_outcome`.
+ *
+ * @example
+ * ```ts
+ * const record = turn.recordedToolCall(pendingCallId);
+ * if (record !== undefined && isFinalToolCallStatus(record.status)) {
+ *   frameworkToolResult = describeToolCallOutcome(record);
+ * }
+ * ```
+ * @param toolCall - Record whose status is final.
+ * @returns The output for `succeeded`; `The tool call failed: <error>` for `failed`; the rejection
+ * message, or {@link defaultRejectionToolResult}, for `rejected`; {@link outcomeUnknownToolResult}
+ * for `outcome_unknown`.
+ * @throws {TypeError} When the record status is `awaiting_approval` or `approved`.
+ */
+export function describeToolCallOutcome(toolCall) {
+    switch (toolCall.status) {
+        case "succeeded":
+            return toolCall.output ?? "";
+        case "failed":
+            return `The tool call failed: ${toolCall.error ?? "unknown error"}`;
+        case "rejected":
+            return toolCall.rejectionMessage ?? defaultRejectionToolResult;
+        case "outcome_unknown":
+            return outcomeUnknownToolResult;
+        case "awaiting_approval":
+        case "approved":
+            throw new TypeError(`tool call ${toolCall.toolCallId} has no final outcome yet`);
+    }
+}
+//# sourceMappingURL=agent-session-values.js.map

package/dist/src/agent-session-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-values.js","sourceRoot":"","sources":["../../src/agent-session-values.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AA0S1D;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,CAAC;QACd,YAAY,EAAE,CAAC;QACf,iBAAiB,EAAE,CAAC;QACpB,eAAe,EAAE,CAAC;KACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,IAAgB,EAAE,KAAiB;IAC/D,OAAO;QACL,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;QAC9C,WAAW,EAAE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW;QACjD,YAAY,EAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY;QACpD,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,iBAAiB;QACnE,eAAe,EAAE,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA2B;IAC/D,OAAO,MAAM,KAAK,mBAAmB,IAAI,MAAM,KAAK,UAAU,CAAC;AACjE,CAAC;AAED,uGAAuG;AACvG,MAAM,CAAC,MAAM,wBAAwB,GACnC,uFAAuF;IACvF,qEAAqE,CAAC;AAExE,uFAAuF;AACvF,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAElG,8BAA8B;AAC9B,MAAM,CAAC,MAAM,qBAAqB,GAAG,4DAA4D,CAAC;AAElG,2GAA2G;AAC3G,MAAM,CAAC,MAAM,0BAA0B,GAAG,mCAAmC,CAAC;AAE9E,mEAAmE;AACnE,MAAM,CAAC,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAmC;IACtE,MAAM,KAAK,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACtC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QACtG,MAAM,OAAO,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,OAAO,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAuB;IAC7D,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxB,KAAK,WAAW;YACd,OAAO,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;QAC/B,KAAK,QAAQ;YACX,OAAO,yBAAyB,QAAQ,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC;QACtE,KAAK,UAAU;YACb,OAAO,QAAQ,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;QACjE,KAAK,iBAAiB;YACpB,OAAO,wBAAwB,CAAC;QAClC,KAAK,mBAAmB,CAAC;QACzB,KAAK,UAAU;YACb,MAAM,IAAI,SAAS,CAAC,aAAa,QAAQ,CAAC,UAAU,2BAA2B,CAAC,CAAC;IACrF,CAAC;AACH,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { ToolExecutionError, resolveToolPolicy, toolEffectFromMcpToolAnnotations, type AgentEventWriter, type AgentFrameworkRunner, type AgentTurnContext, type AgentTurnOutcome, type DeferredToolCall, type DeferredToolExecution, type McpToolAnnotations, type ResolvedToolPolicy, type ToolExecutionResult, type ToolPolicy, type TurnCompleted, type ToolCallsRequested, } from "./agent-framework-runner.js";
+export { createAgentSessionFlow, type AgentSessionFlow, type AgentSessionOptions, type ResolvedAgentSessionOptions, } from "./agent-session-flow.js";
+export { defaultAgentEventsCapacityBytes, messageSequenceKey, type AgentSessionPersistence, } from "./agent-session-persistence.js";
+export { addAgentUsage, approvalDeadlinePassed, buildTurnFailureNote, defaultRejectionToolResult, describeToolCallOutcome, emptyAgentUsage, isFinalToolCallStatus, outcomeUnknownToolResult, turnFailureNoteFooter, turnFailureNoteHeader, type AgentEvent, type AgentEventType, type AgentInterrupt, type AgentInterruptResolution, type AgentMessage, type AgentMessageRole, type AgentMessagesPage, type AgentSessionStartInput, type AgentSessionStatus, type AgentSnapshot, type AgentState, type AgentToolCall, type AgentToolCallStatus, type AgentUsage, type AgentUserMessage, type FrameworkMessage, type ListAgentMessagesInput, type ResolveInterruptInput, type ToolCallCompleted, type ToolEffect, } from "./agent-session-values.js";

package/dist/src/index.js

@@ -0,0 +1,12 @@
+// 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
+export { ToolExecutionError, resolveToolPolicy, toolEffectFromMcpToolAnnotations, } from "./agent-framework-runner.js";
+export { createAgentSessionFlow, } from "./agent-session-flow.js";
+export { defaultAgentEventsCapacityBytes, messageSequenceKey, } from "./agent-session-persistence.js";
+export { addAgentUsage, approvalDeadlinePassed, buildTurnFailureNote, defaultRejectionToolResult, describeToolCallOutcome, emptyAgentUsage, isFinalToolCallStatus, outcomeUnknownToolResult, turnFailureNoteFooter, turnFailureNoteHeader, } from "./agent-session-values.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gCAAgC,GAajC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,sBAAsB,GAIvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,GAEnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,GAqBtB,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,148 @@
+import { type Client, type StartFlowOptions } from "@superdurable/dex";
+import type { AgentSessionFlow } from "../agent-session-flow.js";
+import type { AgentEvent, AgentInterrupt, AgentMessagesPage, AgentSnapshot, AgentState, AgentToolCall } 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;
+    /**
+     * 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);
+    /**
+     * 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`.
+     * @returns A Promise that resolves after Dex accepted the start.
+     */
+    startSession(sessionId: string, initialMessage?: string | null, startFlowOptions?: StartFlowOptions): Promise<void>;
+    /**
+     * Calls `send_user_message`.
+     * @param sessionId - Session Flow ID.
+     * @param text - Message text.
+     * @returns The RPC result: `false` for blank text.
+     */
+    sendUserMessage(sessionId: string, text: string): 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 `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<AgentToolCall | 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: AgentToolCall) => boolean, options?: AgentSessionWaitOptions): Promise<AgentToolCall>;
+    /**
+     * 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,217 @@
+// 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 { 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`.
+     * @returns A Promise that resolves after Dex accepted the start.
+     */
+    async startSession(sessionId, initialMessage = null, startFlowOptions = {}) {
+        await this.client.startFlow(this.flow, sessionId, { initialMessage }, startFlowOptions);
+    }
+    /**
+     * Calls `send_user_message`.
+     * @param sessionId - Session Flow ID.
+     * @param text - Message text.
+     * @returns The RPC result: `false` for blank text.
+     */
+    sendUserMessage(sessionId, text) {
+        return this.client.invokeRPC(this.flow.sendUserMessage, sessionId, { text });
+    }
+    /**
+     * 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.
+     */
+    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);
+        }
+    }
+    /**
+     * 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();
+    }
+}
+//# 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>;
+}