@prized/sdk 0.1.1 → 0.1.3

package/README.md

@@ -13,6 +13,10 @@ console.log(stdout); // 42
 await sandbox.delete();
 ```
 
+Save it as `hello.mjs` and run `node hello.mjs` (Node 18 or later) with
+`PRIZED_API_KEY` set ([Authentication](#authentication)). Top-level `await`
+needs an ES module, so a `.js` file needs `"type": "module"` in package.json.
+
 Sandboxes are in beta. A workspace on free credit alone runs them on the
 free tier: up to 10 at once, each up to 2 vCPU and 4 GB of memory and 60
 minutes of running. A top-up or a paid plan lifts the limits: a sandbox then
@@ -60,6 +64,8 @@ to fewer permissions needs **Sandboxes: Write** to create, run commands and
 move files; **Sandboxes: Read** is enough for `list`, `connect`, `refresh` and
 `templates`.
 
+Your coding agent can install the Prized skill with `npx skills add prized-dev/skills -g -y` (it should ask you first), so it knows when and how to use Prized the next time you ask for a sandbox.
+
 Every entry point (`create`, `connect`, `list`, `deleteByLabels`, `templates`) takes the same
 client options:
 
@@ -72,7 +78,7 @@ client options:
 | `maxRetries` | `3` | See [Retries](#retries-and-timeouts). |
 | `requestTimeoutMs` | `60000` | Per API request. |
 | `pollIntervalMs` | `500` | The longest the SDK's own polling goes between checks of the sandbox (the first come sooner). It does not cover the request itself, or the time the API holds a create, pause or resume for you (up to 8 seconds). |
-| `pollOutageMs` | `120000` | How long a wait keeps polling through a dropped connection (or a 5xx, or a rate limit) before it gives up: a streamed or long `exec` then stops the command, a handle's `wait()` throws. `exec` and `wait()` take it per call too. |
+| `pollOutageMs` | `120000` | How long a wait keeps polling through a dropped connection (or a 5xx, or a rate limit) before it gives up: a streamed or long `exec` then stops the command, a handle's `wait()` throws. A background, streamed or long `exec` keeps sending its start for as long. `exec` and `wait()` take it per call too. |
 
 Your API key goes with every request, so a plain `http` URL to a host other
 than this machine is refused with `invalid_argument` before anything is sent,
@@ -181,8 +187,10 @@ await Promise.all(mine.map((s) => s.delete()));
 ### `Sandbox.deleteByLabels(labels, options?)`
 
 Deletes every sandbox carrying all of `labels` (at least one) in one call and
-resolves with their ids. It is safe to repeat (one already deleting is listed
-again; none matching resolves `[]`). A sandbox being deleted still counts
+resolves with their ids. Each request selects the current matches, including
+sandboxes created since an earlier request. If an answer is lost, the SDK
+throws without repeating the delete; list the matches before deleting again.
+A sandbox being deleted still counts
 toward your quota until `Sandbox.list({ labels })` no longer returns it.
 
 ```ts
@@ -287,7 +295,9 @@ off by an idle connection and its output is never truncated. The result is
 the same either way. If the connection drops meanwhile, the SDK keeps
 polling for up to 2 minutes (`pollOutageMs`, on the call or the client)
 before it gives up and stops the command; a refused key, or an answer that
