@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.1

package/dist/provider.d.ts

@@ -0,0 +1,77 @@
+import type { ExecOptions, ExecResult, MainProcessInfo, NormalizedCommand, SandboxNetworkPolicyKind, SandboxSpec } from "./types.js";
+/** Identifies a sandbox on its provider. Passed to every provider operation. */
+export interface ProviderSandbox {
+    /** SDK sandbox ID. */
+    id: string;
+    /** The provider's own ID, as returned from `create`. */
+    providerRef: string;
+    spec: SandboxSpec;
+    /** Resolved working directory (`spec.workdir` or the provider default). */
+    workdir: string;
+}
+export interface ProviderCreateInput {
+    id: string;
+    spec: SandboxSpec;
+    workdir: string;
+    ownerId: string | null;
+    labels: Record<string, string>;
+}
+export interface ProviderCreateResult {
+    providerRef: string;
+}
+/** What the provider reports about a sandbox. */
+export type ProviderSandboxStatus = "running" | "stopped" | "missing";
+/** A file written by `writeFiles`, with its path resolved to absolute. */
+export interface ResolvedSandboxFile {
+    path: string;
+    content: Uint8Array;
+    mode: number;
+}
+export interface MainLogChunk {
+    data: Uint8Array;
+    /** Byte offset to pass on the next read. */
+    nextOffset: number;
+}
+/**
+ * Adapter to a sandbox backend. Providers are stateless with respect to the
+ * store: the `SandboxManager` owns status bookkeeping.
+ *
+ * Operations other than `create`, `wake`, `stop`, `destroy` and `status` must
+ * throw `ProviderSandboxStoppedError` if the sandbox is not running, and
+ * `ProviderSandboxMissingError` if it no longer exists, so the manager can
+ * auto-resume or report it.
+ */
+export interface SandboxProvider {
+    readonly name: string;
+    /** Working directory used when `spec.workdir` is not set. */
+    readonly defaultWorkdir: string;
+    /**
+     * The restrictive `spec.network` policies this provider enforces. The
+     * manager refuses to create a sandbox whose policy is not listed, so a
+     * provider that leaves this out never silently ignores one. An unset or
+     * `"allow-all"` policy is always accepted.
+     */
+    readonly networkPolicies?: readonly Exclude<SandboxNetworkPolicyKind, "allow-all">[];
+    /** Create the sandbox and leave it running with `workdir` present. */
+    create(input: ProviderCreateInput): Promise<ProviderCreateResult>;
+    /** Start a stopped sandbox. Must be a no-op if it is already running. */
+    wake(sandbox: ProviderSandbox): Promise<void>;
+    /** Stop the sandbox, keeping its filesystem. Must be a no-op if already stopped. */
+    stop(sandbox: ProviderSandbox): Promise<void>;
+    /** Delete the sandbox. Must be a no-op if it no longer exists. */
+    destroy(sandbox: ProviderSandbox): Promise<void>;
+    status(sandbox: ProviderSandbox): Promise<ProviderSandboxStatus>;
+    exec(sandbox: ProviderSandbox, command: NormalizedCommand, options?: ExecOptions): Promise<ExecResult>;
+    /** Launch `command` detached as the sandbox's main process, logging its output. */
+    startMainProcess(sandbox: ProviderSandbox, command: NormalizedCommand): Promise<void>;
+    getMainProcess(sandbox: ProviderSandbox): Promise<MainProcessInfo | null>;
+    /** Read the main process log from byte `offset`; an empty chunk means no new output. */
+    readMainLog(sandbox: ProviderSandbox, offset: number): Promise<MainLogChunk>;
+    writeFiles(sandbox: ProviderSandbox, files: ResolvedSandboxFile[]): Promise<void>;
+    /** Resolves `null` if the file does not exist. */
+    readFile(sandbox: ProviderSandbox, path: string): Promise<Uint8Array | null>;
+    /** A URL that reaches `port` inside the sandbox. The port must be in `spec.ports`. */
+    getUrl(sandbox: ProviderSandbox, port: number): Promise<string>;
+    /** Extend the provider-side timeout, if the provider enforces one. */
+    extendTimeout?(sandbox: ProviderSandbox, durationMs: number): Promise<void>;
+}

package/dist/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/shell-main-process.d.ts

