@prized/sdk 0.1.1 → 0.1.3

package/dist/cjs/http.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Polls = exports.LAST_LOOK_MAX_MS = exports.LAST_LOOK_MS = exports.MAX_RETRY_AFTER_MS = exports.MAX_BACKOFF_MS = exports.BACKOFF_FIRST_MS = exports.DEFAULT_POLL_OUTAGE_MS = exports.DEFAULT_EDGE_URL = exports.DEFAULT_BASE_URL = void 0;
+exports.UPLOAD_CHUNK = exports.timing = exports.Polls = exports.LAST_LOOK_MAX_MS = exports.LAST_LOOK_MS = exports.MAX_RETRY_AFTER_MS = exports.MAX_BACKOFF_MS = exports.BACKOFF_FIRST_MS = exports.DEFAULT_POLL_OUTAGE_MS = exports.DEFAULT_EDGE_URL = exports.DEFAULT_BASE_URL = void 0;
 exports.abortableSleep = abortableSleep;
 exports.validOutage = validOutage;
 exports.resolveConfig = resolveConfig;
@@ -21,6 +21,11 @@ const outcome_js_1 = require("./outcome.js");
 const version_js_1 = require("./version.js");
 exports.DEFAULT_BASE_URL = 'https://api.prized.dev';
 exports.DEFAULT_EDGE_URL = 'https://term.prized.dev';