-settles it (the sandbox deleted or not running), stops it at once.
+settles it (the sandbox deleted or not running), stops it at once. Its
+start rides one out the same way: it is sent again for up to `pollOutageMs`,
+and a resend finds the first start, so the command runs once.
 Background and streamed commands run with `PYTHONUNBUFFERED=1` unless
 their environment already sets it (`env: { PYTHONUNBUFFERED: '' }` keeps
 Python's buffering), so a Python program's output arrives as it prints.
@@ -295,13 +305,17 @@ Python's buffering), so a Python program's output arrives as it prints.
 Commands run as the user `prized` (home `/home/prized`, no sudo). The
 templates come with git, curl, Python 3 with pip and venv, Node 22 with npm
 and pnpm; `prized-agent-v1` adds Claude Code and Codex. Install what else
-you need into your home: Python packages into a venv
-(`python3 -m venv ~/.venv && ~/.venv/bin/pip install numpy`; plain
-`pip install`, `--user` too, is refused), and `npm` with a user prefix.
+you need into your home: `pip install numpy` goes to `~/.local` (or use a
+venv: `python3 -m venv ~/.venv && ~/.venv/bin/pip install numpy`), and
+`npm install -g` to `~/.local` too.
 
 ## Background commands
 
-`background: true` starts the command and returns a `CommandHandle` at once.
+`background: true` starts the command and returns a `CommandHandle` once it
+has started. A start that meets a dropped connection or a 5xx is sent again
+for up to `pollOutageMs` once its own retries run out (a resend finds the
+first start, so the command runs once), so the call can take that long while
+the connection is down.
 The command runs in its own session: it keeps running after your process
 exits, survives a pause and resume, and while it runs, a kill reaches every
 process it started (not one that left its process group, such as a daemon).
@@ -413,11 +427,6 @@ prized sandbox timeout sbx_0123456789abcdef --in 30m  # deleted 30 minutes from
 On a paid plan an extend stops at 7 days from now; on the free tier neither
 moves the end later.
 
-<!-- Held while sandbox ports at a URL are switched off: this section stays
-out of the rendered README until they are on. In the change that turns them
-on, delete these five lines and the closing line after the section, take
-"a sandbox's ports at a URL" out of "Not yet" under Limits, and delete the
-test "the README holds A port at a URL" (test/preview.test.ts).
 ## A port at a URL
 
 `sandbox.previewUrl(port)` is the https URL a port of the sandbox answers at:
@@ -444,15 +453,47 @@ the preview URL, and one that points anywhere else comes back as
 `Prized-Location` instead, which no client follows. To follow a redirect,
 resolve its `Location` against the preview URL and send `previewHeaders()`
 again only when the result has the preview URL's origin, scheme included.
-Call preview URLs from server-side code: a browser hides `Location` from
-`'manual'`.
+Call preview URLs with the key from server-side code: a browser hides
+`Location` from `'manual'`.
 
 Nothing is created: the URL is the sandbox's own, and every port has one
-(but 22 and 81). A request to a paused sandbox resumes it and waits up to 10
-seconds for it, as `exec` does; send `Prized-Auto-Resume: false` to get
-`503` instead. `previewUrl` throws `preview_unavailable` where this is not
-turned on.
--->
+(but 22 and 81). A request with the key to a paused sandbox resumes it and
+waits up to 10 seconds for it, as `exec` does; send
+`Prized-Auto-Resume: false` to get `503` instead. `previewUrl` throws
+`preview_unavailable` where this is not turned on.
+
+A person in a browser, or a client that cannot send the key in a header (a
+WebSocket from a browser page, a program you hand one port to and not your
+key), takes a short-lived token in the URL instead:
+
+```ts
+const { browserUrl, url, expiresAt } = await sandbox.previewToken(3000, { expiresIn: 600 });
+// browserUrl: https://3000-sbx-….prized.link/?prized_token=… opens in a tab or an iframe
+const socket = new WebSocket(url.replace('https:', 'wss:'));
+```
+
+`browserUrl` is the port on `prized.link`, a domain of its own for pages your
+sandboxes serve: open it in a tab or embed it in an iframe. The browser swaps
+the token for a cookie for that one host, so the page's own assets, fetches
+and WebSockets work, and a tab's first visit shows a short notice that the
+page is hosted by a Prized user. `url` is the same token on the preview URL,
+for programs. The token opens that one port until `expiresAt` (an hour by
+default, a day at most), or until your key is revoked; the app never sees
+it. To let anyone reach a port with no credential at all, make it public:
+
+```ts
+const { browserUrl } = await sandbox.setPortPublic(3000, true, { expiresIn: 7 * 86400 });
+await sandbox.setPortPublic(3000, false); // private again
+```
+
+Tokens and public ports need a paid workspace (`share_links_need_payment`
+otherwise), and making a port public takes the workspace owner's key. On the
+preview URL they answer programs, `fetch` and WebSockets but not a page
+opened in a browser tab (`403 ingress_browser_page`, which names the
+`browserUrl`); on `browserUrl` they open in a browser too. Neither wakes a
+paused sandbox: a request gets `503` with `error: 'sandbox_not_running'`
+until something with the key resumes it. Making a port public or private
+again ends the tokens made for it.
 
 ## Fork
 
@@ -528,7 +569,7 @@ try {
 | `sandbox_not_running` | 409 | The sandbox is not running and the call could not wake it: it is resizing (`refresh()` until it leaves `resizing`, then retry), failed, or being deleted. A paused sandbox is resumed by any command or file call. The SDK never turns waking off; a request that carries `Prized-Auto-Resume: false` (added by a custom `fetch`, say) gets this for a paused or starting sandbox too: drop the header to let the call wake it and wait. |
 | `sandbox_not_ready` | 503 | A paused or starting sandbox did not reach running within the edge's 10-second wait. The wait starts when the edge, having checked the key, finds the sandbox not running, and calls with the same key arriving during it share it, so a later call may wait less. Nothing ran; retry. |
 | `parent_not_running` | 409 | Only a running or paused sandbox can be forked. |
-| `parent_not_forkable` | 409 | This sandbox cannot be forked. `reason` `resized_while_paused`: it has no memory to copy; resume it, then fork it. `reason` `parent_too_big`: its machine cannot hold even one copy beside it; fork a smaller sandbox. |
+| `parent_not_forkable` | 409 | This sandbox cannot be forked. `reason` `resized_while_paused` or `memory_discarded`: it has no memory to copy; resume it, then fork it. `reason` `parent_too_big`: its machine cannot hold even one copy beside it; fork a smaller sandbox. |
 | `fork_capacity` | 409 | The parent's machine has room for only `fits` more copies (`err.body?.fits`). If `fits` is above 0, fork that many or fewer; or try again later, or start a new sandbox and fork that one, keeping the parent until it runs. The new sandbox and each copy count toward your quota: at the limit, delete sandboxes you no longer need with `delete({ wait: true })` (a deleting sandbox still counts), or top up on the free tier. Copy out what you need first, and never delete a parent while a copy forked from it is still starting. |
 | `fork_unsupported_host` | 409 | The parent's machine cannot start copies of it. With `reason` `host_retiring` (`err.reason`), the machine is being replaced: it keeps the parent but starts no new sandboxes, so no retry or smaller `count` helps. Create a new sandbox, set it up again, and fork that one. |
 | `sandbox_capacity` | 503 | No sandbox capacity is free right now. Nothing was created or billed; the SDK retries it after `Retry-After`. |
@@ -565,18 +606,21 @@ try {
   `resume`, `fork` and `delete` (the request, its retries and the wait, its
   polls included; with `wait: false` too), twice `requestTimeoutMs` (2
   minutes by default) for `connect`, `list`, `templates`, `refresh` and
-  `keepAlive`, and 10 minutes for a file transfer. `Retry-After` is honoured
+  `keepAlive`, and 10 minutes for a file transfer, whose attempt is given up
+  after 2 minutes with no bytes moving (a dropped connection) and sent again
+  by the rules below (on Node's own `fetch`; elsewhere, or with a `fetch` you
+  pass, an upload is watched only once its answer starts). `Retry-After` is honoured
   up to a minute. A retry that could not start in time is not sent: the call
   throws `timeout`. A wait's last poll goes out just before its deadline.
-- A command, a `files.remove` or a `kill` is sent again only when it
+- A command, a `files.remove`, a `kill` or `deleteByLabels` is sent again only when it
   provably never arrived: the connection never opened, or the answer says so
   (rate limited, the sandbox not ready). If an answer is lost after it was
   delivered, the SDK throws (`sandbox_unreachable`, `network_error`,
-  `timeout`) rather than risk running a command twice.
+  `timeout`) rather than risk repeating the operation on work that changed.
 - A file write (`files.write`, `files.upload`) goes up under a temporary name
   beside the file, which is sent again like a read (a lost answer, a 502, 503
-  or 504), every copy to the same name and none after the transfer's 10
-  minutes, so one that timed out is not sent again. One command that is never
+  or 504, 2 minutes with no bytes moving), every copy to the same name and
+  none after the transfer's 10 minutes. One command that is never
   sent again then puts it in place: if that command's answer is lost, the SDK
   throws rather than risk overwriting what the sandbox wrote to the file since.
 - Did it run? When a command answered in one call (`exec` without
@@ -594,7 +638,8 @@ try {
   says the same of its signal
   (`status()` tells you whether the command is still running). A background
   command (or a streamed or long `exec`, which runs as one) whose start got
-  no clear answer is stopped by the SDK, and the error says so, or, when the
+  no clear answer for longer than `pollOutageMs` is stopped by the SDK, and
+  the error says so, or, when the
   SDK could not confirm the stop, that it may still be running and under
   which run id. So is a streamed or long `exec` whose polling fails while
   it runs (a dropped connection or a 5xx for longer than `pollOutageMs`, a
@@ -652,8 +697,8 @@ runtime) are on the pricing and docs pages at prized.dev; a create or resume
 past one fails with `sandbox_quota_exceeded`.
 
 Not yet: custom templates (from a Dockerfile), egress allow and deny lists,
-a sandbox's ports at a URL, more than 32 vCPU or 128 GB, GPUs, and regions
-other than US West.
+a port URL that opens without an API key (for a browser or a webhook), more
+than 32 vCPU or 128 GB, GPUs, and regions other than US West.
 
 ## Runtimes
 

package/dist/cjs/commands.d.ts

@@ -104,7 +104,9 @@ export interface ExecOptions {
      * its polls fail (no answer, a 5xx, a rate limit), in ms, before it gives
      * up and stops the command. Default: the client's `pollOutageMs`
      * (120 000). A refused key, or an answer that settles the run (the
-     * sandbox deleted or not running, the run gone), stops it at once.
+     * sandbox deleted or not running, the run gone), stops it at once. The
+     * start of a background, streamed or long command is sent again for as
+     * long (a resend finds the first start, so the command runs once).
      */
     pollOutageMs?: number;
 }

package/dist/cjs/commands.js

@@ -477,7 +477,48 @@ async function cleanupOnceGone(toolbox, id) {
         }
     }
 }