@@ -0,0 +1,27 @@
+import type { MainLogChunk } from "./provider.js";
+import type { ExecResult, MainProcessInfo, NormalizedCommand } from "./types.js";
+/**
+ * Main-process bookkeeping for providers that only offer "run a command":
+ * the launcher records its PID, appends output to a log file and records the
+ * exit code, all under this directory inside the sandbox.
+ */
+export declare const MAIN_PROCESS_DIR = "/tmp/sandbox-sdk";
+type Exec = (command: NormalizedCommand) => Promise<ExecResult>;
+type SpawnDetached = (command: NormalizedCommand) => Promise<void>;
+/**
+ * Launch `command` as the main process: clear the previous run's PID and exit
+ * files, spawn the launcher detached, then wait until it has recorded its PID
+ * so `getMainProcess` reflects the new process as soon as this resolves.
+ */
+export declare function shellStartMainProcess(exec: Exec, spawnDetached: SpawnDetached, command: NormalizedCommand, { timeoutMs, pollIntervalMs }?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}): Promise<void>;
+/**
+ * A command that runs `command` in the foreground as the main process. The
+ * provider must run it detached (it only returns when the process exits).
+ */
+export declare function mainProcessLauncher(command: NormalizedCommand): NormalizedCommand;
+export declare function shellGetMainProcess(exec: Exec): Promise<MainProcessInfo | null>;
+export declare function shellReadMainLog(exec: Exec, offset: number, maxBytes?: number): Promise<MainLogChunk>;
+export {};

package/dist/shell-main-process.js