+/** Node's own fetch (not Bun's or Deno's, which also say they are Node), with web streams. */
+function nodeFetch() {
+    const versions = globalThis.process?.versions;
+    return typeof versions?.node === 'string' && versions.bun === undefined && versions.deno === undefined && typeof ReadableStream === 'function';
+}
 function envApiKey() {
     try {
         const env = globalThis.process?.env;
@@ -82,8 +87,9 @@ function abortableSleep(ms, signal) {
 /**
  * How long a wait (a streamed or long exec, a handle's wait()) keeps polling
  * while its polls fail before it gives up (pollOutageMs), and a streamed or
- * long exec stops its command: long enough to ride out a dropped connection
- * or an edge that restarts. The Python SDK's DEFAULT_POLL_OUTAGE.
+ * long exec stops its command, and how long a start is sent again: long
+ * enough to ride out a dropped connection or an edge that restarts (about
+ * 70 s, the last time it crashed). The Python SDK's DEFAULT_POLL_OUTAGE.
  */
 exports.DEFAULT_POLL_OUTAGE_MS = 120_000;
 /** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
@@ -125,6 +131,7 @@ function resolveConfig(options = {}) {
         sleep: options.sleep ?? abortableSleep,
         now: options.now ?? Date.now,
         random: options.random ?? Math.random,
+        streamBodies: options.fetch === undefined && nodeFetch(),
     };
 }
 /** Prized's own domain: its API and its edges are hosts under it. */
@@ -241,6 +248,8 @@ const NEVER_RETRY = new Set([
     'idempotency_conflict',
     'paid_balance_required',
     'insufficient_balance',
+    // A 503 that says preview links are off on this deployment: no wait turns them on.
+    'preview_unavailable',
 ]);
 const EXEC_UNDELIVERED = new Set([
     'rate_limited',
@@ -372,6 +381,84 @@ function backoffMs(config, attempt) {
     const base = Math.min(exports.MAX_BACKOFF_MS, exports.BACKOFF_FIRST_MS * 2 ** attempt);
     return Math.round(base / 2 + (config.random() * base) / 2);
 }
+/**
+ * How long a file transfer may move no bytes before the attempt is given up
+ * (sdk/retry-spec.json transferStallMs; the Python SDK's TRANSFER_STALL).
+ * The edge holds a request about 20 s at most before it reads the body (its
+ * admission queue, then waking a paused sandbox), and ends a body that brings
+ * nothing for 60 s itself: kept above that, a stalled copy is over at the
+ * edge before the next one goes to the same staged name, so the two never
+ * race. Once an upload's last byte is handed over, its answer is waited for
+ * that and a second more for every uploadAnswerBytesPerSecond it sent: what
+ * the socket's buffers, or a proxy that takes a whole body before it sends it
+ * on, still hold moves unseen, and must not read as a stall (the Python SDK's
+ * UPLOAD_ANSWER_RATE). Mutable for tests only.
+ */
+exports.timing = { transferStallMs: 120_000, uploadAnswerBytesPerSecond: 128 * 1024 };
+/** A streamed upload goes out this many bytes at a time. */
+exports.UPLOAD_CHUNK = 64 * 1024;
+/**
+ * A body's bytes, to stream; null for one to send as it is. By shape, not
+ * instanceof: a Uint8Array or Buffer from another realm (a test runner's vm
+ * context, say) is one too.
+ */
+async function bodyBytes(body) {
+    if (typeof body === 'string')
+        return new TextEncoder().encode(body);
+    if (ArrayBuffer.isView(body))
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    if (Object.prototype.toString.call(body) === '[object ArrayBuffer]')
+        return new Uint8Array(body);
+    if (typeof body.arrayBuffer === 'function')
+        return new Uint8Array(await body.arrayBuffer());
+    return null;
+}
+/**
+ * `bytes` as a stream fed UPLOAD_CHUNK at a time, `moved` told each time
+ * fetch asks for more, and at the end given the answer's allowance
+ * (timing.uploadAnswerBytesPerSecond).
+ */
+function inPieces(bytes, moved) {
+    let at = 0;
+    return new ReadableStream({
+        pull(controller) {
+            if (at >= bytes.byteLength) {
+                moved((bytes.byteLength / exports.timing.uploadAnswerBytesPerSecond) * 1000);
+                controller.close();
+                return;
+            }
+            moved();
+            // A copy: a runtime may take the piece's buffer as it sends it.
+            controller.enqueue(bytes.slice(at, at + exports.UPLOAD_CHUNK));
+            at += exports.UPLOAD_CHUNK;
+        },
+    }, 
+    // Nothing read ahead: a pull is the socket taking the last piece.
+    { highWaterMark: 0 });
+}
+/** A body read whole, `moved` told of every piece. */
+async function readAll(response, moved) {
+    if (response.body === null)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    const parts = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        moved();
+        parts.push(value);
+        size += value.byteLength;
+    }
+    const whole = new Uint8Array(size);
+    let at = 0;
+    for (const part of parts) {
+        whole.set(part, at);
+        at += part.byteLength;
+    }
+    return whole;
+}
 /**
  * One fetch, body included, under one timeout and the caller's signal. A
  * body that stalls or breaks after the headers fails the attempt like a
@@ -380,10 +467,24 @@ function backoffMs(config, attempt) {
 async function attemptOnce(config, spec, url, timeoutMs) {
     const controller = new AbortController();
     let timedOut = false;
+    let stalled = false;
     const timer = setTimeout(() => {
         timedOut = true;
         controller.abort();
     }, timeoutMs);
+    // The stall bound starts over whenever bytes move (stallMs), until the attempt is over.
+    let stall;
+    let over = false;
+    const moved = (extraMs = 0) => {
+        if (spec.stallMs === undefined || over)
+            return;
+        clearTimeout(stall);
+        stall = setTimeout(() => {
+            stalled = true;
+            timedOut = true;
+            controller.abort();
+        }, spec.stallMs + extraMs);
+    };
     const onAbort = () => controller.abort();
     spec.signal?.addEventListener('abort', onAbort, { once: true });
     const headers = {
@@ -393,30 +494,52 @@ async function attemptOnce(config, spec, url, timeoutMs) {
         ...spec.headers,
     };
     let body;
-    if (spec.json !== undefined) {
-        headers['content-type'] = 'application/json';
-        body = JSON.stringify(spec.json);
-    }
-    else if (spec.body !== undefined) {
-        headers['content-type'] = spec.contentType ?? 'application/octet-stream';
-        body = spec.body;
-    }
+    // Watched from the start unless an upload goes out unwatched (Config.streamBodies).
+    let watched = spec.stallMs !== undefined && spec.body === undefined;
+    let streamed = false;
     let status = null;
     try {
+        if (spec.json !== undefined) {
+            headers['content-type'] = 'application/json';
+            body = JSON.stringify(spec.json);
+        }
+        else if (spec.body !== undefined) {
+            headers['content-type'] = spec.contentType ?? 'application/octet-stream';
+            body = spec.body;
+            const bytes = spec.stallMs !== undefined && config.streamBodies ? await bodyBytes(spec.body) : null;
+            if (bytes !== null) {
+                headers['content-length'] = String(bytes.byteLength);
+                body = inPieces(bytes, moved);
+                streamed = true;
+                watched = true;
+            }
+        }
+        if (watched)
+            moved();
         const response = await config.fetch(url, {
             method: spec.method,
             headers,
             body: body,
+            // A streamed body (Node's fetch asks for it): sent before the answer is read.
+            ...(streamed ? { duplex: 'half' } : {}),
             // Never follow a redirect with the key attached.
             redirect: 'manual',
             signal: controller.signal,
         });
         status = response.status;
+        if (spec.stallMs !== undefined)
+            moved();
         const ok = response.status >= 200 && response.status < 300;
         if (response.status >= 300 && response.status < 400) {
             await response.body?.cancel().catch(() => undefined);
             return { answer: { status: response.status, headers: response.headers, text: '', bytes: null } };
         }
+        if (spec.stallMs !== undefined) {
+            const whole = await readAll(response, moved);
+            if (ok && spec.read === 'bytes')
+                return { answer: { status: response.status, headers: response.headers, text: '', bytes: whole } };
+            return { answer: { status: response.status, headers: response.headers, text: new TextDecoder('utf-8').decode(whole), bytes: null } };
+        }
         if (ok && spec.read === 'bytes') {
             const bytes = new Uint8Array(await response.arrayBuffer());
             return { answer: { status: response.status, headers: response.headers, text: '', bytes } };
@@ -424,10 +547,12 @@ async function attemptOnce(config, spec, url, timeoutMs) {
         return { answer: { status: response.status, headers: response.headers, text: await response.text(), bytes: null } };
     }
     catch (error) {
-        return { error, timedOut, status };
+        return { error, timedOut, stalled, status };
     }
     finally {
+        over = true;
         clearTimeout(timer);
+        clearTimeout(stall);
         spec.signal?.removeEventListener('abort', onAbort);
     }
 }
@@ -490,8 +615,8 @@ async function request(config, spec) {
     const timeoutMs = spec.timeoutMs ?? config.requestTimeoutMs;
     const sandboxId = spec.sandboxId ?? null;
     const effect = spec.effect ?? (spec.retry === 'exec' ? (0, outcome_js_1.commandEffect)() : undefined);
-    // Whether an attempt that was sent again may have reached the sandbox.
-    let acted = false;
+    // Whether an attempt that was sent again (or an earlier copy) may have reached the sandbox.
+    let acted = spec.acted ?? false;
     // Names the last attempt's failure, if any, so a call cut short by its
     // deadline still says what it was waiting out (a 503, a rate limit).
     const pastDeadline = (last) => {
@@ -500,9 +625,10 @@ async function request(config, spec) {
         let error = new errors_js_1.PrizedError('timeout', `The time allowed for this call ran out.${tail}`, { sandboxId, cause: last });
         // A command is sent again only when it provably never arrived, so every
         // attempt of one cut short this way never reached the sandbox. A staged
-        // upload's copies may have, unless each provably never arrived.
-        if (effect !== undefined && spec.retry !== 'safe')
-            error = (0, outcome_js_1.withOutcome)(error, effect, spec.retry === 'staged' && acted ? 'maybe' : 'never');
+        // upload's copies may have, unless each provably never arrived, and so
+        // may a keyed start's (the one `safe` request that names an effect).
+        if (effect !== undefined)
+            error = (0, outcome_js_1.withOutcome)(error, effect, spec.retry !== 'exec' && acted ? 'maybe' : 'never');
         cutShort.add(error);
         return error;
     };
@@ -540,7 +666,10 @@ async function request(config, spec) {
             }
             const unsentAttempt = !outcome.timedOut && neverSent(outcome.error);
             failure = failed(outcome.timedOut
-                ? new errors_js_1.PrizedError('timeout', `No answer within ${attemptMs} ms`, { sandboxId, cause: outcome.error })
+                ? new errors_js_1.PrizedError('timeout', outcome.stalled ? `No bytes moved for ${spec.stallMs} ms` : `No answer within ${attemptMs} ms`, {
+                    sandboxId,
+                    cause: outcome.error,
+                })
                 : unsentAttempt
                     ? new errors_js_1.PrizedError('network_error', null, { sandboxId, cause: outcome.error })
                     : new errors_js_1.PrizedError('network_error', lostMessage(spec.method, url, outcome.error), { sandboxId, cause: outcome.error }));
@@ -565,7 +694,8 @@ async function request(config, spec) {
                 }
             }
             if (answer.status >= 300 && answer.status < 400) {
-                throw failed(new errors_js_1.PrizedError('unexpected_redirect', null, { status: answer.status, sandboxId }));
+                // A refusal; worded only when an earlier copy of a keyed start may have arrived.
+                throw raised(failed(new errors_js_1.PrizedError('unexpected_redirect', null, { status: answer.status, sandboxId })), null, acted, effect);
             }
             const retryAfter = (0, errors_js_1.parseRetryAfter)(answer.headers.get('retry-after'), config.now());
             failure = failed((0, errors_js_1.errorFromResponse)(answer.status, answer.text, retryAfter, sandboxId, urlPath(url)));

package/dist/cjs/index.d.ts

@@ -1,5 +1,5 @@
 export { Sandbox, DEFAULT_TEMPLATE, PREVIEW_KEY_HEADER } from './sandbox.js';
-export type { CreateOptions, ForkOptions, ListOptions, WaitableOptions } from './sandbox.js';
+export type { CreateOptions, ForkOptions, ListOptions, PortPreview, PreviewToken, PreviewTokenOptions, SetPortPublicOptions, WaitableOptions, } from './sandbox.js';
 export { CommandHandle, DEFAULT_EXEC_TIMEOUT_MS, MAX_BLOCKING_EXEC_MS } from './commands.js';
 export type { CommandStatus, ExecOptions, WaitOptions } from './commands.js';
 export { Files } from './files.js';

package/dist/cjs/outcome.d.ts

@@ -49,6 +49,15 @@ export declare function withOutcome(error: PrizedError, effect: Effect, outcome:
  * connection closes. TypeScript only: the Python SDK takes no signal.
  */
 export declare function withAbort(error: PrizedError, effect: Effect, outcome: 'never' | 'maybe' | 'did'): PrizedError;
+/**
+ * What a start that gave up throws when the failure it gives up with
+ * (`failure`, Outage's pick) is not the last copy's own: an earlier copy's,
+ * worded before a later copy may have reached the sandbox, or what a copy
+ * cut short by the window met, not yet worded. Worded for the start: as one
+ * that may have started when any copy may have reached the sandbox
+ * (`anyActed`), else as one that never did. The Python SDK's start_gave_up.
+ */
+export declare function startGaveUp(failure: PrizedError, anyActed: boolean): PrizedError;
 /**
  * A background start that may have started (`error`, from withOutcome or
  * withAbort) and that the SDK then stopped by its run id (`stopped`: the

package/dist/cjs/outcome.js

@@ -10,6 +10,7 @@ exports.mayHaveActed = mayHaveActed;
 exports.restate = restate;
 exports.withOutcome = withOutcome;
 exports.withAbort = withAbort;
+exports.startGaveUp = startGaveUp;
 exports.startAbandoned = startAbandoned;
 exports.runAborted = runAborted;
 exports.pollFailed = pollFailed;
@@ -105,12 +106,14 @@ function maybeTail(effect, closed) {
         tail += ` ${effect.check}`;
     return tail;
 }
+/** How an error says its request never reached the sandbox (withOutcome). */
+const NEVER_TAIL = ' It never reached the sandbox, so it had no effect.';
 /** `error` (same code, status and body), its message saying what it means for `effect`. */
 function withOutcome(error, effect, outcome) {
     if (outcome === null)
         return error;
     if (outcome === 'never')
-        return restate(error, `${trimmed(error.message)}. It never reached the sandbox, so it had no effect.`);
+        return restate(error, `${trimmed(error.message)}.${NEVER_TAIL}`);
     if (outcome === 'did')
         return acting(error, `${effect.did}, but the answer could not be read (${detail(error)}).`);
     return acting(error, `No clear answer came back (${detail(error)}), so ${maybeTail(effect, false)}`);
@@ -134,6 +137,23 @@ function stopTail(runId, stopped) {
         ? ` The SDK stopped ${runId}, or it had already ended.`
         : ` The SDK could not confirm it stopped: it may still be running as ${runId} (exec('ps -ef | grep ${runId}') finds it).`;
 }
+/**
+ * What a start that gave up throws when the failure it gives up with
+ * (`failure`, Outage's pick) is not the last copy's own: an earlier copy's,
+ * worded before a later copy may have reached the sandbox, or what a copy
+ * cut short by the window met, not yet worded. Worded for the start: as one
+ * that may have started when any copy may have reached the sandbox
+ * (`anyActed`), else as one that never did. The Python SDK's start_gave_up.
+ */
+function startGaveUp(failure, anyActed) {
+    if (acted.has(failure))
+        return failure;
+    const never = failure.message.endsWith(NEVER_TAIL);
+    if (never && !anyActed)
+        return failure;
+    const plain = never ? restate(failure, failure.message.slice(0, -NEVER_TAIL.length)) : failure;
+    return withOutcome(plain, startEffect(), anyActed ? 'maybe' : 'never');
+}
 /**
  * A background start that may have started (`error`, from withOutcome or
  * withAbort) and that the SDK then stopped by its run id (`stopped`: the

package/dist/cjs/output.js

@@ -279,6 +279,7 @@ async function download(toolbox, path, signal) {
         retry: 'safe',
         read: 'bytes',
         timeoutMs: READ_MS,
+        stallMs: http_js_1.timing.transferStallMs,
         deadline: toolbox.config.now() + READ_MS,
         signal,
         sandboxId: toolbox.sandboxId,

package/dist/cjs/sandbox.d.ts

@@ -4,6 +4,42 @@ 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";
+/** A sandbox port's preview link (`setPortPublic`): its URL, and whether
+ *  it is public, until when. */
+export interface PortPreview {
+    sandboxId: string;
+    port: number;
+    /** The port's URL for a program with the API key (`previewUrl`). */
+    url: string;
+    /** The same port on prized.link, which opens in a browser tab once the
+     *  port is public; null where the deployment has no browser domain. */
+    browserUrl: string | null;
+    /** Anyone with the URL reaches the port, no credential needed. */
+    public: boolean;
+    /** When the port goes private again on its own; null while private. */
+    publicExpiresAt: Date | null;
+}
+/** A short-lived URL token for a sandbox port (`previewToken`). */
+export interface PreviewToken {
+    /** The preview URL with the token in its `prized_token` query parameter. */
+    url: string;
+    /** The same on prized.link, to open in a browser tab or a frame; null
+     *  where the deployment has no browser domain. */
+    browserUrl: string | null;
+    token: string;
+    expiresAt: Date;
+}
+export interface PreviewTokenOptions {
+    /** How long the token opens the port, in seconds: 60 to 86 400. Default 3600 (an hour). */
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
+export interface SetPortPublicOptions {
+    /** With `true`: how long the port stays public, in seconds: 300 to
+     *  2 592 000 (30 days). Default 7 days. */
+    expiresIn?: number;
+    signal?: AbortSignal;
+}
 /** 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. */
@@ -128,8 +164,9 @@ export declare class 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
+     * none are left). Each request selects the current matches, so a repeat
+     * can delete sandboxes created since the first request. An uncertain
+     * answer is not retried; list the matches before deleting again. Each
      * counts toward the workspace's quotas until it is gone;
      * `Sandbox.list({ labels })` coming back empty means they all are.
      */
@@ -193,6 +230,35 @@ export declare class Sandbox {
      *  `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>;
+    /**
+     * A short-lived token for `port`, for a client that cannot send
+     * `Prized-Key` in a header: a person in a browser tab, a WebSocket opened
+     * from a browser page, or a program you hand this one port to and not
+     * your API key. `browserUrl` is the port on prized.link with the token in
+     * its `prized_token` query parameter: it opens in a browser tab or a
+     * frame (the token moves into a cookie for that host; a tab's first visit
+     * shows a notice). `url` is the same on the preview URL, for programs. The
+     * app never sees the token. It opens the port until `expiresAt`
+     * (`expiresIn` seconds, 60 to 86 400, an hour by default), or until this
+     * client's key is revoked; making the port public or private again ends
+     * it too. It never wakes a paused sandbox (`503 sandbox_not_running`).
+     * Needs a paid workspace (`share_links_need_payment` otherwise).
+     */
+    previewToken(port: number, options?: PreviewTokenOptions): Promise<PreviewToken>;
+    /**
+     * Make `port` public (anyone with its URL reaches it, with no
+     * credential) for `expiresIn` seconds (300 to 2 592 000, 7 days by
+     * default), or private again with `false`. Public needs the workspace
+     * owner's key and a paid workspace, and counts toward the workspace's 10
+     * public ports and links. The answer's `browserUrl` (prized.link) opens in
+     * a browser tab (a tab's first visit shows a notice); `url` answers
+     * programs, `fetch` and WebSockets. A public port never wakes a paused
+     * sandbox. A port already public keeps its expiry: make it private, then
+     * public again, to change it.
+     */
+    setPortPublic(port: number, isPublic: boolean, options?: SetPortPublicOptions): Promise<PortPreview>;
+    /** A port a preview link may name: 1 to 65 535, never 22 or 81 (the sandbox's own). */
+    private previewPort;
     /** 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). */

package/dist/cjs/sandbox.js

@@ -76,6 +76,13 @@ function wholeMinutes(name, value, allowZero) {
     }
     return value;
 }
+function wholeSeconds(name, value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value <= 0)
+        throw new errors_js_1.PrizedError('invalid_argument', `${name} must be a whole number of seconds > 0`);
+    return value;
+}
 function apiUrl(config, path) {
     return `${config.baseUrl}/api/v1${path}`;
 }
@@ -440,8 +447,9 @@ class 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
+     * none are left). Each request selects the current matches, so a repeat
+     * can delete sandboxes created since the first request. An uncertain
+     * answer is not retried; list the matches before deleting again. Each
      * counts toward the workspace's quotas until it is gone;
      * `Sandbox.list({ labels })` coming back empty means they all are.
      */
@@ -455,7 +463,15 @@ class Sandbox {
         const deleted = new Set();
         const stuck = (calls) => new errors_js_1.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 (0, http_js_1.request)(config, { method: 'DELETE', url: apiUrl(config, `/sandboxes${query}`), retry: 'safe', deadline });
+            // A label is a live selector, not a stable resource or idempotency key.
+            const result = await (0, http_js_1.request)(config, {
+                method: 'DELETE', url: apiUrl(config, `/sandboxes${query}`), retry: 'exec', deadline,
+                effect: {
+                    maybe: 'some matching sandboxes may already be deleting',
+                    did: 'The matching sandboxes were marked for deletion',
+                    check: 'It was not sent again: list the matching sandboxes before deleting again, because the matches may have changed.',
+                },
+            });
             const answer = result.json;
             const ids = answer?.ids;
             if (!Array.isArray(ids) || !ids.every((id) => typeof id === 'string')) {
@@ -552,9 +568,13 @@ class Sandbox {
             body.maxRuntimeMin = maxRuntimeMin;
         const idempotencyKey = options.idempotencyKey ?? randomKey();
         const wire = snapshot(body); // as in create
+        const path = `${sandboxPathFor(this.id)}/fork`;
+        // Held by the API until every copy runs (or its bound), as create is,
+        // instead of polled; the cleanup's replay only wants the ids.
+        const held = options.wait !== false;
         const send = (deadline, attempts) => (0, http_js_1.request)(this.config, {
             method: 'POST',
-            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/fork`),
+            url: (leftMs) => apiUrl(this.config, held && attempts !== undefined ? `${path}${holdQuery(this.config, 'running', leftMs)}` : path),
             json: wire,
             headers: { 'idempotency-key': idempotencyKey },
             retry: 'safe',
@@ -677,9 +697,7 @@ class Sandbox {
      * `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 errors_js_1.PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
-        }
+        this.previewPort(port);
         const template = this.current.raw.previewUrlTemplate;
         if (typeof template !== 'string' || !template.includes('{port}')) {
             throw new errors_js_1.PrizedError('preview_unavailable', 'sandbox ports at a URL are not turned on for this deployment', { sandboxId: this.id });
@@ -693,6 +711,93 @@ class Sandbox {
     previewHeaders() {
         return { [exports.PREVIEW_KEY_HEADER]: this.config.apiKey };
     }
+    /**
+     * A short-lived token for `port`, for a client that cannot send
+     * `Prized-Key` in a header: a person in a browser tab, a WebSocket opened
+     * from a browser page, or a program you hand this one port to and not
+     * your API key. `browserUrl` is the port on prized.link with the token in
+     * its `prized_token` query parameter: it opens in a browser tab or a
+     * frame (the token moves into a cookie for that host; a tab's first visit
+     * shows a notice). `url` is the same on the preview URL, for programs. The
+     * app never sees the token. It opens the port until `expiresAt`
+     * (`expiresIn` seconds, 60 to 86 400, an hour by default), or until this
+     * client's key is revoked; making the port public or private again ends
+     * it too. It never wakes a paused sandbox (`503 sandbox_not_running`).
+     * Needs a paid workspace (`share_links_need_payment` otherwise).
+     */
+    async previewToken(port, options = {}) {
+        this.previewPort(port);
+        const expiresIn = wholeSeconds('expiresIn', options.expiresIn);
+        const result = await (0, http_js_1.request)(this.config, {
+            method: 'POST',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/ports/${port}/token`),
+            json: expiresIn === undefined ? {} : { expiresIn },
+            // A second copy mints a second token nobody holds, which expires on its own.
+            retry: 'safe',
+            signal: options.signal,
+            deadline: (0, http_js_1.callDeadline)(this.config),
+            sandboxId: this.id,
+        });
+        const body = result.json;
+        const expiresAt = (0, types_js_1.parseTime)(body?.expiresAt);
+        if (typeof body?.url !== 'string' || typeof body.token !== 'string' || expiresAt === null) {
+            throw new errors_js_1.PrizedError('bad_response', 'the API answered a preview token without its url, token or expiry', { sandboxId: this.id });
+        }
+        return {
+            url: body.url,
+            browserUrl: typeof body.browserUrl === 'string' ? body.browserUrl : null,
+            token: body.token,
+            expiresAt,
+        };
+    }
+    /**
+     * Make `port` public (anyone with its URL reaches it, with no
+     * credential) for `expiresIn` seconds (300 to 2 592 000, 7 days by
+     * default), or private again with `false`. Public needs the workspace
+     * owner's key and a paid workspace, and counts toward the workspace's 10
+     * public ports and links. The answer's `browserUrl` (prized.link) opens in
+     * a browser tab (a tab's first visit shows a notice); `url` answers
+     * programs, `fetch` and WebSockets. A public port never wakes a paused
+     * sandbox. A port already public keeps its expiry: make it private, then
+     * public again, to change it.
+     */
+    async setPortPublic(port, isPublic, options = {}) {
+        this.previewPort(port);
+        if (typeof isPublic !== 'boolean')
+            throw new errors_js_1.PrizedError('invalid_argument', 'isPublic must be true or false', { sandboxId: this.id });
+        const expiresIn = wholeSeconds('expiresIn', options.expiresIn);
+        if (expiresIn !== undefined && !isPublic) {
+            throw new errors_js_1.PrizedError('invalid_argument', 'expiresIn applies only when making a port public', { sandboxId: this.id });
+        }
+        const result = await (0, http_js_1.request)(this.config, {
+            method: 'PUT',
+            url: apiUrl(this.config, `${sandboxPathFor(this.id)}/ports/${port}`),
+            json: isPublic ? { public: true, ...(expiresIn === undefined ? {} : { expiresIn }) } : { public: false },
+            // Setting the same state again changes nothing.
+            retry: 'safe',
+            signal: options.signal,
+            deadline: (0, http_js_1.callDeadline)(this.config),
+            sandboxId: this.id,
+        });
+        const doc = result.json?.preview;
+        if (doc === undefined || typeof doc.url !== 'string' || typeof doc.public !== 'boolean') {
+            throw new errors_js_1.PrizedError('bad_response', 'the API answered a port without its url or public setting', { sandboxId: this.id });
+        }
+        return {
+            sandboxId: typeof doc.sandboxId === 'string' ? doc.sandboxId : this.id,
+            port: typeof doc.port === 'number' ? doc.port : port,
+            url: doc.url,
+            browserUrl: typeof doc.browserUrl === 'string' ? doc.browserUrl : null,
+            public: doc.public,
+            publicExpiresAt: (0, types_js_1.parseTime)(doc.publicExpiresAt),
+        };
+    }
+    /** A port a preview link may name: 1 to 65 535, never 22 or 81 (the sandbox's own). */
+    previewPort(port) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535 || port === 22 || port === 81) {
+            throw new errors_js_1.PrizedError('bad_request', `port must be a whole number from 1 to 65535 other than 22 and 81, not ${String(port)}`, { sandboxId: this.id });
+        }
+    }
     // --- 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