-async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, unbuffered) {
+/**
+ * Send a start script. It is keyed by a run id the SDK chose, so a resend
+ * finds the first start instead of starting the command twice. Once one
+ * copy's retries run out, it is sent again through an outage of up to
+ * `outageMs` (pollOutageMs), paced as a wait's polls are (Outage): an edge
+ * that restarts mid-start does not cost the command, as it does not cost a
+ * running one its wait. Each copy's error counts the copies before it
+ * (`acted`), so one that gives up says the command may have started when any
+ * copy may have reached the sandbox. The Python SDK's _send_start.
+ */
+async function sendStart(toolbox, req, signal, outageMs) {
+    const config = toolbox.config;
+    const outage = new Outage(outageMs);
+    // Whether an earlier copy may have reached the sandbox: an abort between
+    // copies then says the command may have started, else that it never did.
+    let acted = false;
+    const aborted = (cause) => (0, outcome_js_1.withAbort)(new errors_js_1.PrizedError('aborted', null, { sandboxId: toolbox.sandboxId, cause }), (0, outcome_js_1.startEffect)(), acted ? 'maybe' : 'never');
+    for (;;) {
+        const sentAt = config.now();
+        try {
+            return await (0, toolbox_js_1.rawExec)(toolbox, req, { retry: 'safe', signal, deadline: outage.deadline(sentAt), effect: (0, outcome_js_1.startEffect)(), acted });
+        }
+        catch (error) {
+            if (!(error instanceof errors_js_1.PrizedError))
+                throw error;
+            acted = acted || (0, outcome_js_1.mayHaveActed)(error);
+            if (signal?.aborted)
+                throw error;
+            const step = outage.failed(error, sentAt, config.now(), (0, http_js_1.cutByDeadline)(error), (tries) => (0, http_js_1.backoffMs)(config, tries));
+            // What a copy met, not the window's cut.
+            if (step.pause === null)
+                throw step.failure === error ? error : (0, outcome_js_1.startGaveUp)(step.failure, acted);
+            try {
+                await config.sleep(step.pause, signal);
+            }
+            catch (abort) {
+                throw abort instanceof errors_js_1.PrizedError && abort.code === 'aborted' ? aborted(step.failure) : abort;
+            }
+        }
+    }
+}
+async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, unbuffered, outageMs) {
     // Nothing sent yet: nothing to stop.
     if (signal?.aborted)
         throw (0, outcome_js_1.withOutcome)(new errors_js_1.PrizedError('aborted', null, { sandboxId: toolbox.sandboxId }), (0, outcome_js_1.startEffect)(), 'never');
@@ -489,10 +530,7 @@ async function startBackground(toolbox, command, cwd, env, timeoutMs, signal, un
     // Launched, but no pid came within the start's own wait: it may yet run.
     let unsettled = false;
     try {
-        const result = await (0, toolbox_js_1.rawExec)(toolbox, { command: (0, shell_js_1.startScript)(id, command, timeoutMs === null ? null : timeoutMs / 1000, unbuffered), cwd, env, timeoutMs: 60_000 }, 
-        // Keyed by a run id this call chose, so a resend finds the first start
-        // instead of starting the command twice.
-        { retry: 'safe', signal, effect: (0, outcome_js_1.startEffect)() });
+        const result = await sendStart(toolbox, { command: (0, shell_js_1.startScript)(id, command, timeoutMs === null ? null : timeoutMs / 1000, unbuffered), cwd, env, timeoutMs: 60_000 }, signal, outageMs);
         pid = Number(result.stdout.trim());
         if (result.exitCode !== 0 || !Number.isInteger(pid) || pid <= 0) {
             unsettled = result.exitCode === shell_js_1.NO_PID_EXIT;
@@ -538,7 +576,7 @@ async function execCommand(toolbox, command, options = {}) {
     const cwd = options.cwd === undefined ? undefined : (0, shell_js_1.sandboxPath)(options.cwd);
     if (options.background) {
         const limit = options.timeoutMs ? options.timeoutMs : null;
-        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, true);
+        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, true, outageMs);
         handle.timeoutMs = limit;
         return handle;
     }
@@ -546,7 +584,7 @@ async function execCommand(toolbox, command, options = {}) {
     const streamed = options.onStdout !== undefined || options.onStderr !== undefined;
     if (streamed || timeoutMs === 0 || timeoutMs > exports.MAX_BLOCKING_EXEC_MS) {
         const limit = timeoutMs === 0 ? null : timeoutMs;
-        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, streamed);
+        const handle = await startBackground(toolbox, text, cwd, options.env, limit, options.signal, streamed, outageMs);
         const waitOptions = {};
         if (options.onStdout)
             waitOptions.onStdout = options.onStdout;

package/dist/cjs/files.d.ts

@@ -13,9 +13,10 @@ export interface WriteOptions {
 }
 /**
  * The sandbox's file transfers take at most this long, retries included:
- * the edge's own limit on one transfer. A write's upload sent again (a
- * staged one is, after a lost answer or a 502, 503 or 504) is sent only
- * while time is left, so a transfer that timed out is not.
+ * the edge's own limit on one transfer. An attempt that moves no bytes for
+ * timing.transferStallMs (2 minutes) is given up; a download, or a write's
+ * staged upload, is then sent again (as after a lost answer or a 502, 503 or
+ * 504) while time is left.
  */
 export declare const FILE_TIMEOUT_MS: number;
 /** The publish script's own exits (the Python SDK's too). */
@@ -60,8 +61,8 @@ export declare class Files {
      * stays executable; a new file gets the sandbox's default (0600 in
      * prized-base-v1 and prized-agent-v1). `mode` sets the permission bits either way.
      * The bytes go up under a temporary name beside the file, sent again if
-     * need be (a lost answer, a 502, 503 or 504; all copies within the
-     * transfer's 10 minutes),
+     * need be (a lost answer, a 502, 503 or 504, 2 minutes with no bytes
+     * moving; all copies within the transfer's 10 minutes),
      * and one command that is never sent again puts them in place: a write
      * whose answer to that command was lost throws, since it may have landed
      * and the sandbox written the file since (read it back, or write again,

package/dist/cjs/files.js

@@ -11,9 +11,10 @@ const shell_js_1 = require("./shell.js");
 const toolbox_js_1 = require("./toolbox.js");
 /**
  * The sandbox's file transfers take at most this long, retries included:
- * the edge's own limit on one transfer. A write's upload sent again (a
- * staged one is, after a lost answer or a 502, 503 or 504) is sent only
- * while time is left, so a transfer that timed out is not.
+ * the edge's own limit on one transfer. An attempt that moves no bytes for
+ * timing.transferStallMs (2 minutes) is given up; a download, or a write's
+ * staged upload, is then sent again (as after a lost answer or a 502, 503 or
+ * 504) while time is left.
  */
 exports.FILE_TIMEOUT_MS = 10 * 60_000;
 function byteSize(data) {
@@ -168,6 +169,7 @@ class Files {
             retry: 'safe',
             read: 'bytes',
             timeoutMs: exports.FILE_TIMEOUT_MS,
+            stallMs: http_js_1.timing.transferStallMs,
             deadline: this.toolbox.config.now() + exports.FILE_TIMEOUT_MS,
             sandboxId: this.toolbox.sandboxId,
         });
@@ -180,8 +182,8 @@ class Files {
      * stays executable; a new file gets the sandbox's default (0600 in
      * prized-base-v1 and prized-agent-v1). `mode` sets the permission bits either way.
      * The bytes go up under a temporary name beside the file, sent again if
-     * need be (a lost answer, a 502, 503 or 504; all copies within the
-     * transfer's 10 minutes),
+     * need be (a lost answer, a 502, 503 or 504, 2 minutes with no bytes
+     * moving; all copies within the transfer's 10 minutes),
      * and one command that is never sent again puts them in place: a write
      * whose answer to that command was lost throws, since it may have landed
      * and the sandbox written the file since (read it back, or write again,
@@ -261,6 +263,7 @@ class Files {
             retry,
             effect,
             timeoutMs: exports.FILE_TIMEOUT_MS,
+            stallMs: http_js_1.timing.transferStallMs,
             deadline: this.toolbox.config.now() + exports.FILE_TIMEOUT_MS,
             sandboxId: this.toolbox.sandboxId,
         });

package/dist/cjs/http.d.ts

@@ -32,7 +32,9 @@ export interface ClientOptions {
      * rate limit), in ms, before it gives up: a streamed or long `exec` then
      * stops the command, a handle's `wait()` throws. Default 120 000. `0`
      * gives up once one poll's retries run out. `exec` and `wait()` take it
-     * per call too.
+     * per call too. The start of a background, streamed or long `exec` is
+     * sent again for as long, so an edge that restarts mid-start does not
+     * cost the command.
      */
     pollOutageMs?: number;
     /** Sleep seam (tests inject one that never really waits). */
@@ -54,13 +56,21 @@ export interface Config {
     sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
     now: () => number;
     random: () => number;
+    /**
+     * Whether an upload's body goes out as a stream the SDK feeds piece by
+     * piece, so a stalled one is seen (RequestSpec.stallMs): Node's own fetch
+     * only, which asks for each piece once the last has gone into the socket.
+     * Elsewhere (another runtime, a fetch you pass) the body goes as it is.
+     */
+    streamBodies: boolean;
 }
 export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
 /**
  * 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.
  */
 export declare const DEFAULT_POLL_OUTAGE_MS = 120000;
 /** A pollOutageMs given (a number of ms ≥ 0), or undefined. */
@@ -97,8 +107,8 @@ export declare function warmEdge(config: Config): Promise<void>;
  *   Retries network failures, 429/502/503/504, and everything `exec`
  *   retries (the edge's 500 control_plane_unavailable among them). A GET
  *   retries any 500 too (the API's `internal`).
- * - `exec`: a command, an upload or a remove: what the sandbox does
- *   meanwhile could be undone by a second copy. Retried only when it
+ * - `exec`: a command, an upload, a remove or a label-selected delete:
+ *   a second copy could affect later work. Retried only when it
  *   provably never arrived: a connection that never opened, or an answer
  *   saying so (the edge's rate limit, its lookup failing). A lost answer
  *   is never retried: it may already have run.
@@ -120,7 +130,7 @@ export type RetryMode = 'safe' | 'exec' | 'staged';
 export declare function neverSent(error: unknown, depth?: number): boolean;
 export declare function retryable(error: PrizedError, mode: RetryMode, method: RequestSpec['method']): boolean;
 export interface RequestSpec {
-    method: 'GET' | 'POST' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
     /** The URL, or one built per attempt from the ms left before `deadline`
      *  (Infinity without one): a held request asks only for what is left. */
     url: string | ((leftMs: number) => string);
@@ -139,6 +149,14 @@ export interface RequestSpec {
     sandboxId?: string | null;
     /** How to read a 2xx body. Default `json`. */
     read?: 'json' | 'bytes' | 'none';
+    /**
+     * A file transfer's no-progress bound: an attempt that moves no bytes
+     * either way for this long (a connection dropped without a reset) ends as
+     * a timeout, sent again by `retry`'s rules while `deadline` allows. An
+     * upload's sending is watched only where its body is streamed
+     * (Config.streamBodies); its answer always is.
+     */
+    stallMs?: number;
     /**
      * Told of every attempt that failed (no answer, an error answer, or a 2xx
      * that could not be read), before it is retried or thrown. A create or
@@ -153,6 +171,12 @@ export interface RequestSpec {
      * its error says so too.
      */
     effect?: Effect;
+    /**
+     * An earlier copy of this keyed request may have reached the sandbox (the
+     * background start, sent again through an outage), so its error says so
+     * too.
+     */
+    acted?: boolean;
 }
 export interface HttpResult {
     status: number;
@@ -215,6 +239,25 @@ export declare class Polls {
 }
 /** Delay before retry number `attempt` (0-based): exponential with jitter. */
 export declare function backoffMs(config: Config, attempt: number): number;
+/**
+ * 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.
+ */
+export declare const timing: {
+    transferStallMs: number;
+    uploadAnswerBytesPerSecond: number;
+};
+/** A streamed upload goes out this many bytes at a time. */
+export declare const UPLOAD_CHUNK: number;
 /**
  * What an error answer (not a 2xx: request() judges those) says about
  * whether the sandbox acted: `never` for the codes that prove the request