withruntime 0.9.0 → 0.11.0

package/README.src.md

@@ -14,7 +14,7 @@ The client uses `RUNTIME_API_KEY` when it is set, and otherwise the connection
 this machine saved when the CLI connected it (one browser approval, no key to
 copy). On a server or a CI runner, set `RUNTIME_API_KEY` from your secret
 manager: `npx withruntime keys create` prints a new key once after an account
-owner approves it in the browser, or create one at
+owner, admin or developer approves it in the browser, or create one at
 https://withruntime.com/account/keys. Never put a key in browser code, a URL or
 a command-line argument.
 
@@ -22,7 +22,8 @@ a command-line argument.
 import { Sandbox } from "withruntime";
 
 await using sbx = await Sandbox.create();
-const result = await sbx.exec("python3 -c 'print(6 * 7)'");
+await sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n");
+const result = await sbx.exec("python3 /workspace/invoice.py");
 console.log(result.exitCode, result.stdout);
 ```
 
@@ -32,6 +33,8 @@ Node 22 call `await sbx.stop()`). With no arguments you get the free
 trial while it lasts ({{trial-hours}} free hours, up to {{trial-sandboxes}} sandboxes running at once), 2 vCPU, 4 GiB of
 memory and a 4 GiB disk. The current default image includes NumPy, pandas and
 matplotlib; see the [sandbox environment](https://withruntime.com/docs/sandbox-environment).
+Omitting `funding` can use prepaid credit after the trial is exhausted. Use
+`Sandbox.create({ funding: "trial" })` for free use only; it never falls back to paid.
 
 The sandbox object does the rest:
 
@@ -59,7 +62,9 @@ no compute; `idlePauseSeconds` sets {{idle-pause-min}} to {{idle-pause-max}}, or
 `Sandbox.getOrCreate(name)` returns the sandbox with that name, woken if it is
 paused, or creates it.
 
-The client has `sandboxes`, `images`, `volumes`, `snapshots`, `jobs`, `secrets`,
+`runtime.sandbox`, `snapshot`, `image`, `volume`, `job`, `domain`, `port` and
+`address` name the products as the CLI does. Their existing plural names
+remain aliases of the same product clients. The client has `sandboxes`, `images`, `volumes`, `snapshots`, `jobs`, `secrets`,
 `limits`, `feedback` and `support`; `webhooks`, `events`, `otel` and `audit`
 to watch the account; `domains`, `ports`, `addresses`, `tunnel` and `network`
 to connect sandboxes to your own world (paid accounts); and `mcp`, `sso`,
@@ -67,6 +72,8 @@ to connect sandboxes to your own world (paid accounts); and `mcp`, `sso`,
 the key is read-only and what its agent may still spend today. Every write carries an idempotency key, made for you, so the SDK's
 own retries (timeouts, 429, 503) never do anything twice. Errors are typed and
 carry a `code`, a `hint` and a `requestId`.
+`runtime.usageRequests("7d")` reads the account's API call counts and error rates;
+counts are exact decimal strings, and an empty window has a null `errorPercent`.
 
 ## Behind a proxy
 
@@ -89,7 +96,7 @@ Runtime improves fast because agents tell us what they run into: reports go stra
 
 ## Code written for E2B
 
-`withruntime/e2b` runs code written for E2B's SDK on Runtime. Change the
+`withruntime/e2b` translates supported E2B sandbox calls to Runtime. Change the
 import and set `RUNTIME_API_KEY`. The
 [switch guide](https://withruntime.com/docs/migrate) covers the other providers
 and how to work out what you save:
@@ -123,7 +130,7 @@ package list every mapping and gap.
 
 ## Code written for Blaxel
 
-`withruntime/blaxel` runs code written for Blaxel's sandbox SDK. Change the
+`withruntime/blaxel` translates supported Blaxel sandbox calls. Change the
 import:
 
 ```ts no-run
@@ -134,7 +141,7 @@ Sandboxes get Blaxel's default of 4096 MB, with one vCPU for every 2048 MB.
 Standby becomes Runtime's pause: after 60 seconds without a call a sandbox
 pauses with its memory and processes, and the next call wakes it. Envs,
 processes by name, files, previews, snapshots, forks and the code interpreter
-work as they do on Blaxel, and so do sessions: `sandbox.sessions` makes a
+are supported by the adapter, along with sessions: `sandbox.sessions` makes a
 Runtime sandbox session and `SandboxInstance.fromSession` drives the sandbox
 with its token. A Blaxel key is never sent anywhere. Drives, codegen, schedules and Blaxel's agent, model and MCP hosting throw
 `NotSupportedError` before anything happens, naming what to use instead.
