@superdurable/dex-agents 0.1.0 → 0.3.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 { startAgentSession } from "../agent-session-start.js";
 import { pollUntil } from "./polling.js";
 const lockConflictRetryTimeoutMs = 30_000;
 const lockConflictRetryIntervalMs = 50;
@@ -48,19 +49,79 @@ 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) {
+        await startAgentSession(this.client, 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, 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.
      */
-    sendUserMessage(sessionId, text) {
-        return this.client.invokeRPC(this.flow.sendUserMessage, sessionId, { text });
+    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 +131,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 +270,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/context-window.d.ts

@@ -0,0 +1,194 @@
+import { type CompactionPolicy } from "../agent-context-compaction.js";
+import type { AgentMessage, AgentSnapshot } from "../agent-session-values.js";
+import { AgentSessionTestClient } from "./agent-session-test-client.js";
+import { KillableWorkerProcess } from "./agent-worker-process.js";
+/** Environment variable holding the JSON of {@link ContextWindowSettings}. */
+export declare const contextWindowSettingsVariable = "DEX_AGENTS_CONTEXT_WINDOW_SETTINGS";
+/** Tool that the scripted model calls once per turn. */
+export declare const contextWindowToolName = "lookup";
+/** Start of the error that the scripted model throws for an oversized request. */
+export declare const contextWindowExceededError = "scripted model: input exceeds the context window";
+/** Gate that holds a summary call of a range that names `gate-summary`. */
+export declare const contextWindowSummaryGateName = "summary";
+/**
+ * Sizes of the scripted model and the session of one context window test. A Worker child process reads them from
+ * {@link contextWindowSettingsVariable}.
+ */
+export interface ContextWindowSettings {
+    /** Context window of the scripted model, at four characters per token. */
+    readonly windowTokens: number;
+    /** Whether the session gets a compaction policy. */
+    readonly isCompactionEnabled: boolean;
+    /** Size of each tool result in characters. */
+    readonly toolOutputCharacters: number;
+    /** Size of each model answer in characters. */
+    readonly answerCharacters: number;
+    /** `AgentSessionOptions.messageWindowSize`. */
+    readonly messageWindowSize: number;
+    /** `AgentSessionOptions.messageChunkSize`. */
+    readonly messageChunkSize: number;
+    /** `AgentSessionOptions.retainedMessageLimit`; `null` keeps every message. */
+    readonly retainedMessageLimit: number | null;
+}
+/** The settings of a test that changes nothing. */
+export declare const defaultContextWindowSettings: ContextWindowSettings;
+/**
+ * Returns the Worker environment that carries the settings.
+ * @param settings - The test's settings.
+ * @returns One entry under {@link contextWindowSettingsVariable}.
+ */
+export declare function contextWindowSettingsEnvironment(settings: ContextWindowSettings): Record<string, string>;
+/**
+ * Reads the settings a test gave this Worker.
+ * @returns The test's settings, or the defaults outside a Worker child.
+ */
+export declare function readContextWindowSettings(): ContextWindowSettings;
+/**
+ * Returns the `AgentSessionOptions` fields for the settings.
+ * @param settings - The test's settings.
+ * @returns The compaction policy and the message storage options.
+ */
+export declare function contextWindowSessionOptions(settings: ContextWindowSettings): {
+    readonly compaction?: CompactionPolicy;
+    readonly messageWindowSize: number;
+    readonly messageChunkSize: number;
+    readonly retainedMessageLimit: number | null;
+};
+/** What the scripted model does for one request: call the tool with a tag, or answer with a text. */
+export type ContextWindowReply = {
+    readonly kind: "tool_call";
+    readonly tag: string;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
+/** One request the scripted model saw. */
+export interface ContextWindowRequest {
+    /** `"model"` for an agent's request, `"summary"` for a summary call. */
+    readonly kind: "model" | "summary";
+    /** Characters of the request, instructions included. */
+    readonly characters: number;
+    /** The whole request as text, in the framework's format. */
+    readonly input: string;
+}
+/**
+ * Answers model requests of a framework adapter and logs every request, like a provider with a small context
+ * window. Each user message is `turn <tag>`: the model calls {@link contextWindowToolName} once with the tag, then
+ * answers {@link answerText}. It holds no state between calls, so it survives a Worker restart.
+ */
+export declare class ContextWindowModelScript {
+    private readonly stateDirectory;
+    private readonly settings;
+    /**
+     * @param stateDirectory - Directory shared with the test.
+     * @param settings - Sizes of the test.
+     */
+    constructor(stateDirectory: string, settings: ContextWindowSettings);
+    /**
+     * Returns what the tool answers.
+     * @param tag - The tool call's `tag` argument.
+     * @returns Text of `toolOutputCharacters` that names the tag.
+     */
+    toolOutput(tag: string): string;
+    /**
+     * Returns the answer of the turn with this tag.
+     * @param tag - The tag of the user message.
+     * @returns Text of `answerCharacters` that names the tag.
+     */
+    answerText(tag: string): string;
+    /**
+     * Answers one model request.
+     * @param request - The system prompt, the whole request as text, and whether the running turn has its result.
+     * @returns The tool call or the answer.
+     * @throws {Error} When the request exceeds the window or names no turn.
+     */
+    reply(request: {
+        readonly instructions: string | undefined;
+        readonly inputText: string;
+        readonly hasToolResult: boolean;
+    }): Promise<ContextWindowReply>;
+}
+/**
+ * Returns every request the scripted model saw, in order.
+ * @param stateDirectory - The test's state directory.
+ * @returns The logged requests.
+ */
+export declare function readContextWindowRequests(stateDirectory: string): ContextWindowRequest[];
+/** Options of {@link ContextWindowSessionScenario}. */
+export interface ContextWindowSessionScenarioOptions {
+    /** Dex Server address of the test's engine. */
+    readonly serverAddress: string;
+    /** Session client for the adapter's Flow. */
+    readonly sessions: AgentSessionTestClient;
+    /** Directory shared with the Worker child processes. */
+    readonly stateDirectory: string;
+    /** Sizes of the test. */
+    readonly settings: ContextWindowSettings;
+    /** Compiled module of the Worker child, which calls `runAgentWorkerProcess`. */
+    readonly workerEntryModulePath: string;
+    /** Environment that tells the Worker child where {@link stateDirectory} is. */
+    readonly workerEnvironment: Readonly<Record<string, string>>;
+}
+/**
+ * Drives an adapter's session past a context window in Worker child processes, and checks what happened. Every
+ * adapter so proves one contract: the session keeps going, the model input shrinks, and the record stays readable.
+ */
+export declare class ContextWindowSessionScenario {
+    private readonly options;
+    /** The session ID of this scenario. */
+    readonly sessionId: string;
+    private readonly workers;
+    /** @param options - The engine, the session client, and the Worker child. */
+    constructor(options: ContextWindowSessionScenarioOptions);
+    /**
+     * Starts a Worker child with the scenario's settings, or with other settings.
+     * @param settings - Settings of this Worker. Defaults to the scenario's.
+     * @returns The Worker.
+     */
+    startWorker(settings?: ContextWindowSettings): Promise<KillableWorkerProcess>;
+    /** Kills every Worker child the scenario started. */
+    close(): Promise<void>;
+    /**
+     * Returns the logged requests of one kind.
+     * @param kind - `"model"` or `"summary"`.
+     * @returns The requests in order.
+     */
+    requests(kind: ContextWindowRequest["kind"]): ContextWindowRequest[];
+    /**
+     * Sends one turn per tag and waits until the session finished them.
+     * @param tags - The turns' tags.
+     * @param isFirst - Whether the first tag starts the session.
+     * @returns The snapshot after the last turn.
+     */
+    runTurns(tags: readonly string[], isFirst?: boolean): Promise<AgentSnapshot>;
+    /**
+     * Reads every message history still holds, through the public RPC.
+     * @returns The messages in sequence order.
+     */
+    readStoredMessages(): Promise<AgentMessage[]>;
+    /**
+     * Counts the finished `CompactContext` Steps of the session.
+     * @returns The count.
+     */
+    countCompactContextSteps(): Promise<number>;
+    /**
+     * Checks the whole contract on a session longer than the window.
+     * @param turnCount - Turns to run.
+     * @returns The final snapshot.
+     */
+    assertOutlivesTheWindow(turnCount?: number): Promise<AgentSnapshot>;
+    /**
+     * Checks that retention deletes only chunks behind the summary. The settings need a small `retainedMessageLimit`.
+     * @param turnCount - Turns to run.
+     */
+    assertRetentionFollowsTheSummary(turnCount?: number): Promise<void>;
+    /**
+     * Checks that a session without a policy is unchanged and reaches the window.
+     * @param turnCount - Turns to run; the window must end the session first.
+     */
+    assertFailsAtTheWindowWithoutAPolicy(turnCount?: number): Promise<void>;
+    /** Checks that a session started without a policy compacts once a Worker has one. */
+    assertStartsCompactingAfterAnUpgrade(): Promise<void>;
+    /** Checks SIGKILL during `CompactContext`: one more summary call, one stored summary, no repeated model call. */
+    assertWorkerKillRerunsOnlyTheSummary(): Promise<void>;
+}