@@ -0,0 +1,94 @@
+import { toShellCommandLine } from "./commands.js";
+import { SandboxError } from "./errors.js";
+import { decodeBase64 } from "./internal/base64.js";
+/**
+ * Main-process bookkeeping for providers that only offer "run a command":
+ * the launcher records its PID, appends output to a log file and records the
+ * exit code, all under this directory inside the sandbox.
+ */
+export const MAIN_PROCESS_DIR = "/tmp/sandbox-sdk";
+const PID_FILE = `${MAIN_PROCESS_DIR}/main.pid`;
+const EXIT_FILE = `${MAIN_PROCESS_DIR}/main.exit`;
+const LOG_FILE = `${MAIN_PROCESS_DIR}/main.log`;
+const DEFAULT_MAX_LOG_READ_BYTES = 1024 * 1024;
+const sh = (script) => ({ cmd: "sh", args: ["-c", script], cwd: "/", env: {} });
+/**
+ * Launch `command` as the main process: clear the previous run's PID and exit
+ * files, spawn the launcher detached, then wait until it has recorded its PID
+ * so `getMainProcess` reflects the new process as soon as this resolves.
+ */
+export async function shellStartMainProcess(exec, spawnDetached, command, { timeoutMs = 15_000, pollIntervalMs = 100 } = {}) {
+    const reset = await exec(sh(`mkdir -p ${MAIN_PROCESS_DIR} && rm -f ${PID_FILE} ${EXIT_FILE}`));
+    if (reset.exitCode !== 0) {
+        throw new SandboxError(`Failed to prepare main process: ${reset.stderr.trim()}`);
+    }
+    await spawnDetached(mainProcessLauncher(command));
+    const deadline = Date.now() + timeoutMs;
+    while ((await exec(sh(`[ -f ${PID_FILE} ]`))).exitCode !== 0) {
+        if (Date.now() >= deadline)
+            throw new SandboxError("Main process did not start");
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+}
+/**
+ * A command that runs `command` in the foreground as the main process. The
+ * provider must run it detached (it only returns when the process exits).
+ */
+export function mainProcessLauncher(command) {
+    const script = [
+        `mkdir -p ${MAIN_PROCESS_DIR}`,
+        `rm -f ${EXIT_FILE}`,
+        `echo $$ > ${PID_FILE}`,
+        `exec >> ${LOG_FILE} 2>&1 < /dev/null`,
+        `(${toShellCommandLine(command)})`,
+        `echo $? > ${EXIT_FILE}`,
+    ].join("\n");
+    return sh(script);
+}
+const STATUS_SCRIPT = `[ -f ${PID_FILE} ] || exit 0
+pid=$(cat ${PID_FILE})
+if kill -0 "$pid" 2>/dev/null; then alive=1; else alive=0; fi
+code=$(cat ${EXIT_FILE} 2>/dev/null || true)
+echo "$pid $alive $code"`;
+export async function shellGetMainProcess(exec) {
+    const result = await exec(sh(STATUS_SCRIPT));
+    if (result.exitCode !== 0) {
+        throw new SandboxError(`Failed to read main process status: ${result.stderr.trim()}`);
+    }
+    const [pidText, aliveText, codeText] = result.stdout.trim().split(/\s+/);
+    if (!pidText)
+        return null;
+    const pid = Number.parseInt(pidText, 10);
+    const exitCode = codeText ? Number.parseInt(codeText, 10) : null;
+    return {
+        pid: Number.isNaN(pid) ? null : pid,
+        running: aliveText === "1" && exitCode === null,
+        exitCode: exitCode === null || Number.isNaN(exitCode) ? null : exitCode,
+    };
+}
+/**
+ * Reads the main log from `offset`. The first output line is the effective
+ * start offset (reset to 0 if the log was truncated), then base64 data.
+ */
+const READ_LOG_SCRIPT = `f=${LOG_FILE}
+[ -f "$f" ] || { echo 0; exit 0; }
+size=$(wc -c < "$f")
+off=$SANDBOX_LOG_OFFSET
+[ "$size" -lt "$off" ] && off=0
+echo "$off"
+tail -c +$((off + 1)) "$f" | head -c $SANDBOX_LOG_MAX_BYTES | base64`;
+export async function shellReadMainLog(exec, offset, maxBytes = DEFAULT_MAX_LOG_READ_BYTES) {
+    const result = await exec({
+        cmd: "sh",
+        args: ["-c", READ_LOG_SCRIPT],
+        cwd: "/",
+        env: { SANDBOX_LOG_OFFSET: String(offset), SANDBOX_LOG_MAX_BYTES: String(maxBytes) },
+    });
+    if (result.exitCode !== 0) {
+        throw new SandboxError(`Failed to read main process log: ${result.stderr.trim()}`);
+    }
+    const newline = result.stdout.indexOf("\n");
+    const start = Number.parseInt(newline === -1 ? result.stdout : result.stdout.slice(0, newline), 10) || 0;
+    const data = newline === -1 ? new Uint8Array() : decodeBase64(result.stdout.slice(newline + 1));
+    return { data, nextOffset: start + data.length };
+}

package/dist/store.d.ts

@@ -0,0 +1,36 @@
+import type { SandboxRecord, SandboxStatus } from "./types.js";
+export interface SandboxListFilter {
+    ownerId?: string;
+    provider?: string;
+    status?: SandboxStatus | SandboxStatus[];
+    /** Matches records whose labels contain every given key/value pair. */
+    labels?: Record<string, string>;
+    /** Destroyed sandboxes are excluded unless this is set (or `status` asks for them). */
+    includeDestroyed?: boolean;
+    limit?: number;
+    offset?: number;
+}
+/** Fields the manager may change after insert. `version` and `updatedAt` are managed by the store. */
+export type SandboxRecordPatch = Partial<Pick<SandboxRecord, "status" | "providerRef" | "error" | "expiresAt" | "labels" | "metadata">>;
+/**
+ * Persistence for sandbox records. Implementations must make `update` an
+ * atomic compare-and-set on `version`, which is what makes concurrent
+ * resume/stop calls from different processes safe.
+ */
+export interface SandboxStore {
+    insert(record: SandboxRecord): Promise<void>;
+    get(id: string): Promise<SandboxRecord | null>;
+    /** Newest first. */
+    list(filter?: SandboxListFilter): Promise<SandboxRecord[]>;
+    /**
+     * Apply `patch` only if the stored version equals `expectedVersion`; the
+     * stored version is then incremented and `updatedAt` set to now.
+     * Resolves the updated record, or `null` if the version did not match (or
+     * the record does not exist).
+     */
+    update(id: string, expectedVersion: number, patch: SandboxRecordPatch): Promise<SandboxRecord | null>;
+    /** Hard-delete a record. Resolves whether a record was deleted. */
+    delete(id: string): Promise<boolean>;
+}
+/** Shared filter semantics, for stores that filter in memory. */
+export declare function matchesFilter(record: SandboxRecord, filter: SandboxListFilter): boolean;

package/dist/store.js

@@ -0,0 +1,19 @@
+/** Shared filter semantics, for stores that filter in memory. */
+export function matchesFilter(record, filter) {
+    if (filter.ownerId !== undefined && record.ownerId !== filter.ownerId)
+        return false;
+    if (filter.provider !== undefined && record.provider !== filter.provider)
+        return false;
+    const statuses = filter.status === undefined ? undefined : [].concat(filter.status);
+    if (statuses && !statuses.includes(record.status))
+        return false;
+    if (!statuses && !filter.includeDestroyed && record.status === "destroyed")
+        return false;
+    if (filter.labels) {
+        for (const [key, value] of Object.entries(filter.labels)) {
+            if (record.labels[key] !== value)
+                return false;
+        }
+    }
+    return true;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { MockSandboxProvider } from "./mock-provider.js";
+export type { MockCall, MockExecContext, MockExecHandler, MockMainProcess, MockOperation, MockSandboxProviderOptions, MockSandboxState, } from "./mock-provider.js";
+export { InMemorySandboxStore } from "../in-memory-store.js";

package/dist/testing/index.js

@@ -0,0 +1,2 @@
+export { MockSandboxProvider } from "./mock-provider.js";
+export { InMemorySandboxStore } from "../in-memory-store.js";

package/dist/testing/mock-provider.d.ts

@@ -0,0 +1,99 @@
+import type { MainLogChunk, ProviderCreateInput, ProviderCreateResult, ProviderSandbox, ProviderSandboxStatus, ResolvedSandboxFile, SandboxProvider } from "../provider.js";
+import type { ExecOptions, ExecResult, MainProcessInfo, NormalizedCommand, SandboxNetworkPolicyKind, SandboxSpec } from "../types.js";
+export type MockOperation = "create" | "wake" | "stop" | "destroy" | "exec" | "startMainProcess" | "writeFiles" | "readFile" | "getUrl" | "extendTimeout";
+export interface MockCall {
+    operation: MockOperation;
+    sandboxId: string;
+    command?: NormalizedCommand;
+}
+export interface MockExecContext {
+    sandboxId: string;
+    command: NormalizedCommand;
+    /** `spec.env` merged with the command's env. */
+    env: Record<string, string>;
+}
+/** Answers `exec` calls. Returning nothing means exit code 0 with no output. */
+export type MockExecHandler = (context: MockExecContext) => Partial<ExecResult> | void | Promise<Partial<ExecResult> | void>;
+export interface MockMainProcess {
+    command: NormalizedCommand;
+    pid: number;
+    running: boolean;
+    exitCode: number | null;
+}
+export interface MockSandboxState {
+    sandboxId: string;
+    providerRef: string;
+    spec: SandboxSpec;
+    workdir: string;
+    running: boolean;
+    files: Map<string, Uint8Array>;
+    mainProcess: MockMainProcess | null;
+    /** Main process output, appended across restarts like a real log file. */
+    log: Uint8Array;
+    timeoutExtensionsMs: number[];
+}
+export interface MockSandboxProviderOptions {
+    /** Default `"mock"`. */
+    name?: string;
+    /** Default `"/workspace"`. */
+    defaultWorkdir?: string;
+    execHandler?: MockExecHandler;
+    /** Simulated latency for create / wake / stop / destroy, in ms. Default 0. */
+    lifecycleDelayMs?: number;
+    /** Called before every operation; throw from it to inject failures. */
+    beforeOperation?: (operation: MockOperation, sandboxId: string) => void | Promise<void>;
+    /**
+     * `spec.network` policies the mock accepts. Default: all of them. The mock
+     * only records the policy (in `spec`); narrow this to simulate a provider
+     * that cannot enforce one.
+     */
+    networkPolicies?: readonly Exclude<SandboxNetworkPolicyKind, "allow-all">[];
+}
+/**
+ * An in-memory provider for tests. Nothing is executed: `exec` calls are
+ * answered by `execHandler` and recorded in `calls`, files live in memory,
+ * and stop / wake / external stops are simulated.
+ */
+export declare class MockSandboxProvider implements SandboxProvider {
+    readonly name: string;
+    readonly defaultWorkdir: string;
+    readonly networkPolicies: readonly Exclude<SandboxNetworkPolicyKind, "allow-all">[];
+    readonly calls: MockCall[];
+    private readonly sandboxes;
+    private execHandler;
+    private readonly lifecycleDelayMs;
+    private readonly beforeOperation;
+    private nextPid;
+    constructor(options?: MockSandboxProviderOptions);
+    setExecHandler(handler: MockExecHandler): void;
+    /** State of a sandbox by SDK sandbox ID. */
+    getState(sandboxId: string): MockSandboxState | undefined;
+    /** Calls recorded for one sandbox, optionally of one operation. */
+    callsFor(sandboxId: string, operation?: MockOperation): MockCall[];
+    /** Simulate the provider stopping a sandbox on its own, e.g. a provider-side timeout. */
+    simulateExternalStop(sandboxId: string): void;
+    /** Simulate the sandbox being deleted outside the SDK. */
+    simulateExternalDelete(sandboxId: string): void;
+    /** Append output to the main process log. */
+    appendMainLog(sandboxId: string, text: string): void;
+    /** Simulate the main process exiting with `exitCode`. */
+    exitMainProcess(sandboxId: string, exitCode: number): void;
+    create(input: ProviderCreateInput): Promise<ProviderCreateResult>;
+    wake(sandbox: ProviderSandbox): Promise<void>;
+    stop(sandbox: ProviderSandbox): Promise<void>;
+    destroy(sandbox: ProviderSandbox): Promise<void>;
+    status(sandbox: ProviderSandbox): Promise<ProviderSandboxStatus>;
+    exec(sandbox: ProviderSandbox, command: NormalizedCommand, options?: ExecOptions): Promise<ExecResult>;
+    startMainProcess(sandbox: ProviderSandbox, command: NormalizedCommand): Promise<void>;
+    getMainProcess(sandbox: ProviderSandbox): Promise<MainProcessInfo | null>;
+    readMainLog(sandbox: ProviderSandbox, offset: number): Promise<MainLogChunk>;
+    writeFiles(sandbox: ProviderSandbox, files: ResolvedSandboxFile[]): Promise<void>;
+    readFile(sandbox: ProviderSandbox, path: string): Promise<Uint8Array | null>;
+    getUrl(sandbox: ProviderSandbox, port: number): Promise<string>;
+    extendTimeout(sandbox: ProviderSandbox, durationMs: number): Promise<void>;
+    private record;
+    private delay;
+    private lookup;
+    private running;
+    private mustGetState;
+}

package/dist/testing/mock-provider.js

@@ -0,0 +1,181 @@
+import { ProviderSandboxMissingError, ProviderSandboxStoppedError, SandboxError } from "../errors.js";
+/**
+ * An in-memory provider for tests. Nothing is executed: `exec` calls are
+ * answered by `execHandler` and recorded in `calls`, files live in memory,
+ * and stop / wake / external stops are simulated.
+ */
+export class MockSandboxProvider {
+    name;
+    defaultWorkdir;
+    networkPolicies;
+    calls = [];
+    sandboxes = new Map();
+    execHandler;
+    lifecycleDelayMs;
+    beforeOperation;
+    nextPid = 100;
+    constructor(options = {}) {
+        this.name = options.name ?? "mock";
+        this.defaultWorkdir = options.defaultWorkdir ?? "/workspace";
+        this.execHandler = options.execHandler ?? (() => undefined);
+        this.lifecycleDelayMs = options.lifecycleDelayMs ?? 0;
+        this.beforeOperation = options.beforeOperation;
+        this.networkPolicies = options.networkPolicies ?? ["deny-all", "allowlist"];
+    }
+    setExecHandler(handler) {
+        this.execHandler = handler;
+    }
+    /** State of a sandbox by SDK sandbox ID. */
+    getState(sandboxId) {
+        return [...this.sandboxes.values()].find((state) => state.sandboxId === sandboxId);
+    }
+    /** Calls recorded for one sandbox, optionally of one operation. */
+    callsFor(sandboxId, operation) {
+        return this.calls.filter((call) => call.sandboxId === sandboxId && (operation === undefined || call.operation === operation));
+    }
+    /** Simulate the provider stopping a sandbox on its own, e.g. a provider-side timeout. */
+    simulateExternalStop(sandboxId) {
+        const state = this.mustGetState(sandboxId);
+        state.running = false;
+        if (state.mainProcess)
+            state.mainProcess.running = false;
+    }
+    /** Simulate the sandbox being deleted outside the SDK. */
+    simulateExternalDelete(sandboxId) {
+        this.sandboxes.delete(this.mustGetState(sandboxId).providerRef);
+    }
+    /** Append output to the main process log. */
+    appendMainLog(sandboxId, text) {
+        const state = this.mustGetState(sandboxId);
+        const added = new TextEncoder().encode(text);
+        const log = new Uint8Array(state.log.length + added.length);
+        log.set(state.log);
+        log.set(added, state.log.length);
+        state.log = log;
+    }
+    /** Simulate the main process exiting with `exitCode`. */
+    exitMainProcess(sandboxId, exitCode) {
+        const state = this.mustGetState(sandboxId);
+        if (!state.mainProcess)
+            throw new SandboxError(`Sandbox "${sandboxId}" has no main process`);
+        state.mainProcess.running = false;
+        state.mainProcess.exitCode = exitCode;
+    }
+    async create(input) {
+        await this.record("create", input.id);
+        await this.delay();
+        const providerRef = `mock-${input.id}`;
+        this.sandboxes.set(providerRef, {
+            sandboxId: input.id,
+            providerRef,
+            spec: input.spec,
+            workdir: input.workdir,
+            running: true,
+            files: new Map(),
+            mainProcess: null,
+            log: new Uint8Array(),
+            timeoutExtensionsMs: [],
+        });
+        return { providerRef };
+    }
+    async wake(sandbox) {
+        await this.record("wake", sandbox.id);
+        await this.delay();
+        this.lookup(sandbox).running = true;
+    }
+    async stop(sandbox) {
+        await this.record("stop", sandbox.id);
+        await this.delay();
+        const state = this.lookup(sandbox);
+        state.running = false;
+        if (state.mainProcess)
+            state.mainProcess.running = false;
+    }
+    async destroy(sandbox) {
+        await this.record("destroy", sandbox.id);
+        await this.delay();
+        this.sandboxes.delete(sandbox.providerRef);
+    }
+    async status(sandbox) {
+        const state = this.sandboxes.get(sandbox.providerRef);
+        if (!state)
+            return "missing";
+        return state.running ? "running" : "stopped";
+    }
+    async exec(sandbox, command, options = {}) {
+        await this.record("exec", sandbox.id, command);
+        const state = this.running(sandbox);
+        const result = await this.execHandler({
+            sandboxId: sandbox.id,
+            command,
+            env: { ...state.spec.env, ...command.env },
+        });
+        const stdout = result?.stdout ?? "";
+        const stderr = result?.stderr ?? "";
+        if (stdout)
+            options.onStdout?.(stdout);
+        if (stderr)
+            options.onStderr?.(stderr);
+        return { exitCode: result?.exitCode ?? 0, stdout, stderr };
+    }
+    async startMainProcess(sandbox, command) {
+        await this.record("startMainProcess", sandbox.id, command);
+        const state = this.running(sandbox);
+        state.mainProcess = { command, pid: this.nextPid++, running: true, exitCode: null };
+    }
+    async getMainProcess(sandbox) {
+        const process = this.running(sandbox).mainProcess;
+        return process ? { pid: process.pid, running: process.running, exitCode: process.exitCode } : null;
+    }
+    async readMainLog(sandbox, offset) {
+        const log = this.running(sandbox).log;
+        const start = offset > log.length ? 0 : offset;
+        const data = log.slice(start);
+        return { data, nextOffset: start + data.length };
+    }
+    async writeFiles(sandbox, files) {
+        await this.record("writeFiles", sandbox.id);
+        const state = this.running(sandbox);
+        for (const file of files)
+            state.files.set(file.path, file.content.slice());
+    }
+    async readFile(sandbox, path) {
+        await this.record("readFile", sandbox.id);
+        return this.running(sandbox).files.get(path)?.slice() ?? null;
+    }
+    async getUrl(sandbox, port) {
+        await this.record("getUrl", sandbox.id);
+        this.running(sandbox);
+        return `http://${sandbox.providerRef}.mock.localhost:${port}`;
+    }
+    async extendTimeout(sandbox, durationMs) {
+        await this.record("extendTimeout", sandbox.id);
+        this.running(sandbox).timeoutExtensionsMs.push(durationMs);
+    }
+    async record(operation, sandboxId, command) {
+        this.calls.push({ operation, sandboxId, ...(command && { command }) });
+        await this.beforeOperation?.(operation, sandboxId);
+    }
+    async delay() {
+        if (this.lifecycleDelayMs > 0)
+            await new Promise((resolve) => setTimeout(resolve, this.lifecycleDelayMs));
+    }
+    lookup(sandbox) {
+        const state = this.sandboxes.get(sandbox.providerRef);
+        if (!state)
+            throw new ProviderSandboxMissingError(sandbox.providerRef);
+        return state;
+    }
+    running(sandbox) {
+        const state = this.lookup(sandbox);
+        if (!state.running)
+            throw new ProviderSandboxStoppedError(sandbox.providerRef);
+        return state;
+    }
+    mustGetState(sandboxId) {
+        const state = this.getState(sandboxId);
+        if (!state)
+            throw new SandboxError(`Mock sandbox "${sandboxId}" does not exist`);
+        return state;
+    }
+}