@superdurable/dex-agents 0.0.0-stage → 0.2.0

package/dist/src/testing/agent-worker-process.d.ts

@@ -0,0 +1,91 @@
+import { type Flow } from "@superdurable/dex";
+/** Environment variable that carries the Dex Server address into a Worker child process. */
+export declare const agentWorkerServerAddressVariable = "DEX_AGENTS_SERVER_ADDRESS";
+/**
+ * Environment variable naming the BlobCache directory of a Worker child process. When it is unset,
+ * the child uses a new temporary directory and deletes it on exit.
+ */
+export declare const agentWorkerBlobCacheDirectoryVariable = "DEX_AGENTS_BLOB_CACHE_DIR";
+/** Line a Worker child process prints once every queue is registered; the same as the Python core. */
+export declare const agentWorkerReadyLine = "dex-agents test Worker ready";
+/** Options of {@link KillableWorkerProcess.start}. */
+export interface KillableWorkerProcessOptions {
+    /**
+     * Path of the compiled ES module the child runs with `node`. The module must call
+     * {@link runAgentWorkerProcess} with the Flows it serves.
+     */
+    readonly entryModulePath: string;
+    /** Dex Server address, usually {@link PrivateDexEngine.serverAddress}. */
+    readonly serverAddress: string;
+    /** Log file; output of every start is appended to it. */
+    readonly logPath: string;
+    /** Extra environment variables for the child, such as a directory for tool marker files. */
+    readonly environment?: Readonly<Record<string, string>>;
+    /** Milliseconds to wait for {@link agentWorkerReadyLine}. Defaults to 60,000. */
+    readonly readyTimeoutMs?: number;
+}
+/**
+ * A Dex Worker running in a child process that a test can hard-kill.
+ *
+ * The child leads its own process group. {@link kill} sends SIGKILL to the group, so the Worker
+ * gets no chance to drain, finish a Step, or close its streams, exactly like a crashed host.
+ * Start a new instance afterward to model the replacement Worker.
+ *
+ * @example
+ * ```ts
+ * // worker-main.ts, compiled to dist/test/worker-main.js
+ * import { runAgentWorkerProcess } from "@superdurable/dex-agents/testing";
+ * await runAgentWorkerProcess([createMyAgentFlow()]);
+ *
+ * // In the test
+ * const worker = await KillableWorkerProcess.start({
+ *   entryModulePath: fileURLToPath(new URL("./worker-main.js", import.meta.url)),
+ *   serverAddress: engine.serverAddress,
+ *   logPath: join(engine.stateDirectory, "worker.log"),
+ * });
+ * await worker.kill();
+ * ```
+ */
+export declare class KillableWorkerProcess {
+    private readonly processGroup;
+    private constructor();
+    /**
+     * Starts the child and waits until its Worker registered every pull queue.
+     * @param options - Entry module, server address, log path, and environment.
+     * @returns The running Worker process.
+     * @throws {Error} When the child exits or is not ready in time; the message holds its log.
+     */
+    static start(options: KillableWorkerProcessOptions): Promise<KillableWorkerProcess>;
+    /** Process ID of the child. */
+    get pid(): number;
+    /** Whether the child is still running. */
+    get isRunning(): boolean;
+    /**
+     * Returns the child's output since this start.
+     * @returns Standard output and standard error, interleaved.
+     */
+    readLog(): string;
+    /**
+     * Sends SIGKILL to the child's process group and waits for it to exit. Safe to call again.
+     * @returns A Promise that resolves after the child exited.
+     */
+    kill(): Promise<void>;
+    /**
+     * Asks the child to drain and exit with SIGTERM, then sends SIGKILL after 15 seconds.
+     * @returns A Promise that resolves after the child exited.
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Runs a pull Worker for the given Flows until SIGTERM or SIGINT; call it from a Worker child module.
+ *
+ * It reads the server address from {@link agentWorkerServerAddressVariable} and the BlobCache directory
+ * from {@link agentWorkerBlobCacheDirectoryVariable}, uses a fresh app Worker ID and 8 concurrent tasks, waits for pull
+ * registration, then prints {@link agentWorkerReadyLine} to standard output. On SIGTERM or SIGINT it
+ * closes the Worker and exits with status 0.
+ *
+ * @param flows - Flows the Worker serves; build them exactly as the test's Client Registry does.
+ * @returns A Promise that never resolves; the process exits on a signal.
+ * @throws {Error} When the server address is missing or the Worker cannot register.
+ */
+export declare function runAgentWorkerProcess(flows: readonly Flow<any>[]): Promise<never>;

package/dist/src/testing/agent-worker-process.js

@@ -0,0 +1,150 @@
+// 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 { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Registry, Worker, openBlobCache } from "@superdurable/dex";
+import { ChildProcessGroup } from "./child-process-group.js";
+/** Environment variable that carries the Dex Server address into a Worker child process. */
+export const agentWorkerServerAddressVariable = "DEX_AGENTS_SERVER_ADDRESS";
+/**
+ * Environment variable naming the BlobCache directory of a Worker child process. When it is unset,
+ * the child uses a new temporary directory and deletes it on exit.
+ */
+export const agentWorkerBlobCacheDirectoryVariable = "DEX_AGENTS_BLOB_CACHE_DIR";
+/** Line a Worker child process prints once every queue is registered; the same as the Python core. */
+export const agentWorkerReadyLine = "dex-agents test Worker ready";
+/**
+ * A Dex Worker running in a child process that a test can hard-kill.
+ *
+ * The child leads its own process group. {@link kill} sends SIGKILL to the group, so the Worker
+ * gets no chance to drain, finish a Step, or close its streams, exactly like a crashed host.
+ * Start a new instance afterward to model the replacement Worker.
+ *
+ * @example
+ * ```ts
+ * // worker-main.ts, compiled to dist/test/worker-main.js
+ * import { runAgentWorkerProcess } from "@superdurable/dex-agents/testing";
+ * await runAgentWorkerProcess([createMyAgentFlow()]);
+ *
+ * // In the test
+ * const worker = await KillableWorkerProcess.start({
+ *   entryModulePath: fileURLToPath(new URL("./worker-main.js", import.meta.url)),
+ *   serverAddress: engine.serverAddress,
+ *   logPath: join(engine.stateDirectory, "worker.log"),
+ * });
+ * await worker.kill();
+ * ```
+ */
+export class KillableWorkerProcess {
+    processGroup;
+    constructor(processGroup) {
+        this.processGroup = processGroup;
+    }
+    /**
+     * Starts the child and waits until its Worker registered every pull queue.
+     * @param options - Entry module, server address, log path, and environment.
+     * @returns The running Worker process.
+     * @throws {Error} When the child exits or is not ready in time; the message holds its log.
+     */
+    static async start(options) {
+        const processGroup = await ChildProcessGroup.start({
+            description: `Worker ${options.entryModulePath}`,
+            command: process.execPath,
+            commandArguments: [options.entryModulePath],
+            environment: {
+                ...process.env,
+                ...options.environment,
+                [agentWorkerServerAddressVariable]: options.serverAddress,
+            },
+            logPath: options.logPath,
+            readyLine: agentWorkerReadyLine,
+            readyTimeoutMs: options.readyTimeoutMs ?? 60_000,
+        });
+        return new KillableWorkerProcess(processGroup);
+    }
+    /** Process ID of the child. */
+    get pid() {
+        return this.processGroup.pid;
+    }
+    /** Whether the child is still running. */
+    get isRunning() {
+        return this.processGroup.isRunning;
+    }
+    /**
+     * Returns the child's output since this start.
+     * @returns Standard output and standard error, interleaved.
+     */
+    readLog() {
+        return this.processGroup.readLog();
+    }
+    /**
+     * Sends SIGKILL to the child's process group and waits for it to exit. Safe to call again.
+     * @returns A Promise that resolves after the child exited.
+     */
+    kill() {
+        return this.processGroup.kill();
+    }
+    /**
+     * Asks the child to drain and exit with SIGTERM, then sends SIGKILL after 15 seconds.
+     * @returns A Promise that resolves after the child exited.
+     */
+    stop() {
+        return this.processGroup.stop();
+    }
+}
+/**
+ * Runs a pull Worker for the given Flows until SIGTERM or SIGINT; call it from a Worker child module.
+ *
+ * It reads the server address from {@link agentWorkerServerAddressVariable} and the BlobCache directory
+ * from {@link agentWorkerBlobCacheDirectoryVariable}, uses a fresh app Worker ID and 8 concurrent tasks, waits for pull
+ * registration, then prints {@link agentWorkerReadyLine} to standard output. On SIGTERM or SIGINT it
+ * closes the Worker and exits with status 0.
+ *
+ * @param flows - Flows the Worker serves; build them exactly as the test's Client Registry does.
+ * @returns A Promise that never resolves; the process exits on a signal.
+ * @throws {Error} When the server address is missing or the Worker cannot register.
+ */
+export async function runAgentWorkerProcess(flows) {
+    const serverAddress = process.env[agentWorkerServerAddressVariable];
+    if (serverAddress === undefined || serverAddress === "") {
+        throw new Error(`${agentWorkerServerAddressVariable} is not set`);
+    }
+    const configuredCacheDirectory = process.env[agentWorkerBlobCacheDirectoryVariable];
+    const isCacheDirectoryOwned = configuredCacheDirectory === undefined || configuredCacheDirectory === "";
+    const cacheDirectory = isCacheDirectoryOwned
+        ? mkdtempSync(join(tmpdir(), "dex-agents-worker-cache-"))
+        : configuredCacheDirectory;
+    mkdirSync(cacheDirectory, { recursive: true });
+    const blobCache = openBlobCache({ directory: cacheDirectory, maxBytes: 64 * 1024 * 1024 });
+    const worker = new Worker(new Registry(flows), blobCache, {
+        serverAddress,
+        // Parallel tool Steps must not depend on the CI machine's CPU count.
+        pull: { appWorkerID: `dex-agents-test-worker-${randomUUID()}`, maxConcurrentTasks: 8 },
+    });
+    const closeAndExit = async () => {
+        try {
+            await worker.close();
+            blobCache.close();
+        }
+        finally {
+            if (isCacheDirectoryOwned) {
+                rmSync(cacheDirectory, { recursive: true, force: true });
+            }
+            process.exit(0);
+        }
+    };
+    process.once("SIGTERM", () => void closeAndExit());
+    process.once("SIGINT", () => void closeAndExit());
+    await worker.start();
+    await worker.waitPullRegistered({ timeoutMs: 30_000 });
+    process.stdout.write(`${agentWorkerReadyLine}\n`);
+    return new Promise(() => undefined);
+}
+//# sourceMappingURL=agent-worker-process.js.map

package/dist/src/testing/agent-worker-process.js.map

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

package/dist/src/testing/child-process-group.d.ts

@@ -0,0 +1,33 @@
+/** Command, environment, and readiness of one child process group. */
+export interface ChildProcessGroupLaunch {
+    readonly description: string;
+    readonly command: string;
+    readonly commandArguments: readonly string[];
+    readonly environment: NodeJS.ProcessEnv;
+    readonly logPath: string;
+    readonly readyLine: string;
+    readonly readyTimeoutMs: number;
+}
+/** A child process that leads its own process group, so signals reach every descendant. */
+export declare class ChildProcessGroup {
+    private readonly launch;
+    private readonly child;
+    private readonly logOffset;
+    private readonly exited;
+    private hasExited;
+    private spawnError;
+    private constructor();
+    static start(launch: ChildProcessGroupLaunch): Promise<ChildProcessGroup>;
+    /** Process ID of the group leader. */
+    get pid(): number;
+    get isRunning(): boolean;
+    /** Output written since this process started. */
+    readLog(): string;
+    /** Sends SIGKILL to the whole group and waits for the leader to exit. */
+    kill(): Promise<void>;
+    /** Sends SIGTERM to the whole group, then SIGKILL after 15 seconds. */
+    stop(): Promise<void>;
+    signalGroupSynchronously(signal: NodeJS.Signals): void;
+    private signalGroup;
+    private waitForReadyLine;
+}

package/dist/src/testing/child-process-group.js

@@ -0,0 +1,164 @@
+// 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 { spawn } from "node:child_process";
+import { closeSync, openSync, readFileSync, statSync } from "node:fs";
+import { setTimeout as delay } from "node:timers/promises";
+const readyPollIntervalMs = 50;
+const gracefulStopTimeoutMs = 15_000;
+const runningProcessGroups = new Set();
+let isExitCleanupRegistered = false;
+/** A child process that leads its own process group, so signals reach every descendant. */
+export class ChildProcessGroup {
+    launch;
+    child;
+    logOffset;
+    exited;
+    hasExited = false;
+    spawnError;
+    constructor(launch, child, logOffset) {
+        this.launch = launch;
+        this.child = child;
+        this.logOffset = logOffset;
+        this.exited = new Promise((resolve) => {
+            const markExited = () => {
+                this.hasExited = true;
+                runningProcessGroups.delete(this);
+                resolve();
+            };
+            child.once("exit", markExited);
+            child.once("error", (error) => {
+                this.spawnError = error;
+                // A process that never spawned emits no exit event.
+                if (child.pid === undefined) {
+                    markExited();
+                }
+            });
+        });
+    }
+    static async start(launch) {
+        registerExitCleanup();
+        const logOffset = fileSize(launch.logPath);
+        const logDescriptor = openSync(launch.logPath, "a");
+        let child;
+        try {
+            child = spawn(launch.command, [...launch.commandArguments], {
+                detached: true,
+                env: launch.environment,
+                stdio: ["ignore", logDescriptor, logDescriptor],
+            });
+        }
+        finally {
+            closeSync(logDescriptor);
+        }
+        const processGroup = new ChildProcessGroup(launch, child, logOffset);
+        runningProcessGroups.add(processGroup);
+        try {
+            await processGroup.waitForReadyLine();
+        }
+        catch (error) {
+            await processGroup.kill();
+            throw error;
+        }
+        return processGroup;
+    }
+    /** Process ID of the group leader. */
+    get pid() {
+        const pid = this.child.pid;
+        if (pid === undefined) {
+            throw new Error(`${this.launch.description} has no process ID`);
+        }
+        return pid;
+    }
+    get isRunning() {
+        return !this.hasExited;
+    }
+    /** Output written since this process started. */
+    readLog() {
+        return readFileSync(this.launch.logPath).subarray(this.logOffset).toString("utf8");
+    }
+    /** Sends SIGKILL to the whole group and waits for the leader to exit. */
+    async kill() {
+        this.signalGroup("SIGKILL");
+        await this.exited;
+    }
+    /** Sends SIGTERM to the whole group, then SIGKILL after 15 seconds. */
+    async stop() {
+        this.signalGroup("SIGTERM");
+        const gracefulStopTimer = new AbortController();
+        const isStopped = await Promise.race([
+            this.exited.then(() => true),
+            delay(gracefulStopTimeoutMs, false, { signal: gracefulStopTimer.signal }).catch(() => true),
+        ]);
+        gracefulStopTimer.abort();
+        if (!isStopped) {
+            await this.kill();
+        }
+    }
+    signalGroupSynchronously(signal) {
+        this.signalGroup(signal);
+    }
+    signalGroup(signal) {
+        if (this.hasExited || this.child.pid === undefined) {
+            return;
+        }
+        try {
+            process.kill(-this.child.pid, signal);
+        }
+        catch (error) {
+            if (!isNoSuchProcessError(error)) {
+                throw error;
+            }
+        }
+    }
+    async waitForReadyLine() {
+        const deadline = Date.now() + this.launch.readyTimeoutMs;
+        while (Date.now() < deadline) {
+            const spawnError = this.spawnError;
+            if (spawnError !== undefined) {
+                throw new Error(`${this.launch.description} failed to start: ${spawnError.message}`, {
+                    cause: spawnError,
+                });
+            }
+            if (this.readLog().includes(this.launch.readyLine)) {
+                return;
+            }
+            if (this.hasExited) {
+                throw new Error(`${this.launch.description} exited before it was ready:\n${this.readLog()}`);
+            }
+            await delay(readyPollIntervalMs);
+        }
+        throw new Error(`${this.launch.description} was not ready within ${this.launch.readyTimeoutMs} ms:\n${this.readLog()}`);
+    }
+}
+function registerExitCleanup() {
+    if (isExitCleanupRegistered) {
+        return;
+    }
+    isExitCleanupRegistered = true;
+    // Never leave an engine or Worker behind when the test process exits without cleanup.
+    process.once("exit", () => {
+        for (const processGroup of runningProcessGroups) {
+            processGroup.signalGroupSynchronously("SIGKILL");
+        }
+    });
+}
+function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return 0;
+        }
+        throw error;
+    }
+}
+function isNoSuchProcessError(error) {
+    return error instanceof Error && "code" in error && error.code === "ESRCH";
+}
+//# sourceMappingURL=child-process-group.js.map

