@promigence/sdk 0.1.0-beta.12

package/dist/sandbox.js

@@ -0,0 +1,725 @@
+import { inspect } from "node:util";
+import { ApiError, CommandExitError, EnvFailedError, IMAGE_BUILD_TIMEOUT_MS, InvalidArgumentError, NotFoundError, TimeoutError, UnsupportedError, WAIT_TIMEOUT_MS, withPreviewsFix, } from "./core.js";
+import { PromigenceClient, LONG_POLL_MS, checkImageRef, checkImageVersioned, checkSandboxId, errorFor, newIdempotencyKey, toCommandResult, isWaiting, } from "./client.js";
+import { CommandHandle } from "./handles.js";
+import { CommandTimeoutError, answerTimedOut } from "./command-errors.js";
+import { hintArg } from "./hint.js";
+const EXEC_TIMEOUT_DEFAULT_MS = 15 * 60_000;
+function textSink(cb) {
+    if (!cb)
+        return undefined;
+    const dec = new TextDecoder();
+    return {
+        push: (b) => { const t = dec.decode(b, { stream: true }); if (t)
+            cb(t); },
+        end: () => { const t = dec.decode(); if (t)
+            cb(t); },
+    };
+}
+let uploadSeq = 0;
+export const DEFAULT_PTY_CMD = "TERM=${TERM:-xterm-256color} exec /bin/sh -l";
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export function ptyCommand(opts) {
+    const envs = Object.entries(opts.envs ?? {});
+    if (!opts.cwd && envs.length === 0)
+        return opts.cmd;
+    const parts = [];
+    if (opts.cwd)
+        parts.push(`cd ${shellQuote(opts.cwd)} &&`);
+    for (const [k, v] of envs) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) {
+            throw new InvalidArgumentError(`env name ${JSON.stringify(k)} is not a valid variable name`, "Use [A-Za-z_][A-Za-z0-9_]*.");
+        }
+        parts.push(`export ${k}=${shellQuote(v)};`);
+    }
+    parts.push(opts.cmd ?? DEFAULT_PTY_CMD);
+    return parts.join(" ");
+}
+function permString(mode) {
+    const r = (m) => `${m & 4 ? "r" : "-"}${m & 2 ? "w" : "-"}${m & 1 ? "x" : "-"}`;
+    return r((mode >> 6) & 7) + r((mode >> 3) & 7) + r(mode & 7);
+}
+export function toEntryInfo(e) {
+    const mode = parseInt(e.mode, 8) || 0;
+    return {
+        name: e.name,
+        path: e.path,
+        type: e.is_dir ? "dir" : "file",
+        size: e.size,
+        mode,
+        permissions: permString(mode),
+        modifiedTime: new Date(Math.floor(e.mtime_unix_ns / 1e6)),
+        isSymlink: e.is_symlink,
+    };
+}
+export function toEntryInfoFromPath(f) {
+    const at = f.path.lastIndexOf("/");
+    return toEntryInfo({ ...f, name: at < 0 ? f.path : f.path.slice(at + 1) });
+}
+function buildIsFree(b) {
+    return b.deduped === true || b.joined === true || b.idempotent_replay === true || b.state === "verified" || b.state === "built";
+}
+function buildNotice(image) {
+    return (b) => {
+        if (buildIsFree(b))
+            return;
+        const price = typeof b.build_price === "number"
+            ? typeof b.per_second_usd === "number"
+                ? `billed per second while it builds ($${Number(b.per_second_usd.toPrecision(12))}/s), at most $${b.build_price.toFixed(2)}`
+                : `build_price $${b.build_price.toFixed(2)}, charged once it verifies`
+            : "billed at your plan's rates";
+        process.emitWarning(`building a snapshot of ${image}: ${price} (later creates from this image reuse it free)`, { code: "PROMIGENCE_BUILD" });
+    };
+}
+function buildNotAllowed(image) {
+    return new InvalidArgumentError(`Sandbox.create({ image: ${JSON.stringify(image)} }) builds that image's snapshot unless one already exists, and a new build is billed per second while it runs (\`promigence pricing\` shows the rates; reusing a snapshot already built is free). Nothing was sent.`, `To allow the build: Sandbox.create({ image: ${JSON.stringify(image)}, allowBuild: true }). Or build it once, ` +
+        `\`promigence snapshot create --image ${hintArg(image)} --alias NAME\`, and create from its name: Sandbox.create("NAME").`);
+}
+export async function imageSnapshot(client, opts, hooks = {}) {
+    const create = { image: opts.image };
+    if (opts.setup !== undefined)
+        create.setup = opts.setup;
+    if (opts.verify !== undefined)
+        create.verify = opts.verify;
+    if (opts.start !== undefined)
+        create.start = opts.start;
+    if (opts.tier !== undefined)
+        create.tier = opts.tier;
+    if (opts.alias !== undefined)
+        create.alias = opts.alias;
+    if (opts.registrySecret !== undefined)
+        create.registrySecret = opts.registrySecret;
+    let build = (await client.snapshots.create(create)) ?? {};
+    if (hooks.onBuild)
+        await hooks.onBuild(build);
+    const buildId = build.build_id;
+    if (build.state === "queued" || build.state === "running") {
+        if (!buildId) {
+            throw new ApiError({
+                code: "internal", message: "POST /snapshots started a build but returned no build_id",
+                fix: "Not your fault. Re-run; if it repeats, include the request_id when reporting.", exitCode: 1,
+            });
+        }
+        const bound = opts.buildTimeoutMs ?? IMAGE_BUILD_TIMEOUT_MS;
+        const abortedBuild = () => new TimeoutError(`Sandbox.create was aborted by the caller's signal while image build ${buildId} ran; no sandbox was started, and the build goes on`, `Nothing to fix: the caller aborted it. The build is charged if it verifies, and later creates from this image reuse it: \`promigence snapshot status ${hintArg(buildId)} --wait\`.`);
+        let waited;
+        try {
+            waited = await client.snapshots.waitBuild(buildId, { waitTimeoutMs: bound, ...(hooks.signal ? { signal: hooks.signal } : {}) });
+        }
+        catch (e) {
+            if (hooks.signal?.aborted)
+                throw abortedBuild();
+            throw e;
+        }
+        if (hooks.signal?.aborted)
+            throw abortedBuild();
+        if (waited.timedOut) {
+            throw new TimeoutError(`image build ${buildId} was still running after ${bound} ms; nothing was cancelled`, `Wait for it: \`promigence snapshot status ${hintArg(buildId)} --wait\`, then call Sandbox.create({ image }) again — the same digest reuses the build.`);
+        }
+        build = waited.build ?? {};
+    }
+    const state = build.state;
+    if (build.snapshot_id && state !== "rejected" && state !== "failed")
+        return build.snapshot_id;
+    const err = build.error && typeof build.error === "object" ? build.error : {};
+    throw errorFor(err.code ?? "snapshot_failed", err.message ?? `image build ${buildId ?? "?"} ended ${state ?? "without a state"} with no snapshot`, buildId ? `Read the build log: \`promigence snapshot status ${hintArg(buildId)} --log 80\`.` : "Re-run; if it repeats, include the request_id when reporting.");
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+    promise.catch(() => { });
+    const d = { promise, settled: false, resolve: (v) => { d.settled = true; resolve(v); }, reject: (e) => { d.settled = true; reject(e); } };
+    return d;
+}
+async function abandonQueued(client, sandboxId, runId, bound) {
+    const ids = { sandboxId, runId };
+    try {
+        await client.runs.kill(runId);
+    }
+    catch {
+        return new TimeoutError(`sandbox ${sandboxId} was still queued after ${bound} ms, and cancelling it failed: it may still start`, `Cancel it: \`promigence run kill ${hintArg(runId)}\`, or keep it: \`promigence run status ${hintArg(runId)} --wait\`.`, ids);
+    }
+    return new TimeoutError(`sandbox ${sandboxId} was still queued after ${bound} ms; it was cancelled, so it will not start later`, "Create again, or wait longer with `waitTimeoutMs`. A sandbox cancelled while queued is not billed.", ids);
+}
+const CREATE_CLEANUP_MS = 10_000;
+async function endInterruptedCreate(client, runId, sent) {
+    try {
+        let id = runId;
+        if (id === undefined && sent !== undefined) {
+            const { waitMs: _park, signal: _gone, ...again } = sent;
+            id = (await client.runs.start({ ...again, signal: AbortSignal.timeout(CREATE_CLEANUP_MS) })).run_id;
+        }
+        if (id)
+            await client.runs.kill(id);
+    }
+    catch {
+    }
+}
+const creatingNow = new Set();
+let sigintHeld = false;
+function onSigint() {
+    sigintHeld = false;
+    const cleanups = [...creatingNow];
+    creatingNow.clear();
+    if (process.listenerCount("SIGINT") > 0)
+        return;
+    void Promise.allSettled(cleanups.map((f) => f())).finally(() => { process.kill(process.pid, "SIGINT"); });
+}
+function holdSigint(cleanup) {
+    if (typeof process === "undefined" || typeof process.listenerCount !== "function")
+        return () => { };
+    if (process.listenerCount("SIGINT") - (sigintHeld ? 1 : 0) > 0)
+        return () => { };
+    creatingNow.add(cleanup);
+    if (!sigintHeld) {
+        process.once("SIGINT", onSigint);
+        sigintHeld = true;
+    }
+    return () => {
+        creatingNow.delete(cleanup);
+        if (creatingNow.size === 0 && sigintHeld) {
+            process.removeListener("SIGINT", onSigint);
+            sigintHeld = false;
+        }
+    };
+}
+export const DEFAULT_SNAPSHOT = "promigence/base";
+export function spendCapFromEnv(spendCap) {
+    if (spendCap !== undefined)
+        return spendCap;
+    const env = process.env["PROMIGENCE_SPEND_CAP"];
+    if (env !== undefined && env !== "" && Number.isFinite(Number(env)))
+        return Number(env);
+    return undefined;
+}
+export async function resolveSpendCap(client, spendCap) {
+    if (spendCap !== undefined)
+        return spendCap;
+    const env = process.env["PROMIGENCE_SPEND_CAP"];
+    if (env !== undefined && env !== "" && Number.isFinite(Number(env)))
+        return Number(env);
+    const me = await client.me();
+    if (typeof me.default_spend_cap === "number")
+        return me.default_spend_cap;
+    throw new InvalidArgumentError("no spend cap: every run must be capped before it starts", "Pass { spendCap: 1 } (USD), set PROMIGENCE_SPEND_CAP, or ask for an org default_spend_cap (GET /me).");
+}
+export class Sandbox {
+    sandboxId;
+    runId;
+    snapshot;
+    #client;
+    #envs;
+    timeoutMs;
+    dirty = false;
+    commands;
+    pty;
+    ports;
+    terminals = new Map();
+    files;
+    constructor(init) {
+        this.sandboxId = init.sandboxId;
+        this.runId = init.runId;
+        this.snapshot = init.snapshot;
+        this.#client = init.client;
+        this.#envs = init.envs;
+        this.timeoutMs = init.timeoutMs;
+        const runBackground = async (cmd, opts) => {
+            this.dirty = true;
+            const env = { ...(this.#envs ?? {}), ...(opts.envs ?? {}) };
+            const rec = await this.#client.sandboxes.execBackground(this.sandboxId, {
+                sh: cmd,
+                ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+                ...(Object.keys(env).length === 0 ? {} : { env }),
+                ...(opts.user === undefined ? {} : { user: opts.user }),
+                ...(opts.stdin ? { stdin: true } : {}),
+                ...(opts.timeoutMs === undefined || opts.timeoutMs === 0 ? {} : { timeoutMs: opts.timeoutMs }),
+                ...(opts.maxOutputBytes === undefined ? {} : { maxOutputBytes: opts.maxOutputBytes }),
+            });
+            return new CommandHandle(this.#client, rec, {
+                ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+                ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+                ...(opts.timeoutMs === undefined || opts.timeoutMs === 0 ? {} : { timeoutMs: opts.timeoutMs }),
+            });
+        };
+        this.commands = {
+            run: (async (cmd, opts = {}) => {
+                if (opts.background)
+                    return runBackground(cmd, opts);
+                const fg = opts;
+                this.dirty = true;
+                const env = this.#envs === undefined && fg.envs === undefined ? undefined : { ...(this.#envs ?? {}), ...(fg.envs ?? {}) };
+                const bound = fg.timeoutMs === undefined || fg.timeoutMs === 0 ? (this.timeoutMs || undefined) : fg.timeoutMs;
+                const exec = { sh: cmd };
+                if (fg.cwd !== undefined)
+                    exec.cwd = fg.cwd;
+                if (env !== undefined && Object.keys(env).length !== 0)
+                    exec.env = env;
+                if (fg.user !== undefined)
+                    exec.user = fg.user;
+                if (bound !== undefined)
+                    exec.timeoutMs = bound;
+                if (fg.maxOutputBytes !== undefined)
+                    exec.maxOutputBytes = fg.maxOutputBytes;
+                let res;
+                const out = textSink(fg.onStdout);
+                const err = textSink(fg.onStderr);
+                if (out || err) {
+                    res = await this.#client.sandboxes.execStream(this.sandboxId, exec, {
+                        ...(out ? { stdout: out.push } : {}),
+                        ...(err ? { stderr: err.push } : {}),
+                    });
+                    out?.end();
+                    err?.end();
+                }
+                else {
+                    res = await this.#client.sandboxes.exec(this.sandboxId, exec);
+                }
+                const result = toCommandResult(res);
+                if (result.exitCode !== 0 && fg.throwOnExit !== false) {
+                    if (answerTimedOut(res))
+                        throw new CommandTimeoutError(result, bound ?? EXEC_TIMEOUT_DEFAULT_MS);
+                    throw new CommandExitError(result);
+                }
+                return result;
+            }),
+            list: async () => {
+                const execs = await this.#client.sandboxes.execs.list(this.sandboxId);
+                return execs.map((e) => {
+                    const code = e.exit ? (e.exit.exit_code ?? (e.exit.signal ? 128 + e.exit.signal : -1)) : undefined;
+                    return { pid: e.exec_id, cmd: e.argv, state: e.state, ...(code === undefined ? {} : { exitCode: code }) };
+                });
+            },
+            kill: async (pid) => (await this.#client.sandboxes.execs.signal(this.sandboxId, pid, "SIGKILL")).delivered,
+            connect: async (pid, opts = {}) => {
+                const rec = await this.#client.sandboxes.execs.get(this.sandboxId, pid);
+                return new CommandHandle(this.#client, rec, opts);
+            },
+            sendStdin: async (pid, data) => (await this.#client.sandboxes.execs.stdin(this.sandboxId, pid, { data })).written,
+            closeStdin: async (pid) => {
+                await this.#client.sandboxes.execs.stdin(this.sandboxId, pid, { eof: true });
+            },
+        };
+        const terminal = (pid) => {
+            const t = this.terminals.get(pid);
+            if (!t) {
+                throw new NotFoundError(`no terminal with pid ${pid} is open from this Sandbox object`, "A terminal belongs to the connection that opened it: use the session pty.create() returned, or open a new one.");
+            }
+            return t;
+        };
+        this.pty = {
+            create: async (opts = {}) => {
+                const cmd = ptyCommand({
+                    ...(opts.cmd === undefined ? {} : { cmd: opts.cmd }),
+                    ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+                    envs: { ...(this.#envs ?? {}), ...(opts.envs ?? {}) },
+                });
+                let pid = -1;
+                const session = await this.#client.sandboxes.pty(this.sandboxId, {
+                    ...(opts.cols === undefined ? {} : { cols: opts.cols }),
+                    ...(opts.rows === undefined ? {} : { rows: opts.rows }),
+                    ...(cmd === undefined ? {} : { cmd }),
+                    ...(opts.secrets?.length ? { secrets: opts.secrets } : {}),
+                    ...(opts.onData ? { onData: opts.onData } : {}),
+                    ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                    ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                    reconnect: opts.reconnect ?? opts.cmd === undefined,
+                    ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
+                    onExit: (e) => { this.terminals.delete(pid); opts.onExit?.(e); },
+                });
+                pid = session.pid;
+                this.dirty = true;
+                this.terminals.set(session.pid, session);
+                return session;
+            },
+            sendInput: async (pid, data) => { terminal(pid).write(data); },
+            resize: async (pid, size) => { terminal(pid).resize(size); },
+            kill: async (pid) => {
+                const t = this.terminals.get(pid);
+                if (!t)
+                    return false;
+                t.signal(9);
+                return true;
+            },
+        };
+        this.ports = {
+            expose: (port) => this.#client.sandboxes.ports.expose(this.sandboxId, port),
+            list: () => this.#client.sandboxes.ports.list(this.sandboxId),
+            revoke: async (tokenOrPort) => (await this.#client.sandboxes.ports.revoke(this.sandboxId, tokenOrPort)).revoked,
+        };
+        this.files = {
+            read: (async (path, opts = {}) => {
+                const format = opts.format ?? "text";
+                if (format !== "text" && format !== "bytes") {
+                    throw new InvalidArgumentError(`files.read format must be "text" or "bytes", got ${JSON.stringify(format)}`, "Pass { format: 'bytes' } and wrap the bytes yourself (new Blob([bytes]) for a Blob).");
+                }
+                const bytes = await this.#client.sandboxes.files.get(this.sandboxId, path);
+                return format === "bytes" ? bytes : new TextDecoder().decode(bytes);
+            }),
+            write: async (path, data, opts = {}) => {
+                let body;
+                if (typeof data === "string" || data instanceof Uint8Array)
+                    body = data;
+                else if (data instanceof ArrayBuffer)
+                    body = new Uint8Array(data);
+                else if (ArrayBuffer.isView(data))
+                    body = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+                else if (typeof Blob !== "undefined" && data instanceof Blob)
+                    body = new Uint8Array(await data.arrayBuffer());
+                else {
+                    throw new InvalidArgumentError(`files.write data must be a string, a typed array, an ArrayBuffer or a Blob, got ${data === null ? "null" : typeof data}`, "Pass text, or the bytes as a Uint8Array.");
+                }
+                this.dirty = true;
+                await this.#client.sandboxes.files.put(this.sandboxId, path, body, opts.mode === undefined ? {} : { mode: opts.mode });
+            },
+            remove: async (path, opts = {}) => {
+                this.dirty = true;
+                await this.#client.sandboxes.files.delete(this.sandboxId, path, opts);
+            },
+            exists: async (path) => {
+                try {
+                    await this.#client.sandboxes.files.stat(this.sandboxId, path);
+                    return true;
+                }
+                catch (e) {
+                    if (e instanceof NotFoundError)
+                        return false;
+                    throw e;
+                }
+            },
+            list: async (path = "/", opts = {}) => {
+                const o = opts.depth !== undefined && opts.depth > 1 && opts.recursive === undefined ? { ...opts, recursive: true } : opts;
+                const r = await this.#client.sandboxes.files.list(this.sandboxId, path, o);
+                return r.entries.map(toEntryInfo);
+            },
+            mkdir: async (path, opts = {}) => {
+                this.dirty = true;
+                return toEntryInfoFromPath(await this.#client.sandboxes.files.mkdir(this.sandboxId, path, opts));
+            },
+            move: async (from, to, opts = {}) => {
+                this.dirty = true;
+                return toEntryInfoFromPath(await this.#client.sandboxes.files.move(this.sandboxId, from, to, opts));
+            },
+            rename: async (from, to, opts = {}) => this.files.move(from, to, opts),
+            copy: async (from, to, opts = {}) => {
+                this.dirty = true;
+                return toEntryInfoFromPath(await this.#client.sandboxes.files.copy(this.sandboxId, from, to, opts));
+            },
+            chmod: async (path, opts) => {
+                this.dirty = true;
+                return toEntryInfoFromPath(await this.#client.sandboxes.files.chmod(this.sandboxId, path, opts));
+            },
+            search: async (path, opts) => (await this.#client.sandboxes.files.search(this.sandboxId, path, opts)).matches,
+            downloadDir: async (path, opts = {}) => {
+                this.dirty = true;
+                const made = await this.#client.sandboxes.files.archive(this.sandboxId, path, opts);
+                try {
+                    return await this.#client.sandboxes.files.get(this.sandboxId, made.archive_path);
+                }
+                finally {
+                    await this.#client.sandboxes.files.delete(this.sandboxId, made.archive_path).catch(() => { });
+                }
+            },
+            uploadDir: async (tar, into, opts = {}) => {
+                this.dirty = true;
+                const scratch = `/tmp/.promigence-upload/up-${Date.now().toString(36)}-${(uploadSeq++).toString(36)}.tar`;
+                await this.#client.sandboxes.files.put(this.sandboxId, scratch, tar, {});
+                try {
+                    return await this.#client.sandboxes.files.extract(this.sandboxId, scratch, into, { strip: opts.strip ?? 1 });
+                }
+                finally {
+                    await this.#client.sandboxes.files.delete(this.sandboxId, scratch).catch(() => { });
+                }
+            },
+        };
+    }
+    static async create(arg, second = {}) {
+        const opts = typeof arg === "object" && arg !== null ? arg : second;
+        let snapshotIdOrAlias = typeof arg === "string" ? arg : opts.snapshot;
+        if (snapshotIdOrAlias !== undefined && opts.image !== undefined) {
+            throw new InvalidArgumentError("Sandbox.create takes a snapshot or an image, not both", "Pass Sandbox.create('promigence/base') or Sandbox.create({ image: 'registry/name@sha256:…' }).");
+        }
+        if (opts.tier !== undefined && opts.image === undefined) {
+            throw new InvalidArgumentError(`Sandbox.create: tier "${opts.tier}" needs an image; a sandbox from a snapshot has the snapshot's size (the built-in base is small)`, "Pass image: 'registry/name@sha256:…' with the tier, or build a snapshot at that size once " +
+                "(promigence snapshot create --image REF --tier large) and create from its alias.");
+        }
+        if (opts.image !== undefined) {
+            checkImageRef(opts.image);
+            checkImageVersioned(opts.image);
+            if (opts.allowBuild !== true)
+                throw buildNotAllowed(opts.image.trim());
+        }
+        const client = opts.client ?? new PromigenceClient({
+            ...(opts.apiKey === undefined ? {} : { apiKey: opts.apiKey }),
+            ...(opts.apiUrl === undefined ? {} : { apiUrl: opts.apiUrl }),
+        });
+        const aborted = () => new TimeoutError("Sandbox.create was aborted by the caller's signal; anything it had started was ended", "Nothing to fix: the caller aborted it.");
+        if (opts.signal?.aborted)
+            throw aborted();
+        if (opts.image !== undefined) {
+            try {
+                snapshotIdOrAlias = await imageSnapshot(client, opts, {
+                    onBuild: opts.onBuild ?? buildNotice(opts.image.trim()),
+                    ...(opts.signal ? { signal: opts.signal } : {}),
+                });
+            }
+            catch (e) {
+                if (opts.signal?.aborted && !(e instanceof TimeoutError))
+                    throw aborted();
+                throw e;
+            }
+            if (opts.signal?.aborted)
+                throw aborted();
+        }
+        else if (snapshotIdOrAlias === undefined || snapshotIdOrAlias === "base") {
+            snapshotIdOrAlias = DEFAULT_SNAPSHOT;
+        }
+        const stop = new AbortController();
+        const key = newIdempotencyKey();
+        let sent;
+        let runId;
+        let ending;
+        const end = () => (ending ??= endInterruptedCreate(client, runId, sent));
+        const release = holdSigint(() => { stop.abort(); return end(); });
+        const onAbort = () => { stop.abort(); };
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            let handles;
+            try {
+                ({ runId, handles } = await Sandbox.forkHandlesWith(snapshotIdOrAlias, { ...opts, count: 1, client }, {
+                    idempotencyKey: key, signal: stop.signal, onStart: (s) => { sent = s; },
+                }));
+            }
+            catch (e) {
+                if (stop.signal.aborted) {
+                    await end();
+                    throw aborted();
+                }
+                throw e;
+            }
+            const first = handles[0];
+            try {
+                if (!first)
+                    throw new EnvFailedError("not_started", "no sandbox was started", "Re-run; if it repeats, check `promigence run report <run_id>`.");
+                return await first;
+            }
+            catch (e) {
+                if (stop.signal.aborted) {
+                    await end();
+                    throw aborted();
+                }
+                if (e instanceof TimeoutError && e.runId === runId && e.sandboxId !== undefined) {
+                    throw await abandonQueued(client, e.sandboxId, runId, opts.waitTimeoutMs ?? WAIT_TIMEOUT_MS);
+                }
+                await client.runs.kill(runId).catch(() => { });
+                throw e;
+            }
+        }
+        finally {
+            release();
+            opts.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    static async fork(snapshotIdOrAlias, opts = {}) {
+        const { handles } = await Sandbox.forkHandles(snapshotIdOrAlias, opts);
+        return Promise.all(handles);
+    }
+    static async forkHandles(snapshotIdOrAlias, opts = {}) {
+        return Sandbox.forkHandlesWith(snapshotIdOrAlias, opts, {});
+    }
+    static async forkHandlesWith(snapshotIdOrAlias, opts, extra) {
+        const client = opts.client ?? new PromigenceClient({
+            ...(opts.apiKey === undefined ? {} : { apiKey: opts.apiKey }),
+            ...(opts.apiUrl === undefined ? {} : { apiUrl: opts.apiUrl }),
+        });
+        const count = opts.count ?? 1;
+        const spendCap = spendCapFromEnv(opts.spendCap);
+        const start = { snapshot: snapshotIdOrAlias, count };
+        if (spendCap !== undefined)
+            start.spendCap = spendCap;
+        if (count === 1)
+            start.waitMs = Math.min(opts.waitTimeoutMs ?? WAIT_TIMEOUT_MS, LONG_POLL_MS);
+        if (opts.timeoutMs !== undefined)
+            start.timeoutMs = opts.timeoutMs;
+        if (opts.allowInternetAccess === false)
+            start.network = "none";
+        if (opts.allowHosts?.length)
+            start.network = { allow: opts.allowHosts };
+        if (opts.metadata)
+            start.labels = opts.metadata;
+        if (opts.secrets?.length)
+            start.secrets = opts.secrets;
+        if (opts.optimizeFor !== undefined)
+            start.optimizeFor = opts.optimizeFor;
+        if (extra.idempotencyKey !== undefined)
+            start.idempotencyKey = extra.idempotencyKey;
+        extra.onStart?.({ ...start });
+        const run = await client.runs.start(extra.signal === undefined ? start : { ...start, signal: extra.signal });
+        const envs = opts.envs;
+        const mk = (ref) => {
+            const init = { sandboxId: ref.sandbox_id, runId: run.run_id, snapshot: snapshotIdOrAlias, client };
+            if (envs !== undefined)
+                init.envs = envs;
+            if (opts.timeoutMs !== undefined)
+                init.timeoutMs = opts.timeoutMs;
+            return new Sandbox(init);
+        };
+        const only = run.sandboxes?.length === 1 ? run.sandboxes[0] : undefined;
+        if (only !== undefined && !isWaiting(only.state) && only.state !== "ended") {
+            const sb = mk(only);
+            opts.onReady?.(sb, 0);
+            return { runId: run.run_id, handles: [Promise.resolve(sb)] };
+        }
+        const pending = new Map();
+        const order = [];
+        for (const ref of run.sandboxes ?? []) {
+            order.push(ref.sandbox_id);
+            pending.set(ref.sandbox_id, deferred());
+        }
+        const settle = (ref, index) => {
+            const d = pending.get(ref.sandbox_id);
+            if (!d || d.settled)
+                return;
+            if (ref.state === "ended") {
+                d.reject(new EnvFailedError("env_failed", `sandbox ${ref.sandbox_id} ended before hand-over`, `Not billed. Read the evidence: \`promigence run report ${hintArg(run.run_id)}\`.`));
+                return;
+            }
+            const sb = mk(ref);
+            d.resolve(sb);
+            opts.onReady?.(sb, index);
+        };
+        (run.sandboxes ?? []).forEach((ref, i) => { if (!isWaiting(ref.state))
+            settle(ref, i); });
+        if ([...pending.values()].some((d) => !d.settled)) {
+            const bound = opts.waitTimeoutMs ?? WAIT_TIMEOUT_MS;
+            void client.runs
+                .waitReady(run.run_id, {
+                waitTimeoutMs: bound, onReady: (ref) => settle(ref, order.indexOf(ref.sandbox_id)),
+                ...(extra.signal === undefined ? {} : { signal: extra.signal }),
+            })
+                .then((res) => {
+                if (!res.timedOut)
+                    return;
+                for (const [id, d] of pending) {
+                    if (d.settled)
+                        continue;
+                    d.reject(new TimeoutError(`sandbox ${id} was still queued after ${bound} ms; nothing was killed`, `Run the id-based command: \`promigence run status ${hintArg(run.run_id)} --wait\` or \`promigence run report ${hintArg(run.run_id)}\`.`, { sandboxId: id, runId: run.run_id }));
+                }
+            })
+                .catch((err) => {
+                for (const d of pending.values())
+                    if (!d.settled)
+                        d.reject(err);
+            });
+        }
+        return { runId: run.run_id, handles: order.map((id) => pending.get(id).promise) };
+    }
+    static async connect(sandboxId, opts = {}) {
+        checkSandboxId(sandboxId, "Sandbox.connect");
+        const client = opts.client ?? new PromigenceClient({
+            ...(opts.apiKey === undefined ? {} : { apiKey: opts.apiKey }),
+            ...(opts.apiUrl === undefined ? {} : { apiUrl: opts.apiUrl }),
+        });
+        const rec = await client.sandboxes.get(sandboxId);
+        return new Sandbox({
+            sandboxId: rec.sandbox_id ?? sandboxId,
+            runId: rec.run_id ?? "",
+            snapshot: rec.snapshot_id ?? "",
+            client,
+            ...(opts.envs === undefined ? {} : { envs: opts.envs }),
+            ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+        });
+    }
+    static async list(opts = {}) {
+        return (await Sandbox.listPage(opts)).items;
+    }
+    static async listPage(opts = {}) {
+        const c = opts.client ?? new PromigenceClient();
+        return c.sandboxes.listPage({
+            limit: opts.limit ?? 50,
+            ...(opts.labels ? { labels: opts.labels } : {}),
+            ...(opts.state?.length ? { state: opts.state } : {}),
+            ...(opts.cursor ? { cursor: opts.cursor } : {}),
+        });
+    }
+    async fork(opts = {}) {
+        if (this.dirty && opts.fromOrigin !== true) {
+            throw new UnsupportedError("sandbox.fork() on a sandbox that has changed since it started", `To fork it as it is now: \`const s = await client.sandboxes.snapshot(${JSON.stringify(this.sandboxId)})\` (a live snapshot; it ends background commands), then \`Sandbox.fork(s.snapshot_id, { count })\`. To fork the snapshot it came from instead, pass { fromOrigin: true }.`);
+        }
+        let origin = this.snapshot;
+        if (!origin && this.runId)
+            origin = (await this.#client.runs.get(this.runId)).snapshot_id ?? "";
+        if (!origin) {
+            throw new UnsupportedError("sandbox.fork() without a known origin snapshot", "Use Sandbox.fork('<snapshot>', { count }) or client.runs.start({ snapshot, count }).");
+        }
+        return Sandbox.fork(origin, {
+            client: this.#client,
+            count: opts.count ?? 1,
+            ...(opts.waitTimeoutMs === undefined ? {} : { waitTimeoutMs: opts.waitTimeoutMs }),
+            ...(opts.onReady === undefined ? {} : { onReady: opts.onReady }),
+        });
+    }
+    toJSON() {
+        return { sandboxId: this.sandboxId, runId: this.runId, snapshot: this.snapshot };
+    }
+    [inspect.custom](_depth, opts) {
+        return `Sandbox ${inspect(this.toJSON(), opts)}`;
+    }
+    async kill() {
+        const r = await this.#client.sandboxes.kill(this.sandboxId);
+        return r?.already_ended !== true;
+    }
+    async getInfo() {
+        return this.#client.sandboxes.get(this.sandboxId);
+    }
+    probe(opts = {}) {
+        return this.#client.sandboxes.probe(this.sandboxId, opts);
+    }
+    async isRunning() {
+        const rec = await this.#client.sandboxes.get(this.sandboxId);
+        return rec.state === "ready" || rec.state === "running";
+    }
+    async setTimeout(ms) {
+        await this.#client.sandboxes.patch(this.sandboxId, { timeoutMs: ms });
+        this.timeoutMs = ms;
+    }
+    async setAutoPause(seconds, mode) {
+        await this.#client.sandboxes.patch(this.sandboxId, {
+            autoPauseS: seconds,
+            ...(mode !== undefined ? { autoPauseMode: mode } : {}),
+        });
+    }
+    async getAutoPause() {
+        const rec = await this.#client.sandboxes.get(this.sandboxId);
+        return Number(rec.auto_pause_s ?? 0);
+    }
+    async disableInternet() {
+        await this.#client.sandboxes.setNetworkNone(this.sandboxId);
+    }
+    async getHost(port) {
+        const existing = (await withPreviewsFix(this.#client.sandboxes.ports.list(this.sandboxId), this.sandboxId, port)).find((p) => p.port === port);
+        const rec = existing ?? await this.#client.sandboxes.ports.expose(this.sandboxId, port);
+        return rec.url.replace(/^[a-z]+:\/\//i, "").replace(/\/$/, "");
+    }
+    async pause() {
+        const r = await this.#client.sandboxes.pause(this.sandboxId);
+        return {
+            pausedId: r.paused_id,
+            ...(r.background_execs_killed === undefined ? {} : { backgroundExecsKilled: r.background_execs_killed }),
+            ...(r.warnings?.length ? { warnings: r.warnings } : {}),
+            ...(r.already_paused === true ? { alreadyPaused: true } : {}),
+            ...(r.took_ms === undefined ? {} : { tookMs: r.took_ms }),
+            ...(r.took_ms === undefined ? {} : { pauseMs: r.took_ms }),
+            ...(r.bytes === undefined ? {} : { bytes: r.bytes }),
+        };
+    }
+    async resume(opts = {}) {
+        const r = await this.#client.sandboxes.resume(this.sandboxId, opts);
+        return {
+            ...(r.took_ms === undefined ? {} : { tookMs: r.took_ms }),
+            ...(r.took_ms === undefined ? {} : { resumeMs: r.took_ms }),
+        };
+    }
+}