@prized/sdk 0.0.0-stage → 0.1.0

package/dist/esm/sandbox.js

@@ -0,0 +1,806 @@
+// The Sandbox class: create, connect, list, templates, and the lifecycle
+// verbs (pause, resume, fork, delete, refresh) over the REST API.
+import { execCommand } from './commands.js';
+import { PrizedError } from './errors.js';
+import { Files } from './files.js';
+import { callDeadline, cutByDeadline, MAX_RETRY_AFTER_MS, Polls, request, resolveConfig, toolboxBaseFor, warmEdge, } from './http.js';
+import { parseSandbox, parseTemplate, resourcesToWire, } from './types.js';
+/** The header a request to a sandbox port's URL carries the API key in. */
+export const PREVIEW_KEY_HEADER = 'Prized-Key';
+/** The template a create uses when it names none. */
+export const DEFAULT_TEMPLATE = 'prized-base-v1';
+/** How long create, resume and fork wait for `running` by default. */
+export const DEFAULT_START_TIMEOUT_MS = 180_000;
+/** How long pause and delete wait by default. */
+export const DEFAULT_SETTLE_TIMEOUT_MS = 120_000;
+/** Fork copies a failed or lost fork deletes at once. */
+const DELETE_CONCURRENCY = 8;
+/**
+ * The longest the API holds a create, pause or resume for `?wait=` (its
+ * SANDBOX_WAIT_MAX_MS). An API that predates `wait` ignores it and answers
+ * at once, and the SDK polls as before.
+ */
+const SERVER_HOLD_MAX_MS = 8_000;
+/** Room a held request leaves inside requestTimeoutMs for the round trip. */
+const HOLD_MARGIN_MS = 5_000;
+/** Room it leaves inside the caller's own budget for the answer to arrive. */
+const HOLD_ANSWER_MS = 1_000;
+/** The first poll after an answer that has not settled waits this long, doubling up to pollIntervalMs. */
+const FIRST_POLL_MS = 100;
+/** The bound on deleting the sandbox a create with no usable answer made (replay + delete). */
+const RECLAIM_MS = 10_000;
+/** What a fork's cleanup adds to RECLAIM_MS per copy, so a large fork's copies are all reached. */
+const RECLAIM_PER_COPY_MS = 500;
+/** The most one DELETE of a cleanup may take, so a stalled one leaves time for the rest. */
+const RECLAIM_DELETE_MS = 5_000;
+/** The 5xx answers the API gives before it creates anything. */
+const REFUSED_BEFORE_CREATE = new Set(['sandboxes_disabled', 'sandbox_create_disabled', 'sandbox_fork_disabled', 'sandbox_capacity']);
+/** Cleanups still running after the call that started them has answered.
+ *  Not exported from the package; the tests await it. */
+export const backgroundCleanups = new Set();
+/** Edge warm-ups (warmEdge) not yet settled. Not exported from the package;
+ *  the tests await it. */
+export const backgroundWarmups = new Set();
+function randomKey() {
+    const webcrypto = globalThis.crypto;
+    if (webcrypto?.randomUUID)
+        return `prized-sdk-${webcrypto.randomUUID()}`;
+    const bytes = new Uint8Array(16);
+    if (webcrypto?.getRandomValues)
+        webcrypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i += 1)
+            bytes[i] = Math.floor(Math.random() * 256);
+    return `prized-sdk-${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/** A deep copy of a request body, as it goes on the wire. */
+function snapshot(body) {
+    return JSON.parse(JSON.stringify(body));
+}
+/** A call's timeoutMs: the default when not given, else a number of ms > 0. */
+function budgetMs(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!(Number.isFinite(value) && value > 0))
+        throw new PrizedError('invalid_argument', 'timeoutMs must be a number of ms > 0');
+    return value;
+}
+function wholeMinutes(name, value, allowZero) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 0 || (!allowZero && value === 0)) {
+        throw new PrizedError('invalid_argument', `${name} must be a whole number of minutes${allowZero ? ' ≥ 0' : ' > 0'}`);
+    }
+    return value;
+}
+function apiUrl(config, path) {
+    return `${config.baseUrl}/api/v1${path}`;
+}
+/**
+ * The `?wait=` query asking the API to answer once the sandbox is `want`:
+ * held no longer than the caller has left (`leftMs`, less room for the
+ * answer), the API's bound, or what the request timeout leaves room for.
+ * Empty when there is no time to hold. Built per attempt (RequestSpec.url),
+ * so a retry after a lost answer asks only for what is left.
+ */
+function holdQuery(config, want, leftMs) {
+    const ms = Math.floor(Math.min(SERVER_HOLD_MAX_MS, leftMs - HOLD_ANSWER_MS, config.requestTimeoutMs - HOLD_MARGIN_MS));
+    return ms > 0 ? `?wait=${want}&waitTimeoutMs=${ms}` : '';
+}
+/** The most labels one selector may name (create's own limit). */
+const MAX_SELECTOR_LABELS = 32;
+/** How many times deleteByLabels asks again while the API says `more` (it deletes up to 250 a request). */
+const MAX_BULK_DELETE_CALLS = 100;
+/** A UTF-16 half with no partner: URLSearchParams would send it as U+FFFD, another label. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/** Can the API be asked for this pair? It reads a key up to its first `=` and refuses a pair no sandbox could carry. */
+function selectable(key, value) {
+    return (typeof value === 'string' &&
+        key !== '' &&
+        !key.includes('=') &&
+        !(key + value).includes('\0') &&
+        key.length <= 64 &&
+        value.length <= 256 &&
+        !LONE_SURROGATE.test(key + value));
+}
+/**
+ * `?label=key=value&…` for a label selector, in key order ('' for none). A
+ * pair the API cannot be asked for, or more than 32: `strict` (a delete)
+ * refuses it, and a list leaves it to its own filter, as it always filtered.
+ */
+function labelQuery(labels, strict) {
+    const pairs = [];
+    for (const key of Object.keys(labels ?? {}).sort()) {
+        const value = labels[key];
+        if (selectable(key, value))
+            pairs.push(['label', `${key}=${value}`]);
+        else if (strict) {
+            throw new PrizedError('invalid_argument', `Cannot select on label ${JSON.stringify(key)}: a key is 1 to 64 characters without '=', a value a string of up to 256.`);
+        }
+    }
+    if (pairs.length > MAX_SELECTOR_LABELS) {
+        if (strict)
+            throw new PrizedError('invalid_argument', `At most ${MAX_SELECTOR_LABELS} labels can be selected on.`);
+        return '';
+    }
+    return pairs.length > 0 ? `?${new URLSearchParams(pairs).toString()}` : '';
+}
+function sandboxPathFor(id) {
+    return `/sandboxes/${encodeURIComponent(id)}`;
+}
+/**
+ * Whether one failed attempt at a create or fork may have made sandboxes
+ * anyway: no answer came (it timed out, the connection was lost, it was
+ * cancelled mid-request), the answer was a 5xx other than the API's
+ * refusals made before it creates anything (a gateway's, or the API failing
+ * after it committed), or a 2xx the SDK could not read. Every other answer
+ * is the API's (or a proxy's) refusal, after which that attempt made nothing.
+ */
+function outcomeUnknown(error) {
+    if (error.status === null)
+        return error.code === 'timeout' || error.code === 'network_error' || error.code === 'aborted';
+    if (error.status >= 500)
+        return !REFUSED_BEFORE_CREATE.has(error.code);
+    return error.status >= 200 && error.status < 300;
+}
+/**
+ * Every attempt of a keyed create or fork, judged together. Its retries
+ * carry the same key, but one refused before the API looks the key up (a
+ * rate limit, a switched-off create) says nothing about an earlier attempt
+ * that got no answer: the call's outcome is unknown if any attempt's was,
+ * whatever the last one answered.
+ */
+class Attempts {
+    failures = [];
+    /** A 2xx came back (its body may still have been unusable). */
+    accepted = false;
+    onAttemptFailed = (error) => {
+        this.failures.push(error);
+    };
+    /** Whether sandboxes may exist that the caller has no handle to. */
+    get unresolved() {
+        return this.accepted || this.failures.some(outcomeUnknown);
+    }
+    /** The wait the last refusal asked for (Retry-After), in ms, within the SDK's cap. */
+    get retryAfterMs() {
+        const seconds = this.failures[this.failures.length - 1]?.retryAfter ?? null;
+        return seconds === null ? 0 : Math.min(MAX_RETRY_AFTER_MS, Math.ceil(seconds * 1000));
+    }
+}
+/**
+ * Find what a create or fork with no usable answer made, by sending its key
+ * again (`replay`, without a hold: the API answers at once with what the
+ * key made, or makes it now if no attempt ever arrived), and delete it. In
+ * the background, so the caller's rejection never waits on it, and bounded:
+ * the wait the last refusal asked for (a replay sent sooner would be
+ * refused again), then RECLAIM_MS, plus RECLAIM_PER_COPY_MS a copy. Only
+ * under the SDK's own key, which no other call holds. The sandboxes' own
+ * timers (maxRuntimeMin) are the backstop.
+ */
+function reclaim(config, attempts, copies, replay) {
+    const cleanup = (async () => {
+        const waitMs = attempts.retryAfterMs;
+        if (waitMs > 0)
+            await config.sleep(waitMs);
+        const deadline = config.now() + RECLAIM_MS + RECLAIM_PER_COPY_MS * Math.max(0, copies - 1);
+        const ids = await replay(deadline);
+        // DELETE_CONCURRENCY deletes at a time, each taking at most its share of
+        // what is left for the rounds still to go (and RECLAIM_DELETE_MS), so a
+        // stalled one never leaves later copies without an attempt.
+        let next = 0;
+        const worker = async () => {
+            while (next < ids.length) {
+                const i = next;
+                next += 1;
+                const id = ids[i];
+                const rounds = Math.ceil((ids.length - i) / DELETE_CONCURRENCY);
+                const share = Math.min(RECLAIM_DELETE_MS, (deadline - config.now()) / rounds);
+                await request(config, {
+                    method: 'DELETE',
+                    url: apiUrl(config, sandboxPathFor(id)),
+                    retry: 'safe',
+                    deadline: Math.min(deadline, config.now() + share),
+                    sandboxId: id,
+                }).catch(() => undefined);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(DELETE_CONCURRENCY, ids.length) }, worker));
+    })()
+        .catch(() => {
+        // The sandboxes' own timers (maxRuntimeMin) are the backstop.
+    })
+        .finally(() => backgroundCleanups.delete(cleanup));
+    backgroundCleanups.add(cleanup);
+}
+/** The error a failed or deleted sandbox answers a wait with; null while it can still arrive. */
+function failedState(info) {
+    if (info.state === 'error') {
+        return new PrizedError('sandbox_error', info.errorReason ? `The sandbox failed: ${info.errorReason}` : null, {
+            sandboxId: info.id,
+            reason: info.errorReason,
+        });
+    }
+    if (info.state === 'deleting' || info.state === 'deleted') {
+        return new PrizedError('sandbox_deleted', null, { sandboxId: info.id });
+    }
+    return null;
+}
+/**
+ * A wait's timeout. One ended by a read its deadline cut short (the retry it
+ * was due would have ended past it: a 503's Retry-After, say) may come
+ * before the whole budget has passed, so it says so, and what the last
+ * attempt met; `cause` is the read's own error.
+ */
+function waitTimeout(what, budgetMs, sandboxId, read) {
+    const last = read?.cause instanceof PrizedError ? read.cause : null;
+    if (last === null)
+        return new PrizedError('timeout', `${what} after ${budgetMs} ms`, { sandboxId, cause: read });
+    const met = last.status === null ? last.code : `${last.status} ${last.code}`;
+    return new PrizedError('timeout', `${what}: a read could not get an answer within the ${budgetMs} ms allowed (the last failed with ${met}).`, {
+        sandboxId,
+        cause: read,
+    });
+}
+/**
+ * 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 class Sandbox {
+    /** The sandbox id (`sbx_…`). */
+    id;
+    /** Read, write, list, remove, upload and download files. */
+    files;
+    config;
+    current;
+    toolbox;
+    constructor(config, info) {
+        this.config = config;
+        this.id = info.id;
+        this.current = info;
+        this.toolbox = {
+            config,
+            sandboxId: info.id,
+            base: () => toolboxBaseFor(config, this.id, this.current.toolboxBase),
+        };
+        this.files = new Files(this.toolbox);
+    }
+    // --- what the SDK last heard ---------------------------------------------
+    /** Everything the API said about this sandbox, as of the last call. */
+    get info() {
+        return this.current;
+    }
+    /** The state as of the last call; `refresh()` reads it fresh. */
+    get state() {
+        return this.current.state;
+    }
+    get template() {
+        return this.current.template;
+    }
+    get resources() {
+        return this.current.resources;
+    }
+    get labels() {
+        return this.current.labels;
+    }
+    get createdAt() {
+        return this.current.createdAt;
+    }
+    get expiresAt() {
+        return this.current.expiresAt;
+    }
+    get errorReason() {
+        return this.current.errorReason;
+    }
+    toJSON() {
+        const { raw: _raw, ...rest } = this.current;
+        return rest;
+    }
+    // --- entry points ----------------------------------------------------------
+    /**
+     * 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 async create(options = {}) {
+        const config = resolveConfig(options);
+        const body = { template: options.template ?? DEFAULT_TEMPLATE };
+        if (options.resources !== undefined)
+            body.resources = resourcesToWire(options.resources);
+        if (options.envVars !== undefined)
+            body.envVars = options.envVars;
+        if (options.labels !== undefined)
+            body.labels = options.labels;
+        const maxRuntimeMin = wholeMinutes('maxRuntimeMin', options.maxRuntimeMin, false);
+        if (maxRuntimeMin !== undefined)
+            body.maxRuntimeMin = maxRuntimeMin;
+        const autoPauseMin = wholeMinutes('autoPauseMin', options.autoPauseMin, true);
+        if (autoPauseMin !== undefined)
+            body.autoPauseMin = autoPauseMin;
+        const autoDeleteMin = wholeMinutes('autoDeleteMin', options.autoDeleteMin, true);
+        if (autoDeleteMin !== undefined)
+            body.autoDeleteMin = autoDeleteMin;
+        const timeoutMs = budgetMs(options.timeoutMs, DEFAULT_START_TIMEOUT_MS);
+        const started = config.now();
+        const idempotencyKey = options.idempotencyKey ?? randomKey();
+        const held = options.wait !== false;
+        // Every attempt and the cleanup's replay send this copy, so a caller
+        // that changes its labels or envVars meanwhile cannot make the replay
+        // a different request (idempotency_conflict) that finds nothing.
+        const wire = snapshot(body);
+        const send = (hold, signal, deadline, attempts) => request(config, {
+            method: 'POST',
+            url: (leftMs) => apiUrl(config, `/sandboxes${hold ? holdQuery(config, 'running', leftMs) : ''}`),
+            json: wire,
+            headers: { 'idempotency-key': idempotencyKey },
+            // Keyed, so a resend returns the first sandbox rather than a second.
+            retry: 'safe',
+            signal,
+            deadline,
+            onAttemptFailed: attempts?.onAttemptFailed,
+        });
+        // The caller's first command goes to the edge: open that connection
+        // while the API holds the create, not after the sandbox runs.
+        // A signal aborted before the call sends nothing: nothing to warm.
+        if (held && options.signal?.aborted !== true) {
+            const warm = warmEdge(config).finally(() => backgroundWarmups.delete(warm));
+            backgroundWarmups.add(warm);
+        }
+        const attempts = new Attempts();
+        let sandbox;
+        try {
+            // Held by the API until running (or its bound), instead of polled;
+            // with its retries, within the caller's own timeoutMs (wait: false too).
+            const result = await send(held, options.signal, started + timeoutMs, attempts);
+            attempts.accepted = true;
+            sandbox = new Sandbox(config, parseSandbox(result.json?.sandbox));
+        }
+        catch (error) {
+            // Cancelled mid-request, no answer at all (timed out or the connection
+            // lost), most likely during the API's hold (it commits the sandbox,
+            // then holds), or a 2xx with no usable sandbox in it: on any attempt,
+            // even when a later one was refused. One may be billing that the
+            // caller has no handle to. Under the SDK's own key it can only be this
+            // call's: replay the key and delete what it answers with. Under the
+            // caller's key it may be an earlier call's: left, and resending the
+            // key returns it.
+            if (attempts.unresolved && options.idempotencyKey === undefined) {
+                reclaim(config, attempts, 1, async (deadline) => {
+                    const replay = await send(false, undefined, deadline);
+                    return [parseSandbox(replay.json?.sandbox).id];
+                });
+            }
+            throw error;
+        }
+        if (options.wait === false)
+            return sandbox;
+        try {
+            await sandbox.waitFor('running', timeoutMs - (config.now() - started), options.signal, timeoutMs);
+        }
+        catch (error) {
+            // The caller gets no handle to a sandbox that failed or never came up,
+            // so it is deleted rather than left running (and billing).
+            await sandbox.discard();
+            throw error;
+        }
+        return sandbox;
+    }
+    /** An existing sandbox by id, in whatever state it is in. */
+    static async connect(id, options = {}) {
+        if (typeof id !== 'string' || id === '')
+            throw new PrizedError('invalid_argument', 'A sandbox id is required.');
+        const config = resolveConfig(options);
+        return new Sandbox(config, await fetchInfo(config, id, undefined, callDeadline(config)));
+    }
+    /** The workspace's sandboxes (deleted ones excluded), newest first; `labels` is filtered by the API. */
+    static async list(options = {}) {
+        const config = resolveConfig(options);
+        const infos = await listInfos(config, undefined, callDeadline(config), labelQuery(options.labels, false));
+        const states = options.state === undefined ? null : new Set(Array.isArray(options.state) ? options.state : [options.state]);
+        const labels = Object.entries(options.labels ?? {});
+        return infos
+            .filter((info) => states === null || states.has(info.state))
+            .filter((info) => labels.every(([key, value]) => info.labels[key] === value))
+            .map((info) => new Sandbox(config, info));
+    }
+    /**
+     * 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 async deleteByLabels(labels, options = {}) {
+        if (labels === null || typeof labels !== 'object' || Object.keys(labels).length === 0) {
+            throw new PrizedError('invalid_argument', 'deleteByLabels needs at least one label.');
+        }
+        const query = labelQuery(labels, true);
+        const config = resolveConfig(options);
+        const deadline = callDeadline(config);
+        const deleted = new Set();
+        const stuck = (calls) => new PrizedError('delete_incomplete', `Deleted ${deleted.size} sandboxes in ${calls} requests and some are left; call again to delete the rest.`);
+        for (let call = 1; call <= MAX_BULK_DELETE_CALLS; call += 1) {
+            const result = await request(config, { method: 'DELETE', url: apiUrl(config, `/sandboxes${query}`), retry: 'safe', deadline });
+            const answer = result.json;
+            const ids = answer?.ids;
+            if (!Array.isArray(ids) || !ids.every((id) => typeof id === 'string')) {
+                throw new PrizedError('bad_response', "The API answered without the deleted sandboxes' ids.");
+            }
+            const before = deleted.size;
+            for (const id of ids)
+                deleted.add(id);
+            if (answer?.more !== true)
+                return [...deleted];
+            if (deleted.size === before)
+                throw stuck(call);
+        }
+        throw stuck(MAX_BULK_DELETE_CALLS);
+    }
+    /** The templates you can create sandboxes from, with their default, minimum and maximum shapes. */
+    static async templates(options = {}) {
+        const config = resolveConfig(options);
+        const result = await request(config, {
+            method: 'GET',
+            url: apiUrl(config, '/sandbox-templates'),
+            retry: 'safe',
+            deadline: callDeadline(config),
+        });
+        const list = result.json?.templates;
+        if (!Array.isArray(list))
+            throw new PrizedError('bad_response', 'The API answered without a template list.');
+        return list.map(parseTemplate).filter((t) => t !== null);
+    }
+    exec(command, options = {}) {
+        return execCommand(this.toolbox, command, options);
+    }
+    // --- lifecycle ----------------------------------------------------------------
+    /** Read the sandbox again: `state` and the other fields update. Does not count as activity. */
+    async refresh() {
+        this.current = await fetchInfo(this.config, this.id, undefined, callDeadline(this.config));
+        return this;
+    }
+    /**
+     * Count as activity now: the `autoPauseMin` idle clock starts over.
+     * Commands and file transfers already count; this is for idle stretches.
+     */
+    async keepAlive() {
+        await request(this.config, {
+            method: 'POST',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/refresh`),
+            retry: 'safe',
+            deadline: callDeadline(this.config),
+            read: 'none',
+            sandboxId: this.id,
+        });
+    }
+    /**
+     * Pause: memory and disk are kept, and only storage is billed. Waits for
+     * `paused` unless `wait: false`.
+     */
+    async pause(options = {}) {
+        const timeoutMs = budgetMs(options.timeoutMs, DEFAULT_SETTLE_TIMEOUT_MS);
+        const deadline = this.config.now() + timeoutMs;
+        await this.verb('pause', options.signal, deadline, options.wait === false ? null : 'paused');
+        if (options.wait === false)
+            return;
+        await this.waitFor('paused', deadline - this.config.now(), options.signal, timeoutMs);
+    }
+    /** Resume a paused sandbox, with every process where it left off. Waits for `running` unless `wait: false`. */
+    async resume(options = {}) {
+        const timeoutMs = budgetMs(options.timeoutMs, DEFAULT_START_TIMEOUT_MS);
+        const deadline = this.config.now() + timeoutMs;
+        await this.verb('resume', options.signal, deadline, options.wait === false ? null : 'running');
+        if (options.wait === false)
+            return;
+        await this.waitFor('running', deadline - this.config.now(), options.signal, timeoutMs);
+    }
+    /**
+     * 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.
+     */
+    async fork(options = {}) {
+        const count = options.count ?? 1;
+        if (!Number.isInteger(count) || count < 1)
+            throw new PrizedError('invalid_argument', 'count must be a whole number ≥ 1');
+        const timeoutMs = budgetMs(options.timeoutMs, DEFAULT_START_TIMEOUT_MS);
+        // One deadline for the POST, its retries and the wait for the copies.
+        const deadline = this.config.now() + timeoutMs;
+        const body = { count };
+        if (options.labels !== undefined)
+            body.labels = options.labels;
+        const maxRuntimeMin = wholeMinutes('maxRuntimeMin', options.maxRuntimeMin, false);
+        if (maxRuntimeMin !== undefined)
+            body.maxRuntimeMin = maxRuntimeMin;
+        const idempotencyKey = options.idempotencyKey ?? randomKey();
+        const wire = snapshot(body); // as in create
+        const send = (deadline, attempts) => request(this.config, {
+            method: 'POST',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/fork`),
+            json: wire,
+            headers: { 'idempotency-key': idempotencyKey },
+            retry: 'safe',
+            signal: attempts === undefined ? undefined : options.signal,
+            deadline,
+            sandboxId: this.id,
+            onAttemptFailed: attempts?.onAttemptFailed,
+        });
+        const copies = (result) => {
+            const docs = result.json?.sandboxes;
+            if (!Array.isArray(docs))
+                throw new PrizedError('bad_response', 'The fork answer carried no sandboxes.', { sandboxId: this.id });
+            return docs.map((doc) => new Sandbox(this.config, parseSandbox(doc)));
+        };
+        const attempts = new Attempts();
+        let children;
+        try {
+            const result = await send(deadline, attempts);
+            attempts.accepted = true;
+            children = copies(result);
+        }
+        catch (error) {
+            // As for create: copies may exist with no handle to them. The API
+            // answers a replayed fork key before it checks the parent, so they are
+            // found even if the parent stopped meanwhile.
+            if (attempts.unresolved && options.idempotencyKey === undefined) {
+                reclaim(this.config, attempts, count, async (deadline) => copies(await send(deadline)).map((copy) => copy.id));
+            }
+            throw error;
+        }
+        if (options.wait === false || children.length === 0)
+            return children;
+        try {
+            await Sandbox.settle(this.config, children, deadline, timeoutMs, options.signal, this.id);
+            const failed = children.find((child) => child.state !== 'running');
+            if (failed)
+                throw failedState(failed.current) ?? new PrizedError('sandbox_error', null, { sandboxId: failed.id });
+        }
+        catch (error) {
+            // All or nothing: copies the caller will never get are not left billing.
+            for (let i = 0; i < children.length; i += DELETE_CONCURRENCY) {
+                await Promise.all(children.slice(i, i + DELETE_CONCURRENCY).map((child) => child.discard()));
+            }
+            throw error;
+        }
+        return children;
+    }
+    /**
+     * 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.
+     */
+    async delete(options = {}) {
+        const timeoutMs = budgetMs(options.timeoutMs, DEFAULT_SETTLE_TIMEOUT_MS);
+        // One deadline for the whole call: the DELETE, its retries and the wait.
+        const deadline = this.config.now() + timeoutMs;
+        const result = await requestOr404(this.config, {
+            method: 'DELETE',
+            url: apiUrl(this.config, sandboxPathFor(this.id)),
+            retry: 'safe',
+            signal: options.signal,
+            deadline,
+            sandboxId: this.id,
+        });
+        if (result === null) {
+            this.current = { ...this.current, state: 'deleted' };
+            return;
+        }
+        const doc = result.json?.sandbox;
+        if (doc !== undefined)
+            this.current = parseSandbox(doc);
+        if (options.wait !== true)
+            return;
+        const timedOut = (read) => waitTimeout(`${this.id} was still ${this.current.state}`, timeoutMs, this.id, read);
+        const polls = new Polls(this.config, deadline);
+        for (;;) {
+            let fresh;
+            polls.sent();
+            try {
+                // As in waitFor: the deadline bounds each read and its retries.
+                fresh = await requestOr404(this.config, {
+                    method: 'GET',
+                    url: apiUrl(this.config, sandboxPathFor(this.id)),
+                    retry: 'safe',
+                    signal: options.signal,
+                    deadline,
+                    sandboxId: this.id,
+                });
+            }
+            catch (error) {
+                throw cutByDeadline(error) ? timedOut(error) : error;
+            }
+            polls.answered();
+            if (fresh === null) {
+                this.current = { ...this.current, state: 'deleted' };
+                return;
+            }
+            this.current = parseSandbox(fresh.json?.sandbox);
+            if (this.current.state === 'deleted')
+                return;
+            // As in waitFor: the last read goes out just before the deadline.
+            const pause = polls.pause(this.config.pollIntervalMs);
+            if (pause === null)
+                throw timedOut();
+            if (pause > 0)
+                await this.config.sleep(pause, options.signal);
+            if (deadline - this.config.now() <= 0)
+                throw timedOut();
+        }
+    }
+    // --- ports at a URL -----------------------------------------------------------
+    /**
+     * 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) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 22 || port === 81) {
+            throw new PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
+        }
+        const template = this.current.raw.previewUrlTemplate;
+        if (typeof template !== 'string' || !template.includes('{port}')) {
+            throw new PrizedError('preview_unavailable', 'sandbox ports at a URL are not turned on for this deployment', { sandboxId: this.id });
+        }
+        return template.replace('{port}', String(port));
+    }
+    /** 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() {
+        return { [PREVIEW_KEY_HEADER]: this.config.apiKey };
+    }
+    // --- internals ------------------------------------------------------------------
+    /** 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). */
+    async verb(name, signal, deadline, hold) {
+        const path = `${sandboxPathFor(this.id)}/${name}`;
+        const result = await request(this.config, {
+            method: 'POST',
+            url: (leftMs) => apiUrl(this.config, hold ? `${path}${holdQuery(this.config, hold, leftMs)}` : path),
+            retry: 'safe',
+            deadline,
+            signal,
+            sandboxId: this.id,
+        });
+        const doc = result.json?.sandbox;
+        if (doc !== undefined)
+            this.current = parseSandbox(doc);
+    }
+    /**
+     * 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.
+     */
+    async waitFor(want, timeoutMs, signal, reportedMs = timeoutMs) {
+        const deadline = this.config.now() + timeoutMs;
+        const timedOut = (read) => waitTimeout(`${this.id} was ${this.current.state}, not ${want}`, reportedMs, this.id, read);
+        let delay = Math.min(FIRST_POLL_MS, this.config.pollIntervalMs);
+        const polls = new Polls(this.config, deadline);
+        for (let first = true;; first = false) {
+            if (this.current.state === want)
+                return;
+            const failed = failedState(this.current);
+            if (failed)
+                throw failed;
+            if (deadline - this.config.now() <= 0)
+                throw timedOut();
+            if (!first) {
+                // null once the last look, just before the deadline, has been taken.
+                const pause = polls.pause(delay);
+                if (pause === null)
+                    throw timedOut();
+                if (pause > 0)
+                    await this.config.sleep(pause, signal);
+                delay = Math.min(delay * 2, this.config.pollIntervalMs);
+                // Overslept past the deadline (a laptop lid closed, say): no read is sent.
+                if (deadline - this.config.now() <= 0)
+                    throw timedOut();
+            }
+            polls.sent();
+            try {
+                // The wait's deadline bounds each read and its retries too, so a
+                // read that meets a 5xx near the end cannot carry the wait past it.
+                this.current = await fetchInfo(this.config, this.id, signal, deadline);
+                polls.answered();
+            }
+            catch (error) {
+                throw cutByDeadline(error) ? timedOut(error) : error;
+            }
+        }
+    }
+    /** Best-effort delete after a failed wait, bounded (as the Python SDK's); never throws. */
+    async discard() {
+        try {
+            await this.delete({ timeoutMs: RECLAIM_DELETE_MS });
+        }
+        catch {
+            // The sandbox's own timers (maxRuntimeMin) are the backstop.
+        }
+    }
+    /**
+     * 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.
+     */
+    static async settle(config, children, deadline, reportedMs, signal, parentId) {
+        const settled = (child) => child.state === 'running' || child.state === 'error' || child.state === 'deleting' || child.state === 'deleted';
+        const timedOut = (pending, read) => waitTimeout(`Fork copies not running (${pending.map((c) => `${c.id} ${c.state}`).join(', ')})`, reportedMs, parentId, read);
+        const polls = new Polls(config, deadline);
+        for (;;) {
+            const pending = children.filter((child) => !settled(child));
+            if (pending.length === 0)
+                return;
+            const pause = polls.pause(config.pollIntervalMs);
+            if (pause === null)
+                throw timedOut(pending);
+            if (pause > 0)
+                await config.sleep(pause, signal);
+            if (deadline - config.now() <= 0)
+                throw timedOut(pending); // as in waitFor
+            let infos;
+            polls.sent();
+            try {
+                // As in waitFor: the wait's deadline bounds the read and its retries.
+                infos = await listInfos(config, signal, deadline);
+                polls.answered();
+            }
+            catch (error) {
+                throw cutByDeadline(error) ? timedOut(pending, error) : error;
+            }
+            const byId = new Map(infos.map((info) => [info.id, info]));
+            for (const child of pending) {
+                // The list leaves deleted sandboxes out.
+                child.current = byId.get(child.id) ?? { ...child.current, state: 'deleted' };
+            }
+        }
+    }
+}
+async function fetchInfo(config, id, signal, deadline) {
+    const result = await request(config, {
+        method: 'GET',
+        url: apiUrl(config, sandboxPathFor(id)),
+        retry: 'safe',
+        signal,
+        deadline,
+        sandboxId: id,
+    });
+    return parseSandbox(result.json?.sandbox);
+}
+async function listInfos(config, signal, deadline, query = '') {
+    const result = await request(config, { method: 'GET', url: apiUrl(config, `/sandboxes${query}`), retry: 'safe', signal, deadline });
+    const list = result.json?.sandboxes;
+    if (!Array.isArray(list))
+        throw new PrizedError('bad_response', 'The API answered without a sandbox list.');
+    return list.map(parseSandbox);
+}
+/** request(), with a 404 not_found answered as null. */
+async function requestOr404(config, spec) {
+    try {
+        return await request(config, spec);
+    }
+    catch (error) {
+        if (error instanceof PrizedError && error.status === 404 && error.code === 'not_found')
+            return null;
+        throw error;
+    }
+}