package/dist/cjs/shell.d.ts

@@ -11,7 +11,8 @@ export declare const RUN_ID_RE: RegExp;
 /**
  * Minutes (by the sandbox's clock) a cleaned or abandoned run's directory
  * stays: what keeps a resend of its start from running the command again.
- * The SDK stops resending a start within minutes, so an hour is ample; each
+ * The SDK stops resending a start once pollOutageMs (2 minutes by default)
+ * has run out after its first copy's retries, so an hour is ample; each
  * cleanup then removes the ones older than that, so they never pile up.
  */
 export declare const CLEANED_KEEP_MIN = 60;

package/dist/cjs/shell.js

@@ -64,7 +64,8 @@ exports.RUN_ID_RE = /^run_[0-9a-f]{16}$/;
 /**
  * Minutes (by the sandbox's clock) a cleaned or abandoned run's directory
  * stays: what keeps a resend of its start from running the command again.
- * The SDK stops resending a start within minutes, so an hour is ample; each
+ * The SDK stops resending a start once pollOutageMs (2 minutes by default)
+ * has run out after its first copy's retries, so an hour is ample; each
  * cleanup then removes the ones older than that, so they never pile up.
  */
 exports.CLEANED_KEEP_MIN = 60;

package/dist/cjs/toolbox.d.ts

@@ -30,6 +30,8 @@ export declare function rawExec(toolbox: Toolbox, req: RawExecRequest, options:
     deadline?: number | undefined;
     /** What the command does, for an error that says whether it happened (`exec`: a command unless given). */
     effect?: Effect | undefined;
+    /** An earlier copy of a keyed start may have reached the sandbox. */
+    acted?: boolean | undefined;
 }): Promise<ExecResult>;
 /** A helper command the SDK sends itself; a non-zero exit is the caller's to judge. */
 export declare function helperExec(toolbox: Toolbox, command: string, options?: {

package/dist/cjs/toolbox.js

@@ -51,6 +51,7 @@ async function rawExec(toolbox, req, options) {
         deadline: options.deadline,
         sandboxId: toolbox.sandboxId,
         ...(effect === undefined ? {} : { effect }),
+        ...(options.acted ? { acted: true } : {}),
     });
     const doc = result.json;
     if (doc === null || typeof doc !== 'object' || typeof doc.exitCode !== 'number') {