@prized/sdk 0.0.0-stage → 0.1.1

package/dist/cjs/output.js

@@ -0,0 +1,383 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUN_SCRIPT = exports.COMMAND_VAR = exports.SCRIPT_VAR = exports.FULL_OUTPUT_BYTES = exports.OUTPUT_ID_RE = exports.OUTPUT_DIR = void 0;
+exports.captureScript = captureScript;
+exports.collectScript = collectScript;
+exports.removeOutputScript = removeOutputScript;
+exports.parseMarker = parseMarker;
+exports.markerTruncation = markerTruncation;
+exports.execFullOutput = execFullOutput;
+// exec(..., { fullOutput: true }): one call that keeps a command's whole
+// output, not just the first 4 MiB of each stream the sandbox answers with.
+//
+// The command's stdout and stderr stay pipes, as in a plain exec. A relay on
+// each passes what comes through to a reader that copies it to a file in the
+// exec's own directory, at a fixed path under the sandbox user's home, and
+// drops what passes 100 MiB, so a runaway command cannot fill the disk:
+//
+//   ~/.prized/exec/<exec id>/stdout
+//   ~/.prized/exec/<exec id>/stderr
+//
+// Both under 4 MiB: the script prints them back and removes the directory,
+// so the answer carries the same output a plain exec's does. Bigger, or a
+// reader that could not write its file (a full disk): it prints one marker
+// line instead, and the SDK downloads both files through the files API and
+// removes the directory. A stream whose write failed comes back as far as it
+// got, `truncated` with `truncatedReason: 'write_failed'`. The scripts are the Python SDK's
+// (sdk/python/src/prized/_output.py), rendered the same; both SDKs check
+// them against sdk/output-scripts/.
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+const outcome_js_1 = require("./outcome.js");
+const shell_js_1 = require("./shell.js");
+const toolbox_js_1 = require("./toolbox.js");
+exports.OUTPUT_DIR = '/home/prized/.prized/exec';
+exports.OUTPUT_ID_RE = /^exec_[0-9a-f]{16}$/;
+/** Each stream of a fullOutput command keeps at most this many bytes: one download. */
+exports.FULL_OUTPUT_BYTES = toolbox_js_1.MAX_FILE_BYTES;
+/**
+ * The variables that carry the script and the caller's command, so neither
+ * is in the argv of any process but the command's own shell: `pkill -f`
+ * finds what it finds in a plain exec. The script unsets both first.
+ */
+exports.SCRIPT_VAR = 'PRIZED_EXEC_SCRIPT';
+exports.COMMAND_VAR = 'PRIZED_EXEC_COMMAND';
+/** What a fullOutput exec sends as its command: the script, from SCRIPT_VAR. */
+exports.RUN_SCRIPT = `eval "\${${exports.SCRIPT_VAR}:?}"`;
+/** How long the readers may run on after the command (the sandbox's own wait for a plain exec's pipes). */
+const GRACE_S = 5;
+/**
+ * A directory older than this is one an earlier exec could not remove: no
+ * exec runs it that long (MAX_BLOCKING_EXEC_MS, then GRACE_S and READ_MS).
+ */
+const STALE_MIN = 60;
+/** The bound on each request the SDK makes on its own to collect or remove the files. */
+const TEARDOWN_MS = 10_000;
+/** The bound on reading the files back, retries included (files.ts FILE_TIMEOUT_MS). */
+const READ_MS = 10 * 60_000;
+function checkId(id) {
+    if (!exports.OUTPUT_ID_RE.test(id))
+        throw new Error(`unreachable: bad exec id ${id}`);
+}
+/**
+ * The reader's own shell (`$1` the file, `$2` its flag): cat writes the file
+ * until a write fails; then the flag, an empty file (it takes no free block),
+ * then the rest drained into /dev/null, and exit 1. `true`, not `:`: a
+ * redirection that fails on a special builtin ends the shell, and with it
+ * the draining.
+ */
+const READER_SHELL = `'cat > "$1" || { true > "$2" || :; cat > /dev/null; exit 1; }'`;
+/**
+ * The reader on one stream: cat copies what the relay passes it to the file
+ * as it comes (each read written at once) until the file reaches
+ * FULL_OUTPUT_BYTES and one 512-byte block more, which tells a cut stream
+ * from a full one. The file size limit (ulimit -f, in 512-byte blocks in
+ * POSIX mode) stops the file there with EFBIG, not SIGXFSZ, and the reader
+ * goes on draining into /dev/null, so the command never meets a closed pipe
+ * and a runaway one cannot fill the disk. A write that fails short of that (a
+ * full disk) stops the file the same way. Either leaves `<name>.failed` at
+ * once, which collect reads when a time limit ended the script before it
+ * could wait for the reader, and the reader exits 1 once its input ends. A
+ * shell per stream (exec), in a session of its own (setsid, same pid): a time
+ * limit or a `kill 0` that ends the command's process group leaves it to
+ * drain what the pipe still holds.
+ */
+function reader(d, name, fifo) {
+    const blocks = exports.FULL_OUTPUT_BYTES / 512 + 1;
+    return (`( exec > /dev/null 2>&1; PATH=${shell_js_1.LAUNCH_PATH}; trap '' XFSZ; ( set -o posix ) && set -o posix; ` +
+        `ulimit -f ${blocks} || :; exec setsid /bin/sh -c ${READER_SHELL} sh ${d}/${name} ${d}/${name}.failed < ${d}/${fifo} ) &`);
+}
+/**
+ * The relay on one stream: cat reads the command's pipe and passes it on to
+ * the reader's. It is what the watchdog stops, never the reader, so the
+ * reader always ends on the end of its input, and its exit status says
+ * whether every write to its file went through. In a session of its own
+ * (setsid, same pid), as the reader is.
+ */
+function relay(d, from, to) {
+    return `( exec > ${d}/${to} 2> /dev/null < /dev/null; PATH=${shell_js_1.LAUNCH_PATH}; exec setsid cat ${d}/${from} ) &`;
+}
+/**
+ * A shell test: process `pid` (shell text) is this exec's relay on `fifo`,
+ * not another process that reused its pid. Its arguments must be exactly
+ * `cat <fifo>` (as setsid execs it), not merely name the exec's directory
+ * somewhere in the command line, as a process the command started may
+ * (`tail -f ~/.prized/exec/<id>/stdout`). /proc ends each argument with a
+ * NUL; here each is one line (a NUL becomes a newline, a newline a space),
+ * as the run scripts' isRun (shell.ts) reads them.
+ */
+function isRelay(pid, fifo) {
+    return `[ "$(tr "\\0\\n" "\\n " < "/proc/${pid}/cmdline" 2> /dev/null | tr "\\n" " ")" = "cat ${fifo} " ]`;
+}
+/**
+ * The bound on waiting for the readers once the command has ended: GRACE_S
+ * seconds, as the sandbox waits for a plain exec's pipes, then the relays
+ * still running stop (each pid checked to be this exec's relay on its own
+ * pipe first, never one reused since): its reader then ends with what came
+ * through, and a process the command left holding its output meets a closed
+ * pipe, as it would there. Stopped early (TERM, once the readers are done),
+ * it takes its sleep with it.
+ */
+function watchdog(d) {
+    return (`( s=; trap '[ -z "$s" ] || kill "$s" 2> /dev/null; exit 0' TERM; sleep ${GRACE_S} & s=$!; wait "$s" || :; ` +
+        `if ${isRelay('$4', `${d}/o`)}; then kill "$4" 2> /dev/null || :; fi; ` +
+        `if ${isRelay('$5', `${d}/e`)}; then kill "$5" 2> /dev/null || :; fi ) > /dev/null 2>&1 &`);
+}
+/**
+ * Sizes, the cut past FULL_OUTPUT_BYTES and the marker line, with `d` set to
+ * the directory and each reader's write failure in `x` and `y` (1 or 0,
+ * failedLines). A cut leaves `<name>.cut`, so collect sent again still reads
+ * the stream as past the bound (its flag is still there, its size no longer
+ * says so). `true`, not `:`, for the same reason as in READER_SHELL.
+ */
+function reportLines(id) {
+    const max = exports.FULL_OUTPUT_BYTES;
+    return {
+        sizes: ['o=$(stat -c %s "$d/stdout" 2> /dev/null || echo 0)', 'e=$(stat -c %s "$d/stderr" 2> /dev/null || echo 0)'],
+        cut: [
+            `if [ "$o" -gt ${max} ]; then truncate -s ${max} "$d/stdout" && true > "$d/stdout.cut" || :; fi`,
+            `if [ "$e" -gt ${max} ]; then truncate -s ${max} "$d/stderr" && true > "$d/stderr.cut" || :; fi`,
+            `echo "prized-output ${id} $o $e $x $y"`,
+        ],
+    };
+}
+/**
+ * Whether each reader failed to write its file (`x` for stdout, `y` for
+ * stderr: nonzero from its exit status, or its flag, after `sizes`): 1 when
+ * it ended in error short of the bound (a full disk or a quota, a file it
+ * could not create, a reader killed), else 0. Past the bound its error is the
+ * cut (EFBIG). The watchdog stops relays, never readers, so a reader's status
+ * is its own.
+ */
+function failedLines() {
+    const max = exports.FULL_OUTPUT_BYTES;
+    return [
+        `if [ "$x" -eq 0 ] || [ "$o" -gt ${max} ]; then x=0; else x=1; fi`,
+        `if [ "$y" -eq 0 ] || [ "$e" -gt ${max} ]; then y=0; else y=1; fi`,
+    ];
+}
+/**
+ * The script a fullOutput exec runs (RUN_SCRIPT, from SCRIPT_VAR). The
+ * caller's command, from COMMAND_VAR, runs as a plain exec runs it (`bash
+ * -c`, or `sh -c` where there is no bash, stdin from /dev/null), with the
+ * request's cwd and env.
+ *
+ * Nothing is assigned before it runs but the positional parameters, so every
+ * variable the caller's env sets reaches it unchanged, PATH included; and
+ * every step holds under an errexit the env may switch on (SHELLOPTS). As in
+ * a plain exec, the relays stop 5 s after the command ends if a process it
+ * left running still holds its output, keeping what came through. A command
+ * a signal ends exits 128+n, as a background command does. A reader that
+ * could not write its file (failedLines) sends the output to the files API
+ * whatever its size, with the marker saying which. Without /bin/sh, setsid,
+ * cat or a directory to write to, the command runs as a plain exec.
+ */
+function captureScript(id) {
+    checkId(id);
+    const d = `${exports.OUTPUT_DIR}/${id}`;
+    const { sizes, cut } = reportLines(id);
+    return [
+        `set -- "\${${exports.COMMAND_VAR}:?}" /bin/bash; unset ${exports.COMMAND_VAR} ${exports.SCRIPT_VAR}; [ -x "$2" ] || set -- "$1" /bin/sh`,
+        `if ( PATH=${shell_js_1.LAUNCH_PATH}; mkdir -p ${exports.OUTPUT_DIR} && mkdir ${d} ) 2> /dev/null; then`,
+        `if ( PATH=${shell_js_1.LAUNCH_PATH}; [ -x /bin/sh ] && command -v setsid && command -v cat && mkfifo ${d}/o ${d}/e ${d}/p ${d}/q ) > /dev/null 2>&1; then`,
+        // The command writes to o and e; a relay passes each on to p and q, where its reader is.
+        reader(d, 'stdout', 'p'),
+        'set -- "$1" "$2" "$!"',
+        reader(d, 'stderr', 'q'),
+        'set -- "$1" "$2" "$3" "$!"',
+        relay(d, 'o', 'p'),
+        'set -- "$1" "$2" "$3" "$4" "$!"',
+        relay(d, 'e', 'q'),
+        'set -- "$1" "$2" "$3" "$4" "$5" "$!"',
+        // bash's "Killed" line for a command a signal ended goes to the braces' /dev/null.
+        `if { "$2" -c "$1" > ${d}/o 2> ${d}/e < /dev/null; } 2> /dev/null; then set -- 0 "$3" "$4" "$5" "$6"; else set -- "$?" "$3" "$4" "$5" "$6"; fi`,
+        `PATH=${shell_js_1.LAUNCH_PATH}`,
+        `c=$1; d=${d}`,
+        watchdog(d),
+        'w=$!',
+        'if wait "$2" 2> /dev/null; then x=0; else x=$?; fi',
+        'if wait "$3" 2> /dev/null; then y=0; else y=$?; fi',
+        'kill "$w" 2> /dev/null || :',
+        ...sizes,
+        ...failedLines(),
+        `if [ "$o" -lt ${toolbox_js_1.MAX_OUTPUT_BYTES} ] && [ "$e" -lt ${toolbox_js_1.MAX_OUTPUT_BYTES} ] && [ "$x$y" = 00 ]; then ` +
+            'cat "$d/stdout" 2> /dev/null || :; cat "$d/stderr" >&2 2> /dev/null || :; rm -rf "$d" || :; exit "$c"; fi',
+        ...cut,
+        'exit "$c"',
+        'fi',
+        `( PATH=${shell_js_1.LAUNCH_PATH}; rm -rf ${d} ) 2> /dev/null || :`,
+        'fi',
+        'exec "$2" -c "$1" < /dev/null',
+    ].join('\n');
+}
+/**
+ * What a fullOutput command left when the script could not print it (its
+ * time limit, or a signal, ended the script): the marker line, or `gone`,
+ * with the directory removed, when there is nothing to read (it was never
+ * made, or its output was already printed back). A failed write is read from
+ * the reader's flag, before the size, which is final once the flag is there
+ * (the script's wait for the reader's exit status went with the script); a
+ * reader killed, or one that could not make its flag, is not seen here.
+ */
+function collectScript(id) {
+    checkId(id);
+    const { sizes, cut } = reportLines(id);
+    return [
+        `d=${exports.OUTPUT_DIR}/${id}`,
+        `PATH=${shell_js_1.LAUNCH_PATH}`,
+        `if [ ! -f "$d/stdout" ] || [ ! -f "$d/stderr" ]; then rm -rf "$d" || :; echo "prized-output ${id} gone"; exit 0; fi`,
+        'if [ -e "$d/stdout.failed" ]; then x=1; else x=0; fi',
+        'if [ -e "$d/stderr.failed" ]; then y=1; else y=0; fi',
+        ...sizes,
+        // Cut by an earlier collect whose answer was lost: as long as a cut stream (the bound and a block).
+        `if [ -e "$d/stdout.cut" ]; then o=$((${exports.FULL_OUTPUT_BYTES} + 512)); fi`,
+        `if [ -e "$d/stderr.cut" ]; then e=$((${exports.FULL_OUTPUT_BYTES} + 512)); fi`,
+        ...failedLines(),
+        ...cut,
+    ].join('\n');
+}
+/**
+ * Remove a fullOutput command's directory (keyed by the SDK's own id, safe to
+ * send again), and any an earlier one left over an hour ago, when it got no
+ * answer to remove its own.
+ */
+function removeOutputScript(id) {
+    checkId(id);
+    return (`PATH=${shell_js_1.LAUNCH_PATH}; rm -rf ${exports.OUTPUT_DIR}/${id}; ` +
+        `find ${exports.OUTPUT_DIR} -mindepth 1 -maxdepth 1 -name 'exec_*' -mmin +${STALE_MIN} -exec rm -rf -- {} + 2> /dev/null || :`);
+}
+/** The marker (one without failure flags, as an earlier SDK's collect printed, has none), `gone`, or null for no marker. */
+function parseMarker(stdout, id) {
+    const m = new RegExp(`(?:^|\\n)prized-output ${id} (?:([0-9]+) ([0-9]+)(?: ([01]) ([01]))?|(gone))\\n$`).exec(stdout);
+    if (m === null)
+        return null;
+    if (m[5] === 'gone')
+        return 'gone';
+    return { out: Number(m[1]), err: Number(m[2]), outFailed: m[3] === '1', errFailed: m[4] === '1' };
+}
+/** Why the read-back output is cut, if it is: a failed write first, since it is the one the caller cannot foresee. */
+function markerTruncation(marker) {
+    if (marker.outFailed || marker.errFailed)
+        return 'write_failed';
+    if (marker.out > exports.FULL_OUTPUT_BYTES || marker.err > exports.FULL_OUTPUT_BYTES)
+        return 'output_limit';
+    return null;
+}
+/** A request the SDK sends on its own to collect or remove the files: best effort, within TEARDOWN_MS. */
+async function teardown(toolbox, script) {
+    try {
+        return await (0, toolbox_js_1.helperExec)(toolbox, script, { deadline: toolbox.config.now() + TEARDOWN_MS });
+    }
+    catch {
+        return null;
+    }
+}
+async function download(toolbox, path, signal) {
+    const result = await (0, http_js_1.request)(toolbox.config, {
+        method: 'GET',
+        url: `${toolbox.base()}/files/download?path=${encodeURIComponent(path)}`,
+        retry: 'safe',
+        read: 'bytes',
+        timeoutMs: READ_MS,
+        deadline: toolbox.config.now() + READ_MS,
+        signal,
+        sandboxId: toolbox.sandboxId,
+    });
+    // A leading BOM is the command's own output, as in the answer.
+    return new TextDecoder('utf-8', { ignoreBOM: true }).decode(result.bytes ?? new Uint8Array(0));
+}
+/** The files' contents in place of the answer's output. */
+async function readBack(toolbox, id, marker, result, signal) {
+    const dir = `${exports.OUTPUT_DIR}/${id}`;
+    // Both at once; one that fails stops the other, as the caller's abort stops both.
+    const both = new AbortController();
+    const stop = () => both.abort();
+    if (signal?.aborted)
+        stop();
+    signal?.addEventListener('abort', stop, { once: true });
+    const read = (name, size) => size > 0
+        ? download(toolbox, `${dir}/${name}`, both.signal).catch((error) => {
+            stop();
+            throw error;
+        })
+        : Promise.resolve('');
+    let stdout;
+    let stderr;
+    try {
+        [stdout, stderr] = await Promise.all([read('stdout', marker.out), read('stderr', marker.err)]);
+    }
+    finally {
+        signal?.removeEventListener('abort', stop);
+    }
+    const reason = markerTruncation(marker);
+    const { exitCode, durationMs, timedOut } = result;
+    const full = { stdout, stderr, exitCode, durationMs, timedOut, truncated: reason !== null };
+    if (reason !== null)
+        full.truncatedReason = reason;
+    return full;
+}
+/**
+ * A blocking exec that keeps the whole output (up to FULL_OUTPUT_BYTES of
+ * each stream). The result is a plain exec's, timeouts included: the caller
+ * (execCommand) turns a timed-out one into CommandTimeoutError.
+ */
+async function execFullOutput(toolbox, id, req, signal) {
+    const raw = {
+        command: exports.RUN_SCRIPT,
+        env: { ...req.env, [exports.SCRIPT_VAR]: captureScript(id), [exports.COMMAND_VAR]: req.command },
+        timeoutMs: req.timeoutMs,
+    };
+    if (req.cwd !== undefined)
+        raw.cwd = req.cwd;
+    let result;
+    try {
+        // A plain exec's retry rules: sent again only if it provably never arrived.
+        result = await (0, toolbox_js_1.rawExec)(toolbox, raw, { retry: 'exec', signal });
+    }
+    catch (error) {
+        // The caller has no way to read what it printed: its files go.
+        await teardown(toolbox, removeOutputScript(id));
+        throw error;
+    }
+    let marker = parseMarker(result.stdout, id);
+    if (marker === null && (result.timedOut || result.exitCode === -1)) {
+        // Its time limit (or a signal) ended the script with the command, before
+        // it printed anything back: what the command printed is in its files.
+        const collected = await teardown(toolbox, collectScript(id));
+        marker = collected === null ? null : parseMarker(collected.stdout, id);
+        if (marker === null)
+            return result; // no answer: nothing more to be done
+    }
+    // No marker: the output came back in the answer (or the command ran as a
+    // plain exec), and the directory is already gone.
+    if (marker === null || marker === 'gone')
+        return result;
+    let full;
+    try {
+        full = await readBack(toolbox, id, marker, result, signal);
+    }
+    catch (error) {
+        const aborted = !(error instanceof errors_js_1.PrizedError) || error.code === 'aborted';
+        if (aborted || result.timedOut) {
+            // Leaving, or the timeout is the caller's error: the files go.
+            await teardown(toolbox, removeOutputScript(id));
+            if (aborted)
+                throw error;
+            return result;
+        }
+        if (error.code === 'sandbox_deleted') {
+            // Nothing is kept: the output went with the sandbox, as its code says for any call on it.
+            // The command ran: its exit code goes on the error too, so a caller
+            // that replaces the sandbox can tell not to run it again.
+            throw (0, outcome_js_1.restate)(error, `The command ran (exit ${result.exitCode}), but the sandbox was deleted before its output could be read back.`, {
+                cause: error,
+                exitCode: result.exitCode,
+            });
+        }
+        const dir = `${exports.OUTPUT_DIR}/${id}`;
+        throw new errors_js_1.OutputReadError(`The command ran (exit ${result.exitCode}), but its output could not be read back (${error.message.replace(/[.\s]+$/, '')}). ` +
+            `It is kept in ${dir}/stdout and ${dir}/stderr for an hour: read them with files.read(), then remove ${dir}.`, { cause: error, exitCode: result.exitCode, stdoutPath: `${dir}/stdout`, stderrPath: `${dir}/stderr` });
+    }
+    await teardown(toolbox, removeOutputScript(id));
+    return full;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/sandbox.d.ts

@@ -0,0 +1,218 @@
+import { CommandHandle, type ExecOptions } from './commands.js';
+import { Files } from './files.js';
+import { type ClientOptions } from './http.js';
+import { type ExecResult, type Resources, type ResourcesInput, type SandboxInfo, type SandboxState, type Template } from './types.js';
+/** The header a request to a sandbox port's URL carries the API key in. */
+export declare const PREVIEW_KEY_HEADER = "Prized-Key";
+/** The template a create uses when it names none. */
+export declare const DEFAULT_TEMPLATE = "prized-base-v1";
+/** How long create, resume and fork wait for `running` by default. */
+export declare const DEFAULT_START_TIMEOUT_MS = 180000;
+/** How long pause and delete wait by default. */
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 120000;
+/** Cleanups still running after the call that started them has answered.
+ *  Not exported from the package; the tests await it. */
+export declare const backgroundCleanups: Set<Promise<void>>;
+/** Edge warm-ups (warmEdge) not yet settled. Not exported from the package;
+ *  the tests await it. */
+export declare const backgroundWarmups: Set<Promise<void>>;
+export interface CreateOptions extends ClientOptions {
+    /** Template id. Default `prized-base-v1`; `Sandbox.templates()` lists them. */
+    template?: string;
+    /** vCPU, memory and disk. Anything left out takes the template's default. */
+    resources?: ResourcesInput;
+    /** Environment variables for every command in the sandbox. */
+    envVars?: Record<string, string>;
+    /** Your own key/value tags (up to 32), filterable in `Sandbox.list`. */
+    labels?: Record<string, string>;
+    /**
+     * Run time in minutes; the sandbox is deleted when it ends. Paid plans:
+     * 1 440 (24 hours) by default, up to 7 days (10 080; a custom plan has no
+     * maximum), and every resume restarts the clock. The free tier: 60
+     * minutes of running at most (paused time does not count). Change it later
+     * with `prized sandbox extend` or the API's `extend` and `timeout` routes.
+     */
+    maxRuntimeMin?: number;
+    /** Pause after this many idle minutes (0: never). */
+    autoPauseMin?: number;
+    /** Delete this many minutes after pausing (0: never). */
+    autoDeleteMin?: number;
+    /**
+     * How long the create may take, in ms: the request, its retries and
+     * (unless `wait: false`) the wait for `running`. Default 180 000.
+     * Deleting a sandbox that failed (up to 5 s) comes on top.
+     */
+    timeoutMs?: number;
+    /**
+     * Makes a retried create return the same sandbox instead of a second one.
+     * The SDK sends a fresh key per call when you give none, so its own
+     * retries are always safe.
+     */
+    idempotencyKey?: string;
+    /** Resolve as soon as the API accepts the create, without waiting for `running`. */
+    wait?: boolean;
+    signal?: AbortSignal;
+}
+export interface ListOptions extends ClientOptions {
+    /** Only sandboxes carrying every one of these labels. */
+    labels?: Record<string, string>;
+    /** Only sandboxes in this state (or any of these states). */
+    state?: SandboxState | SandboxState[];
+}
+export interface WaitableOptions {
+    /** Wait for the change to land. Default true (false for delete). */
+    wait?: boolean;
+    /**
+     * How long the call may take, in ms: the request, its retries and
+     * (unless `wait: false`) the wait. Default 180 000 for resume and fork,
+     * 120 000 for pause and delete. Deleting a fork's copies that failed
+     * comes on top.
+     */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ForkOptions extends WaitableOptions {
+    /** How many copies. Default 1. */
+    count?: number;
+    /** Labels for the copies, in place of the parent's. Default: the parent's labels. */
+    labels?: Record<string, string>;
+    /**
+     * Each copy's lifetime in minutes, up to the workspace's maximum. Default:
+     * on a paid workspace, the parent's runtime, starting at the fork; on the
+     * free tier, copies keep the parent's deletion time (this may only shorten it).
+     */
+    maxRuntimeMin?: number;
+    /** Makes a retried fork return the same copies. The SDK sends one per call when you give none. */
+    idempotencyKey?: string;
+}
+/**
+ * A Prized sandbox: a microVM your code creates, runs commands in, and
+ * pauses, resumes, forks and deletes.
+ *
+ *     const sandbox = await Sandbox.create({ template: 'prized-base-v1' });
+ *     const { stdout } = await sandbox.exec('python3 --version');
+ *     await sandbox.delete();
+ */
+export declare class Sandbox {
+    /** The sandbox id (`sbx_…`). */
+    readonly id: string;
+    /** Read, write, list, remove, upload and download files. */
+    readonly files: Files;
+    private readonly config;
+    private current;
+    private readonly toolbox;
+    private constructor();
+    /** Everything the API said about this sandbox, as of the last call. */
+    get info(): SandboxInfo;
+    /** The state as of the last call; `refresh()` reads it fresh. */
+    get state(): SandboxState;
+    get template(): string | null;
+    get resources(): Resources;
+    get labels(): Record<string, string>;
+    get createdAt(): Date | null;
+    get expiresAt(): Date | null;
+    get errorReason(): string | null;
+    toJSON(): Omit<SandboxInfo, 'raw'>;
+    /**
+     * Create a sandbox and wait until it is running, ready for commands.
+     * If it fails or the wait runs out, the sandbox is deleted and the error
+     * thrown. Throws PrizedError: `paid_balance_required`, `insufficient_balance`,
+     * `sandbox_quota_exceeded` (see `reason`), `template_not_found`,
+     * `invalid_resources`, `sandbox_error`, `timeout`, …
+     */
+    static create(options?: CreateOptions): Promise<Sandbox>;
+    /** An existing sandbox by id, in whatever state it is in. */
+    static connect(id: string, options?: ClientOptions): Promise<Sandbox>;
+    /** The workspace's sandboxes (deleted ones excluded), newest first; `labels` is filtered by the API. */
+    static list(options?: ListOptions): Promise<Sandbox[]>;
+    /**
+     * Delete every sandbox carrying all of `labels` (at least one) and resolve
+     * with their ids (the API takes up to 250 a request; this repeats it until
+     * none are left). Safe to repeat: sandboxes already being
+     * deleted are in the answer again, and none matching resolves `[]`. Each
+     * counts toward the workspace's quotas until it is gone;
+     * `Sandbox.list({ labels })` coming back empty means they all are.
+     */
+    static deleteByLabels(labels: Record<string, string>, options?: ClientOptions): Promise<string[]>;
+    /** The templates you can create sandboxes from, with their default, minimum and maximum shapes. */
+    static templates(options?: ClientOptions): Promise<Template[]>;
+    /**
+     * Run a command (a shell string, or an argv array the SDK quotes) and
+     * return its output. A non-zero exit is not an error: read `exitCode`.
+     * With `background: true` it returns a CommandHandle at once.
+     */
+    exec(command: string | readonly string[], options: ExecOptions & {
+        background: true;
+    }): Promise<CommandHandle>;
+    exec(command: string | readonly string[], options?: ExecOptions & {
+        background?: false;
+    }): Promise<ExecResult>;
+    exec(command: string | readonly string[], options?: ExecOptions): Promise<ExecResult | CommandHandle>;
+    /** Read the sandbox again: `state` and the other fields update. Does not count as activity. */
+    refresh(): Promise<this>;
+    /**
+     * Count as activity now: the `autoPauseMin` idle clock starts over.
+     * Commands and file transfers already count; this is for idle stretches.
+     */
+    keepAlive(): Promise<void>;
+    /**
+     * Pause: memory and disk are kept, and only storage is billed. Waits for
+     * `paused` unless `wait: false`.
+     */
+    pause(options?: WaitableOptions): Promise<void>;
+    /** Resume a paused sandbox, with every process where it left off. Waits for `running` unless `wait: false`. */
+    resume(options?: WaitableOptions): Promise<void>;
+    /**
+     * Fork a running or paused sandbox into `count` new sandboxes, each with
+     * every process of this one running. Resolves once every copy is running,
+     * ready for commands (unless `wait: false`); if any copy fails or the
+     * wait runs out, every copy is deleted and the error thrown. The parent is
+     * left as it was: running, or paused. `timeoutMs` bounds the request and
+     * the wait together.
+     */
+    fork(options?: ForkOptions): Promise<Sandbox[]>;
+    /**
+     * Delete the sandbox and everything in it. Returns once the API accepts;
+     * `wait: true` also waits until it is gone (a deleting sandbox still
+     * counts toward the workspace's quota). `timeoutMs` (default 120 000)
+     * bounds the whole call, its retries and the wait included.
+     */
+    delete(options?: WaitableOptions): Promise<void>;
+    /**
+     * The https URL `port` of the sandbox answers at, for a request that
+     * carries a workspace-wide API key with Sandboxes: Write in the
+     * `Prized-Key` header (`previewHeaders()`): a web app, an API or a dev
+     * server listening on that port in the sandbox on 127.0.0.1 or 0.0.0.0. A
+     * request to a paused sandbox resumes it and waits up to 10 seconds, as
+     * `exec` does. Nothing is created: the URL is the sandbox's own. Throws
+     * `preview_unavailable` when the deployment has sandbox ingress off.
+     */
+    previewUrl(port: number): string;
+    /** The headers a request to `previewUrl(port)` sends: this client's API key in
+     *  `Prized-Key`. The header never reaches the app. Send them with
+     *  `redirect: 'manual'`: fetch resends custom headers to whatever host a
+     *  redirect names, so only ever send them to the sandbox's preview URL. */
+    previewHeaders(): Record<string, string>;
+    /** POST the verb, the call and its retries within `deadline`; with `hold`,
+     *  held by the API until the sandbox is that (each attempt asks only for
+     *  what is left). */
+    private verb;
+    /**
+     * Poll until the sandbox reaches `want`; throws on error/deleted or the
+     * deadline. The first read goes out at once (a held answer that has not
+     * settled is usually a breath away), then 100 ms, doubling to
+     * pollIntervalMs, and the last just before the deadline (Polls).
+     * `reportedMs` is the caller's whole budget, for the error.
+     */
+    private waitFor;
+    /** Best-effort delete after a failed wait, bounded (as the Python SDK's); never throws. */
+    private discard;
+    /**
+     * Poll the list until every fork copy is running or has failed, by
+     * `deadline`: one list call per poll, however many copies, every
+     * pollIntervalMs, and the last just before the deadline (Polls),
+     * so even a budget shorter than one interval polls once. `reportedMs` is
+     * the caller's whole budget, for the error.
+     */
+    private static settle;
+}