package/dist/src/testing/child-process-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-process-group.js","sourceRoot":"","sources":["../../../src/testing/child-process-group.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAC/B,MAAM,qBAAqB,GAAG,MAAM,CAAC;AACrC,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAqB,CAAC;AAC1D,IAAI,uBAAuB,GAAG,KAAK,CAAC;AAapC,2FAA2F;AAC3F,MAAM,OAAO,iBAAiB;IAMT;IACA;IACA;IAPF,MAAM,CAAgB;IAC/B,SAAS,GAAG,KAAK,CAAC;IAClB,UAAU,CAAoB;IAEtC,YACmB,MAA+B,EAC/B,KAAmB,EACnB,SAAiB;QAFjB,WAAM,GAAN,MAAM,CAAyB;QAC/B,UAAK,GAAL,KAAK,CAAc;QACnB,cAAS,GAAT,SAAS,CAAQ;QAElC,IAAI,CAAC,MAAM,GAAG,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACpC,MAAM,UAAU,GAAG,GAAS,EAAE;gBAC5B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;gBACtB,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAClC,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC5B,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;gBACxB,oDAAoD;gBACpD,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;oBAC5B,UAAU,EAAE,CAAC;gBACf,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAA+B;QACvD,mBAAmB,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACpD,IAAI,KAAmB,CAAC;QACxB,IAAI,CAAC;YACH,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,gBAAgB,CAAC,EAAE;gBAC1D,QAAQ,EAAE,IAAI;gBACd,GAAG,EAAE,MAAM,CAAC,WAAW;gBACvB,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,aAAa,CAAC;aAChD,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,aAAa,CAAC,CAAC;QAC3B,CAAC;QACD,MAAM,YAAY,GAAG,IAAI,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;QACrE,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACvC,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,gBAAgB,EAAE,CAAC;QACxC,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,YAAY,CAAC,IAAI,EAAE,CAAC;YAC1B,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,sCAAsC;IACtC,IAAW,GAAG;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;QAC3B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,oBAAoB,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAW,SAAS;QAClB,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC;IACzB,CAAC;IAED,iDAAiD;IAC1C,OAAO;QACZ,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrF,CAAC;IAED,yEAAyE;IAClE,KAAK,CAAC,IAAI;QACf,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAC5B,MAAM,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IAED,uEAAuE;IAChE,KAAK,CAAC,IAAI;QACf,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QAC5B,MAAM,iBAAiB,GAAG,IAAI,eAAe,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YAC5B,KAAK,CAAC,qBAAqB,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SAC5F,CAAC,CAAC;QACH,iBAAiB,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAEM,wBAAwB,CAAC,MAAsB;QACpD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAEO,WAAW,CAAC,MAAsB;QACxC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YACnD,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjC,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,gBAAgB;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QACzD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;YACnC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,qBAAqB,UAAU,CAAC,OAAO,EAAE,EAAE;oBACnF,KAAK,EAAE,UAAU;iBAClB,CAAC,CAAC;YACL,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;gBACnD,OAAO;YACT,CAAC;YACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,iCAAiC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAC/F,CAAC;YACD,MAAM,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACnC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,yBAAyB,IAAI,CAAC,MAAM,CAAC,cAAc,SAAS,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1H,CAAC;CACF;AAED,SAAS,mBAAmB;IAC1B,IAAI,uBAAuB,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IACD,uBAAuB,GAAG,IAAI,CAAC;IAC/B,sFAAsF;IACtF,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;QACxB,KAAK,MAAM,YAAY,IAAI,oBAAoB,EAAE,CAAC;YAChD,YAAY,CAAC,wBAAwB,CAAC,SAAS,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY;IAC5B,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;AAC7E,CAAC"}

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