@@ -154,7 +161,8 @@ https://withruntime.com/docs/frameworks.
 ## CLI
 
 ```bash no-run
-npx withruntime sandbox run -- python3 -c 'print(6 * 7)'   # connects on first use
+printf '%s\n' 'print(sum([125, 250, 375]))' > invoice.py
+npx withruntime sandbox run -- python3 - < invoice.py   # connects on first use
 npx withruntime sandbox create
 npx withruntime help
 ```

package/VERCEL.md

@@ -16,9 +16,9 @@ from withruntime.vercel import sandbox  # was: from vercel import sandbox
 from withruntime.vercel.sandbox import sync as sandbox  # was: from vercel.sandbox import sync as sandbox
 ```
 
-The mapping was written against `@vercel/sandbox` 3.5.0 and `vercel-sandbox`
+The mapping was written against `@vercel/sandbox` 3.5.1 and `vercel-sandbox`
 0.7.0 on PyPI (the `vercel.sandbox` module of `vercel` 0.11.4), checked
-23 September 2026.
+30 September 2026.
 
 ## Keys
 
@@ -34,7 +34,10 @@ are ignored.
 - **Machine:** Vercel's default, 2 vCPUs with 2048 MiB each.
   `resources: { vcpus }` sets another, with 2048 MiB per vCPU.
 - **Timeout:** Vercel's default of 5 minutes. Runtime's leases run 60 seconds to
-  an hour; `extendTimeout` moves the end later, as often as needed.
+  an hour. A longer `timeout` (Python `execution_time_limit`) starts with an
+  hour's lease, and the sandbox object renews it toward the timeout while it
+  lives, never past it; once the program ends, the sandbox pauses within an
+  hour. `extendTimeout` moves the end later, as often as needed.
 - **Persistence:** persistent by default, as in Vercel. `stop()` and the end of
   the timeout pause the sandbox, keeping its files and also its memory and
   processes. `Sandbox.get({ name })`, or the next command or file call, wakes
@@ -63,6 +66,8 @@ are ignored.
 | `source: { type: "tarball", url }`, `{ type: "snapshot" }`            | Downloaded and unpacked into the working directory; a Runtime snapshot, with its own shape.                                                 |
 | `networkPolicy`, `updateNetworkPolicy`                                | Runtime network rules: `allow-all`, `deny-all`, or a list of domains and subnets to allow and deny.                                         |
 | `Sandbox.get({ name })`, `getOrCreate`, `list({ tags })`              | The newest live sandbox with that name (or a Runtime id), woken; create when missing; `sandboxes.list` with Vercel's paginator.             |
+| `list({ namePrefix, since, until, sortBy, sortOrder, cursor })`       | Applied here over every sandbox the key sees; the cursor continues the same order. Python's `query_sandboxes` does the same.                |
+| `createUser`, `asUser`, `createGroup`, `addUserToGroup`               | `useradd`, `groupadd` and `usermod` with `sudo`, as Vercel does; a user's commands run under `sudo -u` in its home, its files given to it.  |
 | `Sandbox.fork({ sourceSandbox, name })`                               | A Runtime fork, which copies memory and processes too.                                                                                      |
 | `runCommand(cmd, args)`, `runCommand({ cmd, args, cwd, env, sudo })`  | `exec` of the argv without a shell. `sudo` runs it under `sudo --preserve-env`. A non-zero exit is a result. Past `timeoutMs` it exits 137. |
 | `stdout`, `stderr` writers, `detached: true`, `logs()`, `wait()`      | Output streams to the writers; a detached command is a Runtime process, its logs followed from the start.                                   |
@@ -72,8 +77,8 @@ are ignored.
 | Paths                                                                 | Relative paths resolve from `/vercel/sandbox`, which is `/workspace`. A command that names `/vercel/sandbox` finds a link to it.            |
 | `domain(port)`, `update({ ports })`                                   | The public preview of that port; ports added or removed.                                                                                    |
 | `stop()`, `delete()`, `extendTimeout(ms)`                             | `pause` (persistent) or `stop`; `stop`; `extend`.                                                                                           |
-| `update({ timeout, networkPolicy, snapshotExpiration })`              | `extend` (later only), network rules, retention.                                                                                            |
-| `snapshot()`, `Snapshot.get`, `Snapshot.list`, `snapshot.delete()`    | A Runtime snapshot (files, memory and processes), then the sandbox stops, as in Vercel; `snapshots.get`, `list`, `delete`.                  |
+| `update({ timeout, networkPolicy, snapshotExpiration })`              | A new timeout (earlier only while the lease has not reached it), network rules, retention.                                                  |
+| `snapshot()`, `Snapshot.get`, `Snapshot.list`, `snapshot.delete()`    | A verified disk-only capture, then the source stops; restored snapshots start fresh processes; `snapshots.get`, `list`, `delete`.           |
 | Error classes                                                         | `APIError` with a `response` whose status is Runtime's and `json` of `{ error: { code, message } }`; also `code`, `hint` and `requestId`.   |
 | Python: `create_sandbox`, `run_process`, `create_process`, `box.fs`   | The same mapping; operations await or work as context managers, which stop and by default destroy the sandbox; readers iterate by line.     |
 
@@ -82,21 +87,30 @@ are ignored.
 Each of these throws `NotSupportedError` before anything happens. Its
 `feature` names the gap and its `alternative` says what to use.
 
-| Vercel Sandbox                                             | Use instead                                                                                                 |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| An `image` with no Runtime image of that name              | Build it: `npx withruntime image build --dockerfile Dockerfile --name <image>`.                             |
-| `timeout` over one hour                                    | Create with up to an hour, then `extendTimeout` before it ends.                                             |
-| Drives (`mounts`), `networkId`                             | Runtime volumes through `withruntime: { create: { volumes } }`; network rules.                              |
-| A region outside the US, `failoverRegions`                 | Runtime runs in one US region.                                                                              |
-| Network rules that transform or forward requests           | Allow the domain and store the credential as a Runtime secret for it: the sandbox sees a placeholder.       |
-| `openInteractive`                                          | `sandbox.withruntime.terminal(...)` or `npx withruntime sandbox shell <id>`.                                |
-| Extra users and groups (`createUser`, `asUser`)            | `sudo useradd` and `sudo -u` through `runCommand`.                                                          |
-| Sessions (`currentSession`, `listSessions`)                | A Runtime sandbox is its own session.                                                                       |
-| `update` of tags, resources, persistence or region         | Create a new sandbox with them.                                                                             |
-| Overrides on `Sandbox.fork`                                | Fork, then change what Runtime can change.                                                                  |
-| `delete({ deleteOrphanSnapshots: true })`, `Snapshot.tree` | Delete snapshots one by one; `Snapshot.list`.                                                               |
-| `Drive`, `SandboxUser`, `defineSandboxProxy`               | Runtime volumes; `sudo`; `sandbox.withruntime.previews`.                                                    |
-| Listing by time, prefix or cursor (JavaScript)             | List them all and filter the result yourself. (Python applies a name prefix and newest-first order itself.) |
+| Vercel Sandbox                                             | Use instead                                                                                           |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| An `image` with no Runtime image of that name              | Build it: `npx withruntime image build --dockerfile Dockerfile --name <image>`.                       |
+| Drives (`mounts`), `networkId`                             | Runtime volumes through `withruntime: { create: { volumes } }`; network rules.                        |
+| A region outside the US, `failoverRegions`                 | Runtime runs in one US region.                                                                        |
+| Network rules that transform or forward requests           | Allow the domain and store the credential as a Runtime secret for it: the sandbox sees a placeholder. |
+| A `timeout` earlier than the current lease's end           | Stop the sandbox when you are done with it.                                                           |
+| Sessions (`currentSession`, `listSessions`)                | A Runtime sandbox is its own session.                                                                 |
+| `openInteractive`                                          | `sandbox.withruntime.terminal(...)` or `npx withruntime sandbox shell <id>`.                          |
+| `update` of tags, resources, persistence or region         | Create a new sandbox with them.                                                                       |
+| Overrides on `Sandbox.fork`                                | Fork, then change what Runtime can change.                                                            |
+| `delete({ deleteOrphanSnapshots: true })`, `Snapshot.tree` | Delete snapshots one by one; `Snapshot.list`.                                                         |
+| `Drive`, `defineSandboxProxy`                              | Runtime volumes; `sandbox.withruntime.previews`.                                                      |
+| `keepLastSnapshots`                                        | Manage saved snapshots with `Snapshot.list` and `snapshot.delete`.                                    |
+
+Explicit snapshots require the released native disk-capture capability; a server
+that does not confirm disk-only capture is refused. If capture succeeds but the
+source cannot finish stopping, the error retains `snapshotId` and
+`sourceSandboxId` so the saved filesystem remains recoverable. JavaScript exposes
+them in `error.json.error.details` for API errors and directly on other errors;
+Python exposes them in `error.data` for API errors and directly on other errors.
+`snapshot_source_stop_timeout` means the source is still stopping after its wait;
+a failed stop request keeps its original error code. These contracts remain
+partial; controlled package comparisons do not prove hosted restoration.
 
 Some differences are not refusals:
 
@@ -106,8 +120,6 @@ Some differences are not refusals:
   `pwd` prints `/workspace`.
 - Runtime's stock image is Ubuntu 24.04 with Python 3.12, Node.js 24 and Bun;
   Vercel's `universal` has Python 3.14.
-- `keepLastSnapshots` is accepted: a paused Runtime sandbox keeps exactly its
-  latest state.
 - A git source is cloned into the working directory itself.
 
 ## Tests

package/compatibility-lock.json

@@ -9,9 +9,9 @@
         {
           "registry": "npm",
           "name": "e2b",
-          "version": "2.51.0",
+          "version": "2.52.0",
           "artifacts": {
-            "2.51.0": "sha512-P+50lx1nOYpgCFyE1xuz6JVN/TqJivMUiH7v+RW0CUSfb4+NCu8IkC5KruT2sNPgp6aexddQQ77+OZKGpZZJ+Q=="
+            "2.52.0": "sha512-TmUZlAvQq8BbguodpA+BBdawR/x5uILMQtHcLkdaLUqevsDjDdh46IYYU8ZRYKsQ4OhWr4xhsFIPSg1kgf+O0w=="
           }
         },
         {
@@ -25,19 +25,19 @@
         {
           "registry": "pypi",
           "name": "e2b",
-          "version": "2.51.0",
+          "version": "2.52.0",
           "artifacts": {
-            "e2b-2.51.0-py3-none-any.whl": "sha256-951d0fd069f017e760b338a435bdb83589b4bfb9574fc5203a7f777e9cb994c2",
-            "e2b-2.51.0.tar.gz": "sha256-902ee861b30c8ec3e46e7f84db8c993f30695872c7b4490efaad1627ec6e08ba"
+            "e2b-2.52.0-py3-none-any.whl": "sha256-6f4b5084b09986db43e99c7405bae6b14dc56984a69bbb1dc0687f1c71515cfb",
+            "e2b-2.52.0.tar.gz": "sha256-58c0042609513799341d4c1837e2581a4a5e73d3d62c9f1c57495c5e23eedee2"
           }
         },
         {
           "registry": "pypi",
           "name": "e2b-code-interpreter",
-          "version": "2.10.0",
+          "version": "2.10.1",
           "artifacts": {
-            "e2b_code_interpreter-2.10.0-py3-none-any.whl": "sha256-6ba776122086261875bc6033ef2dc42ac6b6e22cefdffdfd19d30e93bb09786f",
-            "e2b_code_interpreter-2.10.0.tar.gz": "sha256-57fb7f9b9ad99ebbdf407619786fdb84e31537c2fbc8358c394aa0f0cbc1af28"
+            "e2b_code_interpreter-2.10.1-py3-none-any.whl": "sha256-f4c9732699ee4b1c289acedac8bff66fccecc6ab374bf0b4ef88d5ad063e333d",
+            "e2b_code_interpreter-2.10.1.tar.gz": "sha256-94e504667788c6cbb175e5deaf1f68e8df474b670343fe1d72e2496b49d5a666"
           }
         }
       ]
@@ -128,18 +128,18 @@
         {
           "registry": "npm",
           "name": "@blaxel/core",
-          "version": "0.3.24",
+          "version": "0.3.25",
           "artifacts": {
-            "0.3.24": "sha512-zF1S7vx+mYHDbK9F4FQbdobz3N+YIlNqHCyOC7R7QpbQ4nP9laeCuQRaN1OTfJVZcRwFvFQ5Nx1lh0su+esd7g=="
+            "0.3.25": "sha512-K6aGUyIpgrPnkpwMOI/U/gbZwveOMu1Am04pkawZQjkp7NUa/roG0HC6NJPBp3AVVJY3CQtkGSWpAJ2DV4ZKpw=="
           }
         },
         {
           "registry": "pypi",
           "name": "blaxel",
-          "version": "0.4.12",
+          "version": "0.4.13",
           "artifacts": {
-            "blaxel-0.4.12-py3-none-any.whl": "sha256-9ca08aa0c1c5aaac87055f684eae002365c55010eaa008d5dc36c552e153210a",
-            "blaxel-0.4.12.tar.gz": "sha256-58dc5c9aea5b21aa65538f811c7de0b24e8e7a411bdf64e374a295eb1b9cb15e"
+            "blaxel-0.4.13-py3-none-any.whl": "sha256-b8817718ca63a2b31a5026f98c7191d5ed8f2f4c1aafc2d4aa57491a560a2146",
+            "blaxel-0.4.13.tar.gz": "sha256-a036256792e85238724b8bce38fb7c0b4f661fe4c3ac576258a8be1736ac8483"
           }
         }
       ]
@@ -225,10 +225,10 @@
         {
           "registry": "pypi",
           "name": "prime-sandboxes",
-          "version": "0.4.0",
+          "version": "0.4.1",
           "artifacts": {
-            "prime_sandboxes-0.4.0-py3-none-any.whl": "sha256-2a15263a30f3a3a27307c83701b92317af83ec8df0968e910100ccdb557cbb6b",
-            "prime_sandboxes-0.4.0.tar.gz": "sha256-a6934a5f5fce8342dbe9ade9816242e893ebf23b83a4fa5fda5b0ddbce651f27"
+            "prime_sandboxes-0.4.1-py3-none-any.whl": "sha256-1a1bb96afacc66d690815be82c0b7af180ea141421b7d180b4a0adbada4f38f0",
+            "prime_sandboxes-0.4.1.tar.gz": "sha256-53f7577dc9070e3b8e30db360f9e3cce3bcc35f8765b26f24f64dbc3c7763b06"
           }
         }
       ]

package/dist/blaxel/errors.js

@@ -95,7 +95,7 @@ const BLAXEL_HINTS = {
     sandbox_paused: "Call sandbox.unarchive(), then try again.",
     not_running: "The sandbox is not running: call sandbox.unarchive() if it was archived, or make a new one with SandboxInstance.create if it was deleted.",
     trial_busy: "The trial's sandboxes are all in use: delete one you no longer need (sandbox.delete()) or archive it (sandbox.archive()), then try again. Moving to paid credit is the account owner's decision.",
-    public_preview_not_allowed: "On the trial, share the port privately: sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt). A public preview needs a paid sandbox, which is the account owner's decision.",
+    public_preview_not_allowed: "On the trial, share the port privately: sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt) on a server supporting absolute preview deadlines. A public preview needs a paid sandbox, which is the account owner's decision.",
     busy: AGAIN,
     guest_busy: AGAIN,
     rate_limited: AGAIN,

package/dist/blaxel/lookup.d.ts

@@ -32,6 +32,7 @@ export declare function findSandbox(client: Runtime, name: string): Promise<Runt
 export declare function findByExternalId(client: Runtime, externalId: string): Promise<RuntimeSandbox>;
 /** Runs a create or fork that names a sandbox. When the name is still held
  * by a sandbox that is stopping (deleted a moment ago, by this client or
- * another), waits for it to stop, up to 30 seconds, and runs it once more, as
- * Blaxel's createIfNotExists waits out a sandbox being deleted. */
+ * another), waits for it to stop, up to 30 seconds, and runs it once more.
+ * This reconciles Runtime's stopping-name conflicts. Blaxel 0.3.25 delegates
+ * createIfNotExists reconciliation to its control plane without client polling. */
 export declare function whenNameFree<T>(client: Runtime, work: () => Promise<T>): Promise<T>;

package/dist/blaxel/lookup.js

@@ -54,8 +54,9 @@ export async function findByExternalId(client, externalId) {
 }
 /** Runs a create or fork that names a sandbox. When the name is still held
  * by a sandbox that is stopping (deleted a moment ago, by this client or
- * another), waits for it to stop, up to 30 seconds, and runs it once more, as
- * Blaxel's createIfNotExists waits out a sandbox being deleted. */
+ * another), waits for it to stop, up to 30 seconds, and runs it once more.
+ * This reconciles Runtime's stopping-name conflicts. Blaxel 0.3.25 delegates
+ * createIfNotExists reconciliation to its control plane without client polling. */
 export async function whenNameFree(client, work) {
     try {
         return await work();

package/dist/blaxel/pagination.d.ts

@@ -28,7 +28,7 @@ export type PaginatedList<T, TQuery extends CursorPaginationQuery = CursorPagina
 /** Blaxel's own helper: the items of a list answer in any of its shapes. */
 export declare function unwrapListData<T>(response: ListResponse<T>): T[];
 /** Blaxel's own helper, for a list fetched by `fetchPage`. */
-export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPaginationQuery>({ response, fetchPage, mapItem, query, }: {
+export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPaginationQuery>({ response, fetchPage, mapItem, query, seenCursors, }: {
     response: ListResponse<TRaw>;
     fetchPage: (query?: TQuery) => Promise<ListResponse<TRaw>>;
     mapItem: (item: TRaw) => TItem | Promise<TItem>;
@@ -36,4 +36,4 @@ export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPa
     seenCursors?: Set<string>;
 }): Promise<PaginatedList<TItem, TQuery>>;
 /** A Runtime page, each item mapped, as Blaxel's paginated list. */
-export declare function paginate<TRaw, TItem>(page: Page<TRaw>, map: (item: TRaw) => TItem): PaginatedList<TItem>;
+export declare function paginate<TRaw, TItem>(page: Page<TRaw>, map: (item: TRaw) => TItem, seenCursors?: Set<string>): PaginatedList<TItem>;

package/dist/blaxel/pagination.js

@@ -8,30 +8,58 @@ export function unwrapListData(response) {
     return response.data ?? [];
 }
 /** Blaxel's own helper, for a list fetched by `fetchPage`. */
-export async function createPaginatedList({ response, fetchPage, mapItem, query, }) {
-    const meta = !response || Array.isArray(response) ? {} : (response.meta ?? {});
+export async function createPaginatedList({ response, fetchPage, mapItem, query, seenCursors, }) {
+    const meta = !response || Array.isArray(response)
+        ? { hasMore: false }
+        : (response.meta ?? { hasMore: false });
     const data = await Promise.all(unwrapListData(response).map(mapItem));
-    return build(data, meta.nextCursor || undefined, async (cursor) => createPaginatedList({
-        response: await fetchPage({ ...(query ?? {}), cursor }),
-        fetchPage,
-        mapItem,
-        ...(query ? { query: { ...query, cursor } } : {}),
-    }));
+    const cursors = new Set(seenCursors);
+    if (query?.cursor)
+        cursors.add(query.cursor);
+    return build(data, meta.nextCursor || undefined, async (cursor) => {
+        if (cursors.has(cursor))
+            throw new Error("Pagination returned a repeated cursor");
+        const nextQuery = { ...(query ?? {}), cursor };
+        const nextSeenCursors = new Set(cursors);
+        nextSeenCursors.add(cursor);
+        return createPaginatedList({
+            response: await fetchPage(nextQuery),
+            fetchPage,
+            mapItem,
+            query: nextQuery,
+            seenCursors: nextSeenCursors,
+        });
+    }, meta);
 }
 /** A Runtime page, each item mapped, as Blaxel's paginated list. */
-export function paginate(page, map) {
-    return build(page.data.map(map), page.nextCursor ?? undefined, async () => {
-        const next = await guard(() => page.next());
-        return next ? paginate(next, map) : null;
+export function paginate(page, map, seenCursors = new Set()) {
+    return build(page.data.map(map), page.nextCursor ?? undefined, async (cursor) => {
+        if (cursor && seenCursors.has(cursor))
+            throw new Error("Pagination returned a repeated cursor");
+        const nextSeenCursors = new Set(seenCursors);
+        if (cursor)
+            nextSeenCursors.add(cursor);
+        const next = await guard(() => page.next(cursor));
+        return next ? paginate(next, map, nextSeenCursors) : null;
     });
 }
-function build(data, nextCursor, more) {
+function build(data, nextCursor, more, meta = {
+    hasMore: nextCursor !== undefined,
+    ...(nextCursor ? { nextCursor } : {}),
+}) {
     const list = {
         data,
-        meta: { hasMore: nextCursor !== undefined, ...(nextCursor ? { nextCursor } : {}) },
-        hasMore: nextCursor !== undefined,
-        ...(nextCursor ? { nextCursor } : {}),
-        nextPage: async () => (nextCursor ? more(nextCursor) : null),
+        meta,
+        get hasMore() {
+            return Boolean(list.nextCursor);
+        },
+        get nextCursor() {
+            return meta.nextCursor || undefined;
+        },
+        nextPage: async () => {
+            const cursor = list.nextCursor;
+            return cursor ? more(cursor) : null;
+        },
         async autoPagingEach(onItem) {
             for await (const item of list)
                 if ((await onItem(item)) === false)

package/dist/blaxel/preview.d.ts

@@ -67,7 +67,8 @@ export declare class SandboxPreviewTokens {
     constructor(preview: SandboxPreview, ctx: PreviewContext);
     get previewName(): string;
     get resourceName(): string;
-    /** A token that lasts until `expiresAt` (at least a minute, at most a week). */
+    /** A token bounded by `expiresAt`; native signing floors milliseconds and
+     * caps it to the caller's session. Older servers refuse without a TTL fallback. */
     create(expiresAt: Date): Promise<SandboxPreviewToken>;
     list(): Promise<never>;
     /** Revokes the preview's tokens. Runtime cannot revoke one token alone, so

package/dist/blaxel/preview.js

@@ -1,8 +1,5 @@
 import { guard, isNotFound, NotSupportedError, responseError } from "./errors.js";
 import { PREVIEW } from "./lookup.js";
-/** Runtime's shortest and longest token, in seconds. */
-const TOKEN_MIN = 60;
-const TOKEN_MAX = 7 * 86_400;
 function checkName(name) {
     if (!/^[A-Za-z0-9._-]{1,48}$/.test(name))
         throw new NotSupportedError(`The preview name "${name}"`, "Use 1 to 48 letters, digits, dots, dashes or underscores.");
@@ -56,19 +53,24 @@ export class SandboxPreviewTokens {
     get resourceName() {
         return this.#ctx.sandboxName;
     }
-    /** A token that lasts until `expiresAt` (at least a minute, at most a week). */
+    /** A token bounded by `expiresAt`; native signing floors milliseconds and
+     * caps it to the caller's session. Older servers refuse without a TTL fallback. */
     async create(expiresAt) {
-        const seconds = Math.ceil((expiresAt.getTime() - Date.now()) / 1000);
-        if (seconds > TOKEN_MAX)
-            throw new NotSupportedError("A preview token lasting more than a week", "Create one for at most seven days, and a new one when it runs out.");
-        const port = this.#preview.spec.port;
-        const got = await this.#ctx.run((runtime) => runtime.previews.get(port, Math.max(TOKEN_MIN, seconds)));
+        const requested = expiresAt.getTime();
+        if (!Number.isFinite(requested))
+            throw responseError(400, "A preview token needs a valid expiration date.");
+        const remaining = requested - Date.now();
+        if (remaining < 60_000 || remaining > 7 * 86_400_000)
+            throw new NotSupportedError("A preview token lasting less than a minute or more than a week", "Request an expiration at least one minute and at most seven days away.");
+        const got = await this.#ctx.run((runtime) => runtime.previews.get(this.#preview.spec.port, undefined, {
+            expiresAt: expiresAt.toISOString(),
+        }));
+        const actual = got.tokenExpiresAt === null ? Number.NaN : Date.parse(got.tokenExpiresAt);
+        if (!got.token || !Number.isFinite(actual) || actual > requested)
+            throw new NotSupportedError("A preview token with the requested expiration", "The server must issue a token that never outlives the requested expiration; no duration-based fallback was requested.");
         return new SandboxPreviewToken({
             metadata: { name: `token-${Date.now()}`, previewName: this.previewName },
-            spec: {
-                ...(got.token ? { token: got.token } : {}),
-                ...(got.tokenExpiresAt ? { expiresAt: got.tokenExpiresAt } : {}),
-            },
+            spec: { token: got.token, expiresAt: got.tokenExpiresAt },
         });
     }
     list() {

package/dist/blaxel/process.js

@@ -152,14 +152,17 @@ export class SandboxProcess {
     }
     /** A call that found the sandbox paused (autoWake off) is made again once,
      * after a wake: it never started, so it cannot run twice. */
-    async #retryPaused(work) {
+    async #retryPaused(work, signal) {
+        signal?.throwIfAborted();
         try {
             return await work();
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (codeOf(error) !== "sandbox_paused")
                 throw translate(error);
             await this.#ctx.wake();
+            signal?.throwIfAborted();
             return guard(work);
         }
     }
@@ -281,16 +284,20 @@ export class SandboxProcess {
         };
     }
     /** A process by pid or name: the registry first, then Runtime's list. */
-    async #find(identifier) {
+    async #find(identifier, signal) {
+        signal?.throwIfAborted();
         const runtime = await this.#ctx.live();
+        signal?.throwIfAborted();
         const registry = this.#registry;
         const known = registry.byName.get(identifier) ?? (registry.meta.has(identifier) ? identifier : undefined);
         if (known !== undefined) {
-            const process = await this.#retryPaused(() => runtime.processes.get(known));
+            const process = await this.#retryPaused(() => runtime.processes.get(known, { signal }), signal);
+            signal?.throwIfAborted();
             registry.processes.set(known, process);
             return { id: known, info: process.info, process };
         }
-        const all = await this.#retryPaused(() => runtime.processes.list());
+        const all = await this.#retryPaused(() => runtime.processes.list({ signal }), signal);
+        signal?.throwIfAborted();
         let found;
         for (const info of all) {
             const parsed = parseProcessLine(info.command);
@@ -323,7 +330,9 @@ export class SandboxProcess {
         const running = found.info.state === "running";
         if (running && !untilExit && found.info.outputBytes <= found.info.firstOffset)
             return out;
+        signal?.throwIfAborted();
         const runtime = await this.#ctx.live();
+        signal?.throwIfAborted();
         const abort = new AbortController();
         const forward = () => abort.abort();
         signal?.throwIfAborted();
@@ -369,9 +378,30 @@ export class SandboxProcess {
     /** The process, with the output it has written so far. */
     async get(identifier, options = {}) {
         options.signal?.throwIfAborted();
-        const found = await this.#find(identifier);
-        const out = await this.#output(found, false, options.signal);
-        return this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+        const signal = options.signal;
+        let onAbort;
+        const interrupted = new Promise((_, reject) => {
+            onAbort = () => reject(new Error("Process read was interrupted.", { cause: signal?.reason }));
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+            const reading = (async () => {
+                const found = await this.#find(identifier, signal);
+                const out = await this.#output(found, false, signal);
+                signal?.throwIfAborted();
+                return this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+            })();
+            return await Promise.race([reading, interrupted]);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+            throw error;
+        }
+        finally {
+            if (onAbort)
+                signal?.removeEventListener("abort", onAbort);
+        }
     }
     /** Waits for the process to end (at most `maxWait` ms, -1 for no limit) and
      * answers it with its output. The process is never stopped by the wait. */
@@ -390,10 +420,24 @@ export class SandboxProcess {
         signal?.throwIfAborted();
         signal?.addEventListener("abort", forward, { once: true });
         const timer = maxWait === -1 ? undefined : setTimeout(() => abort.abort(late()), maxWait);
+        let onAbort;
+        const interrupted = new Promise((_, reject) => {
+            onAbort = () => {
+                const reason = abort.signal.reason;
+                reject(reason instanceof Error
+                    ? reason
+                    : new Error("Process wait was interrupted.", { cause: reason }));
+            };
+            abort.signal.addEventListener("abort", onAbort, { once: true });
+        });
         try {
-            const found = await this.#find(identifier);
-            const out = await this.#output(found, true, abort.signal);
-            return await this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+            const result = (async () => {
+                const found = await this.#find(identifier, abort.signal);
+                const out = await this.#output(found, true, abort.signal);
+                abort.signal.throwIfAborted();
+                return await this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+            })();
+            return await Promise.race([result, interrupted]);
         }
         catch (error) {
             if (abort.signal.aborted)
@@ -402,6 +446,8 @@ export class SandboxProcess {
         }
         finally {
             clearTimeout(timer);
+            if (onAbort)
+                abort.signal.removeEventListener("abort", onAbort);
             signal?.removeEventListener("abort", forward);
         }
     }

package/dist/blaxel/sandbox.d.ts

@@ -32,6 +32,8 @@ export type SandboxForkOptions = {
     /** A snapshot's id or, of this sandbox's snapshots, its name. */
     snapshotId?: string;
     envs?: Env[];
+    /** Blaxel's fork override; Runtime cannot enforce this override during a fork. */
+    lifecycle?: SandboxLifecycle;
 };
 export type SandboxArchiveOptions = {
     wait?: boolean;

package/dist/blaxel/sandbox.js

@@ -750,6 +750,8 @@ export class SandboxInstance {
      * (files, memory and running processes), or started from a snapshot with
      * `snapshotId`. `envs` are added over this sandbox's. */
     async fork(targetName, options = {}) {
+        if (options.lifecycle !== undefined)
+            throw new NotSupportedError("Overriding lifecycle during a fork", "Omit lifecycle to use the existing Runtime fork behavior.");
         refuseApplication(options);
         const envs = envRecord(options.envs);
         checkEnvNames(Object.keys(envs));

package/dist/blaxel/snapshot.js

@@ -22,13 +22,11 @@ export function snapshotModel(snapshot, sandboxName) {
 }
 /** Envs as a record; a nameless one is refused. */
 export function envRecord(envs) {
-    const out = {};
-    for (const env of envs ?? []) {
+    return Object.fromEntries((envs ?? []).map((env) => {
         if (!env.name)
             throw responseError(400, "every env needs a name");
-        out[env.name] = env.value ?? "";
-    }
-    return out;
+        return [env.name, env.value ?? ""];
+    }));
 }
 /** Appends envs to a sandbox's env file: they win over the ones it has. */
 export async function appendEnvs(runtime, envs) {

package/dist/cli.d.ts

@@ -7,6 +7,8 @@ type Out = {
     json: boolean;
     write: (text: string) => void;
     error: (text: string) => void;
+    /** Wait when an output pipe cannot accept another page yet. */
+    drain?: () => Promise<void>;
 };
 type Args = {
     positional: string[];