withruntime 0.9.0 → 0.10.0

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
+import { once } from "node:events";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { connectionOrigins, connectionStore, resolveCredential } from "./credentials.js";
+import { checkBrowserOrigins, connectionOrigins, connectionStore, resolveCredential, } from "./credentials.js";
 import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
 import { Sandbox as SandboxHandle } from "./sandbox.js";
@@ -36,6 +37,8 @@ Account
   sso                                          Single sign-on and SCIM directory sync (owner or
                                                admin keys); an owner changes it on the website
   usage [--csv]                                Balance, trial time and charges; --csv, each resource
+  usage export --since <UTC time> --until <UTC time>
+                                               Every settlement in the range as CSV; --json, each page
   limits                                       Whether this key is read-only, and its daily spending limit
   secrets set <NAME> --host <host>... [--header <name> [--format '<text {value}>']]
             [--allow '[GET,HEAD] /path/*']...  Store a secret sandboxes use without seeing it; the
@@ -180,8 +183,8 @@ const SANDBOX_HELP = `runtime sandbox <command>
 
 Examples
   id=$(runtime sandbox create)
-  runtime sandbox exec $id -- python3 -c 'print(6*7)'
-  runtime sandbox cp ./project $id:/workspace/project
+  runtime sandbox cp ./invoice.py $id:/workspace/invoice.py
+  runtime sandbox exec $id -- python3 /workspace/invoice.py
   runtime sandbox stop $id
 `;
 /** A command's options. Reading one its parse() did not declare is a bug in
@@ -229,9 +232,13 @@ commandAfter) {
                 throw commandAfter && !meantOption(name, known)
                     ? usage(`Unknown option ${arg.split("=")[0]}. If it belongs to the command, put the command after --: ${commandAfter}`)
                     : unknownOption(name, known);
-            const value = inline ?? (booleans.includes(name) ? "true" : argv[++i]);
-            if (value === undefined)
+            const boolean = booleans.includes(name);
+            const value = inline ?? (boolean ? "true" : argv[++i]);
+            if (value === undefined ||
+                (!boolean && inline === undefined && (value === "--" || /^--?[^\d]/.test(value))))
                 throw usage(`--${name} needs a value.`);
+            if (boolean && value !== "true" && value !== "false")
+                throw usage(`--${name} takes true or false.`);
             flags.set(name, [...(flags.get(name) ?? []), value]);
         }
         else
@@ -263,7 +270,10 @@ const integer = (args, name) => {
         return undefined;
     if (!/^\d+$/.test(value))
         throw usage(`--${name} must be a whole number.`);
-    return Number(value);
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        throw usage(`--${name} is too large to represent exactly.`);
+    return parsed;
 };
 /** A flag that takes one of a few words, checked before anything is sent. */
 function oneOf(args, name, choices) {
@@ -575,8 +585,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             ? JSON.stringify({ connected, usage: HELP })
             : `Runtime Cloud ${VERSION}. ${start}
 
-  ${me} sandbox run -- python3 -c 'print(6*7)'
-                                   A fresh sandbox runs one command, then stops
+  ${me} sandbox run -- python3 < invoice.py
+                                   Run a local invoice script, then stop the sandbox
   ${me} sandbox create                   A sandbox that stays; prints its id
   ${me} sandbox exec <id> -- <command>   Run in it
   ${me} help                             Everything else
@@ -588,10 +598,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "run") {
-        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandbox run -- python3 -c 'print(6*7)'`);
+        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandbox run -- python3 < invoice.py`);
         const commandLine = args.rest ?? args.positional;
         if (!commandLine.length)
-            throw usage(`Give the command after --: ${me} sandbox run -- python3 -c 'print(6*7)'`);
+            throw usage(`Give the command after --: ${me} sandbox run -- python3 < invoice.py`);
         const runtime = await client(env);
         const timeout = integer(args, "timeout");
         const { timeoutSeconds: _lease, ...input } = createInput(args);
@@ -688,6 +698,40 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "usage") {
+        if (rest[0] === "export") {
+            const args = parse(rest.slice(1), [], ["since", "until"]);
+            if (args.positional.length || args.rest)
+                throw usage(`Use ${me} usage export --since <UTC time> --until <UTC time>.`);
+            const since = need(flag(args, "since"), "--since <UTC time>, such as 2026-09-01T00:00:00Z");
+            const until = need(flag(args, "until"), "--until <UTC time>, such as 2026-10-01T00:00:00Z");
+            const rt = await client(env);
+            const cursors = new Set();
+            let cursor;
+            for (;;) {
+                const page = await rt.usageExport({
+                    since,
+                    until,
+                    ...(cursor ? { cursor } : {}),
+                    limit: 500,
+                });
+                if (page.nextCursor !== null && cursors.has(page.nextCursor))
+                    throw new RuntimeError({
+                        code: "usage_export_incomplete",
+                        status: 0,
+                        message: "The usage export repeated a page cursor and could not finish.",
+                        hint: "Run the export again; do not treat the partial output as complete.",
+                    });
+                if (out.json)
+                    out.write(JSON.stringify(page));
+                else if (page.csv)
+                    out.write(page.csv);
+                await out.drain?.();
+                if (page.nextCursor === null)
+                    return 0;
+                cursors.add(page.nextCursor);
+                cursor = page.nextCursor;
+            }
+        }
         const csv = rest.includes("--csv");
         const unknown = rest.find((arg) => arg !== "--csv");
         if (unknown)
@@ -738,7 +782,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         const page = await rt.events.list({
             ...(sandbox ? { resourceId: await sandboxIdOf(rt, sandbox) } : {}),
             ...(flag(args, "type") ? { type: flag(args, "type") } : {}),
-            ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+            ...(integer(args, "limit") !== undefined ? { limit: integer(args, "limit") } : {}),
         });
         print(page.data.length
             ? table(page.data.map((e) => {
@@ -783,7 +827,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
                 throw usage(`Unknown option --${name}.`);
         const page = await (await client(env)).audit.list({
             ...(flag(args, "action") ? { action: flag(args, "action") } : {}),
-            ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+            ...(integer(args, "limit") !== undefined ? { limit: integer(args, "limit") } : {}),
             ...(flag(args, "before") ? { before: flag(args, "before") } : {}),
         });
         print(page.events.length
@@ -809,17 +853,26 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         const origins = connectionOrigins(env);
         const { claimWalletAccount, openWalletAccount } = await import("./wallet.js");
         return billingCommand(rest, parse(rest, ["wait", "new-account", "accept-terms"], []), out, () => client(env), undefined, {
-            open: (input) => openWalletAccount(input, { authUrl: origins.auth }),
-            claim: (code) => claimWalletAccount(code, { authUrl: origins.auth }),
-            save: (key, orgId) => connectionStore(env).save({
-                version: 1,
-                apiOrigin: origins.api,
-                authOrigin: origins.auth,
-                key,
-                connectionId: "pasted",
-                orgId,
-                agentName: "Wallet agent",
-            }),
+            open: (input) => {
+                checkBrowserOrigins(origins);
+                return openWalletAccount(input, { authUrl: origins.auth });
+            },
+            claim: (code) => {
+                checkBrowserOrigins(origins);
+                return claimWalletAccount(code, { authUrl: origins.auth });
+            },
+            save: (key, orgId) => {
+                checkBrowserOrigins(origins);
+                return connectionStore(env).save({
+                    version: 1,
+                    apiOrigin: origins.api,
+                    authOrigin: origins.auth,
+                    key,
+                    connectionId: "pasted",
+                    orgId,
+                    agentName: "Wallet agent",
+                });
+            },
         });
     }
     if (command === "referrals") {
@@ -1536,7 +1589,9 @@ async function sandbox(argv, env, out) {
             const sbx = await get(args.positional[0]);
             const snapshot = await sbx.snapshot({
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
-                ...(integer(args, "retention") ? { retentionDays: integer(args, "retention") } : {}),
+                ...(integer(args, "retention") !== undefined
+                    ? { retentionDays: integer(args, "retention") }
+                    : {}),
             });
             print(snapshot.id, snapshot);
             return 0;
@@ -1596,7 +1651,7 @@ async function sandbox(argv, env, out) {
                 ...(cost === undefined
                     ? {}
                     : {
-                        maxTotalCostMicros: cost === "none" ? null : Math.round(Number(cost) * 1e6),
+                        maxTotalCostMicros: cost === "none" ? null : usdMicros(args, "max-total-cost"),
                     }),
             };
             if (!Object.keys(settings).length)
@@ -1709,7 +1764,7 @@ async function sandbox(argv, env, out) {
             const args = parse(rest, [], ["depth", "glob"]);
             const sbx = await use(args.positional[0]);
             const entries = await sbx.files.list(args.positional[1] ?? "/workspace", {
-                ...(integer(args, "depth") ? { depth: integer(args, "depth") } : {}),
+                ...(integer(args, "depth") !== undefined ? { depth: integer(args, "depth") } : {}),
                 ...(flag(args, "glob") ? { glob: flag(args, "glob") } : {}),
             });
             print(entries
@@ -1752,7 +1807,7 @@ async function sandbox(argv, env, out) {
             const sbx = await use(args.positional[0]);
             const preview = await sbx.previews.create(port, {
                 ...(has(args, "public") ? { visibility: "public" } : {}),
-                ...(integer(args, "ttl") ? { ttlSeconds: integer(args, "ttl") } : {}),
+                ...(integer(args, "ttl") !== undefined ? { ttlSeconds: integer(args, "ttl") } : {}),
             });
             // The link and how to use it, nothing more: the API's `hint` (which
             // carries a referral line) stays in --json, not in the command's words.
@@ -2084,7 +2139,7 @@ async function runCode(sbx, argv, out) {
     const execution = await sbx.interpreter.run(code, {
         language,
         ...(flag(args, "context") ? { context: flag(args, "context") } : {}),
-        ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+        ...(timeout !== undefined ? { timeoutMs: timeout * 1000 } : {}),
         ...(out.json
             ? {}
             : {
@@ -2133,8 +2188,8 @@ async function desktop(sbx, argv, out) {
         case "start": {
             const args = parse(rest, [], ["width", "height"]);
             const started = await d.start({
-                ...(integer(args, "width") ? { width: integer(args, "width") } : {}),
-                ...(integer(args, "height") ? { height: integer(args, "height") } : {}),
+                ...(integer(args, "width") !== undefined ? { width: integer(args, "width") } : {}),
+                ...(integer(args, "height") !== undefined ? { height: integer(args, "height") } : {}),
             });
             print(`Desktop ${started.size} on ${started.display}. Watch it: ${started.streamUrl}`, started);
             return 0;
@@ -2473,9 +2528,13 @@ read = readSecret) {
             if (sources.filter((s) => s !== undefined).length !== 1)
                 throw usage("Give exactly one of a folder with a Dockerfile (or -f <Dockerfile>), --from <image>, or --pip/--apt/--npm.");
             const build = {
-                ...(integer(args, "max-image-mib") ? { maxImageMiB: integer(args, "max-image-mib") } : {}),
-                ...(integer(args, "disk-mib") ? { diskMiB: integer(args, "disk-mib") } : {}),
-                ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+                ...(integer(args, "max-image-mib") !== undefined
+                    ? { maxImageMiB: integer(args, "max-image-mib") }
+                    : {}),
+                ...(integer(args, "disk-mib") !== undefined ? { diskMiB: integer(args, "disk-mib") } : {}),
+                ...(integer(args, "timeout") !== undefined
+                    ? { timeoutSeconds: integer(args, "timeout") }
+                    : {}),
             };
             // -t app, -t app:v2 -t app:latest: one name, its tags.
             let name = flag(args, "name");
@@ -2492,9 +2551,11 @@ read = readSecret) {
             }
             const start = {
                 ...(flag(args, "start") ? { command: flag(args, "start") } : {}),
-                ...(integer(args, "ready-port") ? { readyPort: integer(args, "ready-port") } : {}),
+                ...(integer(args, "ready-port") !== undefined
+                    ? { readyPort: integer(args, "ready-port") }
+                    : {}),
                 ...(flag(args, "ready-command") ? { readyCommand: flag(args, "ready-command") } : {}),
-                ...(integer(args, "ready-timeout")
+                ...(integer(args, "ready-timeout") !== undefined
                     ? { readyTimeoutSeconds: integer(args, "ready-timeout") }
                     : {}),
             };
@@ -2758,23 +2819,29 @@ async function jobCommand(argv, env, out) {
                     ? { cron, ...(flag(args, "timezone") ? { timezone: flag(args, "timezone") } : {}) }
                     : { at: atTime(at) },
                 command: cwd ? { argv, cwd } : argv,
-                ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+                ...(integer(args, "timeout") !== undefined
+                    ? { timeoutSeconds: integer(args, "timeout") }
+                    : {}),
                 compute: {
-                    ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
-                    ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
-                    ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+                    ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
+                    ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+                    ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
                     ...(flag(args, "cpu")
                         ? { cpuMode: oneOf(args, "cpu", ["shared", "reserved"]) }
                         : {}),
-                    ...(integer(args, "cpu-floor") ? { cpuFloorMillis: integer(args, "cpu-floor") } : {}),
+                    ...(integer(args, "cpu-floor") !== undefined
+                        ? { cpuFloorMillis: integer(args, "cpu-floor") }
+                        : {}),
                     ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
-                    ...(usdMicros(args, "max-cost") ? { maxCostMicros: usdMicros(args, "max-cost") } : {}),
+                    ...(usdMicros(args, "max-cost") !== undefined
+                        ? { maxCostMicros: usdMicros(args, "max-cost") }
+                        : {}),
                 },
                 ...(attempts !== undefined
                     ? { retry: { maxAttempts: attempts, backoffSeconds: backoff ?? 30 } }
                     : {}),
                 ...(secrets ? { secrets } : {}),
-                ...(usdMicros(args, "max-total-cost")
+                ...(usdMicros(args, "max-total-cost") !== undefined
                     ? { maxTotalCostMicros: usdMicros(args, "max-total-cost") }
                     : {}),
             });
@@ -2903,9 +2970,13 @@ async function jobCommand(argv, env, out) {
 }
 const VOLUME_HELP = `runtime volume <command>
 