@@ -0,0 +1,99 @@
+/**
+ * Pauses code in a Worker child at an exact point until the test releases it.
+ *
+ * The child calls {@link markReached} and then awaits {@link waitForRelease}. The test awaits
+ * {@link waitUntilReached} and then kills the Worker, or calls {@link release}. Both sides construct
+ * the gate with the same directory and name. The gate survives Worker kills, so a replacement Worker
+ * passes a released gate immediately. It mirrors the Python core's `FileGate`.
+ *
+ * @example
+ * ```ts
+ * // In the tool, inside the Worker child:
+ * const gate = new FileGate(stateDirectory, "charge");
+ * gate.markReached();
+ * await gate.waitForRelease(call.cancellationSignal);
+ *
+ * // In the test:
+ * await new FileGate(stateDirectory, "charge").waitUntilReached();
+ * await worker.kill();
+ * ```
+ */
+export declare class FileGate {
+    private readonly reachedPath;
+    private readonly releasedPath;
+    /**
+     * Names a gate inside a directory both processes can read.
+     * @param directory - Shared directory, created when needed.
+     * @param name - Gate name, unique within the directory.
+     */
+    constructor(directory: string, name: string);
+    /** Records that code reached the gate; repeated calls count each arrival. */
+    markReached(): void;
+    /**
+     * Returns how many times code reached the gate.
+     * @returns The number of {@link markReached} calls across all processes.
+     */
+    reachedCount(): number;
+    /**
+     * Reports whether the test released the gate.
+     * @returns `true` after {@link release}.
+     */
+    isReleased(): boolean;
+    /** Lets current and future waiters pass the gate. */
+    release(): void;
+    /**
+     * Waits until the test releases the gate.
+     *
+     * It never times out: the test either releases the gate or kills the waiting process. Pass the
+     * attempt's cancellation signal so a canceled attempt stops waiting.
+     * @param signal - Optional signal that ends the wait with an `AbortError`.
+     * @returns A Promise that resolves once the gate is released.
+     */
+    waitForRelease(signal?: AbortSignal): Promise<void>;
+    /**
+     * Waits until code reached the gate `count` times.
+     * @param count - Arrivals to wait for. Defaults to 1.
+     * @param timeoutMs - Maximum wait in milliseconds. Defaults to 90,000.
+     * @returns A Promise that resolves once the gate was reached often enough.
+     * @throws {Error} When the timeout passes first.
+     */
+    waitUntilReached(count?: number, timeoutMs?: number): Promise<void>;
+}
+/**
+ * Counts how often named operations ran, across Worker processes.
+ *
+ * A tool in the Worker child records each real run; the test then asserts that a write ran exactly
+ * once, even across a Worker kill. Each record is appended synchronously, so it survives a SIGKILL
+ * right after. It mirrors the Python core's `InvocationLog`.
+ *
+ * @example
+ * ```ts
+ * new InvocationLog(join(stateDirectory, "invocations.log")).record("send_email");
+ * assert.equal(new InvocationLog(join(stateDirectory, "invocations.log")).count("send_email"), 1);
+ * ```
+ */
+export declare class InvocationLog {
+    private readonly path;
+    /**
+     * Uses one append-only file shared by the test and its Workers.
+     * @param path - Log file, created on the first record.
+     */
+    constructor(path: string);
+    /**
+     * Appends one run of `name`.
+     * @param name - Operation name without line breaks.
+     * @throws {TypeError} When `name` contains a line break.
+     */
+    record(name: string): void;
+    /**
+     * Returns how many runs of `name` were recorded.
+     * @param name - Operation name.
+     * @returns The number of matching records.
+     */
+    count(name: string): number;
+    /**
+     * Returns every recorded name in order.
+     * @returns The records, oldest first, or an empty array before the first record.
+     */
+    names(): string[];
+}