-  create --size-mib <N> [--name n]            A persistent ext4 disk; prints its id
+  create --size-mib <N> [--name n] [--shared]  A persistent disk; prints its id
   ls                                          Your volumes
   get <id>                                    One volume, its backups and where it is attached
+  resize <id> --size-mib <N>                  Grow a detached volume on its current host
+  attach <id> <sandboxId> --path /data        Mount a shared disk in a running sandbox
+  detach <id> <attachmentId>                 Flush and unmount its shared attachment
+  attachment <id> <attachmentId>             Read the attachment's state and error
   rm <id>                                     Delete it and everything on it (its backups stay)
   backup <id> [--retention-days N] [--no-wait]
                                               Back it up now, off its host; prints the backup id
@@ -2916,6 +2987,7 @@ const VOLUME_HELP = `runtime volume <command>
                                               Daily backups on or off, and how long each is kept
   Attach one: runtime sandbox create --volume <id>:/data
   Volumes are backed up off their host daily unless you turn it off.
+  Shared commands work where shared disks are enabled.
 `;
 async function volume(argv, env, out) {
     const [verb, ...rest] = argv;
@@ -2927,10 +2999,11 @@ async function volume(argv, env, out) {
     const api = (await client(env)).volumes;
     switch (verb) {
         case "create": {
-            const args = parse(rest, [], ["size-mib", "name"]);
+            const args = parse(rest, ["shared"], ["size-mib", "name"]);
             const created = await api.create({
                 sizeMiB: integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>")),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(has(args, "shared") ? { shared: true } : {}),
             });
             print(created.id, created);
             return 0;
@@ -2958,6 +3031,40 @@ async function volume(argv, env, out) {
             print(describeRecord(found, table), found);
             return 0;
         }
+        case "resize": {
+            const args = parse(rest, [], ["size-mib"]);
+            const id = need(args.positional[0], "a volume id");
+            if (args.positional.length !== 1 || args.rest)
+                throw usage(`Use ${me} volume resize <id> --size-mib <N>.`);
+            const sizeMiB = integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>"));
+            const resized = await api.resize(id, { sizeMiB });
+            print(describeRecord(resized, table), resized);
+            return resized.resize?.state === "failed" ? 1 : 0;
+        }
+        case "attach": {
+            const args = parse(rest, [], ["path"]);
+            const id = need(args.positional[0], "a volume id");
+            const sandboxId = need(args.positional[1], "a sandbox id");
+            const path = need(flag(args, "path"), "--path /data");
+            if (args.positional.length !== 2 || args.rest)
+                throw usage(`Use ${me} volume attach <id> <sandboxId> --path /data.`);
+            const attachment = await api.attach(id, { sandboxId, path });
+            print(describeRecord(attachment, table), attachment);
+            return attachment.error ? 1 : 0;
+        }
+        case "detach":
+        case "attachment": {
+            const args = parse(rest, [], []);
+            const id = need(args.positional[0], "a volume id");
+            const attachmentId = need(args.positional[1], "an attachment id");
+            if (args.positional.length !== 2 || args.rest)
+                throw usage(`Use ${me} volume ${verb} <id> <attachmentId>.`);
+            const attachment = verb === "detach"
+                ? await api.detach(id, attachmentId)
+                : await api.getAttachment(id, attachmentId);
+            print(describeRecord(attachment, table), attachment);
+            return verb === "detach" && attachment.error ? 1 : 0;
+        }
         case "rm":
         case "delete": {
             const found = await api.delete(need(rest[0], "a volume id"));
@@ -3029,6 +3136,10 @@ async function volume(argv, env, out) {
         "create",
         "ls",
         "get",
+        "resize",
+        "attach",
+        "detach",
+        "attachment",
         "rm",
         "backup",
         "backups",
@@ -3089,7 +3200,13 @@ function usdMicros(args, name) {
         return undefined;
     if (!/^\d+(\.\d{1,6})?$/.test(value))
         throw usage(`--${name} takes dollars, such as 25 or 2.50.`);
-    return Math.round(Number(value) * 1e6);
+    // ARCHITECTURE.md section 10: integer microdollars throughout, with no
+    // floating-point money path or rounding drift.
+    const [whole, fraction = ""] = value.split(".");
+    const micros = BigInt(whole) * 1000000n + BigInt(fraction.padEnd(6, "0"));
+    if (micros > BigInt(Number.MAX_SAFE_INTEGER))
+        throw usage(`--${name} is too large to represent exactly in microdollars.`);
+    return Number(micros);
 }
 /** A create body from the command line's flags. */
 function createInput(args) {
@@ -3109,17 +3226,23 @@ function createInput(args) {
         ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
         ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
         ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
-        ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
-        ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
-        ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+        ...(integer(args, "vcpu") !== undefined ? { vcpu: integer(args, "vcpu") } : {}),
+        ...(integer(args, "memory") !== undefined ? { memoryMiB: integer(args, "memory") } : {}),
+        ...(integer(args, "disk") !== undefined ? { diskMiB: integer(args, "disk") } : {}),
         ...(flag(args, "cpu") ? { cpu: oneOf(args, "cpu", ["shared", "reserved"]) } : {}),
-        ...(integer(args, "cpu-floor") ? { cpuFloorMillis: integer(args, "cpu-floor") } : {}),
+        ...(integer(args, "cpu-floor") !== undefined
+            ? { cpuFloorMillis: integer(args, "cpu-floor") }
+            : {}),
         ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
-        ...(usdMicros(args, "max-cost") ? { maxCostMicros: usdMicros(args, "max-cost") } : {}),
-        ...(usdMicros(args, "max-total-cost")
+        ...(usdMicros(args, "max-cost") !== undefined
+            ? { maxCostMicros: usdMicros(args, "max-cost") }
+            : {}),
+        ...(usdMicros(args, "max-total-cost") !== undefined
             ? { maxTotalCostMicros: usdMicros(args, "max-total-cost") }
             : {}),
-        ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+        ...(integer(args, "timeout") !== undefined
+            ? { timeoutSeconds: integer(args, "timeout") }
+            : {}),
         ...(flag(args, "on-timeout")
             ? { onLeaseEnd: oneOf(args, "on-timeout", ["pause", "stop"]) }
             : {}),
@@ -3149,7 +3272,7 @@ ownInterrupt = true) {
         ...(stdin ? { stdin } : {}),
         ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
         ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
-        ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+        ...(timeout !== undefined ? { timeoutMs: timeout * 1000 } : {}),
     };
     // Ctrl-C stops the command in the sandbox too, and says so; without this
     // the CLI exited and the command ran on unseen.
@@ -3222,6 +3345,10 @@ function defaultOut(argv) {
     return {
         json,
         write: (text) => process.stdout.write(text.endsWith("\n") ? text : `${text}\n`),
+        drain: async () => {
+            if (process.stdout.writableNeedDrain)
+                await once(process.stdout, "drain");
+        },
         error: (text) => process.stderr.write(`${text}\n`),
     };
 }
@@ -3279,6 +3406,10 @@ function spark(values) {
 }
 const mib = (bytes) => `${Math.round(bytes / 1_048_576).toLocaleString("en-US")} MiB`;
 function metricsText(m) {
+    const waiting = (value) => value == null ? "not measured" : `${value}%`;
+    const waitingHistory = (field) => m.points.some((point) => point[field] != null)
+        ? spark(m.points.map((point) => point[field] ?? null))
+        : "not measured";
     const cpu = m.points.map((p) => p.cpuPercent);
     const memory = m.points.map((p) => p.memoryBytes);
     const peak = Math.max(0, ...m.points.map((p) => p.cpuPeakPercent ?? p.cpuPercent ?? 0));
@@ -3302,7 +3433,11 @@ function metricsText(m) {
                 "memory now",
                 still ?? (latest ? `${mib(latest.memoryBytes)} of ${mib(m.memoryLimitBytes)}` : "-"),
             ],
+            ["cpu wait now", still ?? waiting(latest?.cpuWaitPercent)],
+            ["memory stalls now", still ?? waiting(latest?.memoryStallPercent)],
             [`cpu, ${m.range}`, m.points.length ? `${spark(cpu)}  peak ${peak}%` : "no readings"],
+            [`cpu wait, ${m.range}`, waitingHistory("cpuWaitPercent")],
+            [`memory stalls, ${m.range}`, waitingHistory("memoryStallPercent")],
             [
                 `memory, ${m.range}`,
                 m.points.length
@@ -3397,7 +3532,7 @@ async function webhooksCommand(argv, env, out) {
         }
         case "deliveries": {
             const page = await hooks.deliveries(id(), {
-                ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+                ...(integer(args, "limit") !== undefined ? { limit: integer(args, "limit") } : {}),
             });
             print(page.data.length
                 ? table(page.data.map((d) => [

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { RuntimeError } from "./errors.js";
 import type { Page } from "./page.js";
 import { type ClientExtensions } from "./products/index.js";
+import { usageExport as makeUsageExport } from "./products/observability.js";
 import { Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, type RequestOptions } from "./transport.js";
@@ -11,7 +12,7 @@ export type RuntimeOptions = {
     /** Default: RUNTIME_API_URL, then https://api.withruntime.com. */
     baseUrl?: string;
     fetch?: typeof fetch;
-    /** Per call, retries included. Default 5 minutes. */
+    /** Per call, queue and retries included. Default 5 minutes; 0 disables it. */
     timeoutMs?: number;
     /** Retries of transport failures, 429, 502, 503 and 504. Default 4. */
     maxRetries?: number;
@@ -30,11 +31,16 @@ export interface Runtime extends ClientExtensions {
 }
 export declare class Runtime {
     readonly transport: Transport;
+    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
+    readonly sandbox: Sandboxes;
     readonly sandboxes: Sandboxes;
+    readonly snapshot: Snapshots;
     readonly snapshots: Snapshots;
     readonly feedback: FeedbackApi;
     readonly support: SupportApi;
     readonly account: AccountApi;
+    /** Date-range settlements, paged with exact charges and the server's CSV. */
+    readonly usageExport: ReturnType<typeof makeUsageExport>;
     constructor(options?: RuntimeOptions);
     /** Who this key is: organization, agent and credential. */
     me(options?: RequestOptions): Promise<{
@@ -50,6 +56,25 @@ export declare class Runtime {
     /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
     /** Credit, holds, trial time and per-resource charges. */
     usage(options?: RequestOptions): Promise<Usage>;
+    /** This account's authenticated API answers, in hourly windows. Counts are
+     * exact decimal strings, and an empty window has a null error percentage.
+     * A key needs usage permission. */
+    usageRequests(range?: "24h" | "7d" | "30d" | "90d", options?: RequestOptions): Promise<{
+        range: "24h" | "7d" | "30d" | "90d";
+        since: string;
+        until: string;
+        calls: string;
+        clientErrors: string;
+        serverErrors: string;
+        errorPercent: number | null;
+        operations: Array<{
+            operation: string;
+            calls: string;
+            clientErrors: string;
+            serverErrors: string;
+            errorPercent: number | null;
+        }>;
+    }>;
 }
 /** How `sandboxes.create` waits when every trial slot, the account's quota or
  * the region is full. */
@@ -83,7 +108,8 @@ export declare class Sandboxes {
     /** Deletes a sandbox for good, by id, without reading it first: see
      * `sandbox.delete()`. Deleting it again answers the same. */
     delete(id: string, options?: RequestOptions): Promise<DeletedSandbox>;
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
+    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
+     * Request options apply to the initial request and every subsequent page. */
     list(filter?: {
         state?: SandboxInfo["state"][];
         includeStopped?: boolean;
@@ -91,7 +117,7 @@ export declare class Sandboxes {
         labels?: Record<string, string>;
         name?: string;
         limit?: number;
-    }): Promise<Page<Sandbox>>;
+    }, options?: RequestOptions): Promise<Page<Sandbox>>;
 }
 export declare class FeedbackApi {
     private readonly t;