withruntime 0.33.3 → 0.34.0

package/dist/apps-cli.js

@@ -13,11 +13,17 @@ export const APP_HELP = `runtime apps <command>
   create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>
          [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]
          [--health-path /healthz] [--health-fail 60] [--stop-grace 30] [--cdn on|off]
-         [--volume <volumeId>:<path>] [--label key=value]...
+         [--release at-once|staged] [--soak 300] [--volume <volumeId>:<path>] [--label key=value]...
                                               Make an App, waiting for its first deploy; prints its id.
                                               --health-fail: seconds a live copy may fail its health
                                               check before it is replaced. --stop-grace: seconds a
-                                              stopped copy has after SIGTERM. --volume mounts one
+                                              stopped copy has after SIGTERM. --release staged: a new
+                                              version goes live on one copy, then about 10%, 50% and
+                                              all of them, each stage running --soak seconds (60 to
+                                              3600) and judged on its visitors' errors and speed
+                                              before the next; a stage that does worse goes back and
+                                              the deploy fails, the live version never stopping.
+                                              --volume mounts one
                                               volume of yours at a path under /data, /mnt, /state,
                                               /storage or /volumes, in the App's one copy: it needs
                                               --max-copies 1 (--min-copies is then 1, --spares 0), and
@@ -27,7 +33,7 @@ export const APP_HELP = `runtime apps <command>
   update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]
          [--concurrency n] [--spares n] [--port n] [--health-path /path] [--health-fail n]
          [--stop-grace n] [--volume <volumeId>:<path> | none] [--cdn on|off]
-         [--label key=value]...
+         [--release at-once|staged] [--soak n] [--label key=value]...
                                               Change its settings; --volume none takes the volume
                                               away, only before its first deploy;
                                               --cdn off sends visitors straight to Runtime's routers,
@@ -224,6 +230,19 @@ function onOff(value, kit) {
         return false;
     throw kit.usage(`--cdn takes on or off, not ${value}.`);
 }
+/** --release at-once|staged and --soak <seconds>: how an App's new version
+ * goes live. */
+function releases(args, kit) {
+    const given = kit.flag(args, "release");
+    const soak = kit.integer(args, "soak");
+    const stages = given?.replace("-", "_");
+    if (stages !== undefined && stages !== "at_once" && stages !== "staged")
+        throw kit.usage(`--release takes at-once or staged, not ${given}.`);
+    return {
+        ...(stages === undefined ? {} : { releaseStages: stages }),
+        ...(soak === undefined ? {} : { releaseSoakSeconds: soak }),
+    };
+}
 /** --volume <volumeId>:<path>, or none (an update's: no volume). */
 function volume(args, kit) {
     const given = kit.flag(args, "volume");
@@ -239,8 +258,8 @@ function volume(args, kit) {
     return { volume: { volumeId, path } };
 }
 /** The flags an App's settings are given with, as the API names them. A
- * Function's leave out --min-copies, --stop-grace and --volume, which its
- * parse does not take. */
+ * Function's leave out --min-copies, --stop-grace, --volume, --release and
+ * --soak, which its parse does not take. */
 function settings(args, kit, kind) {
     const { integer, flag } = kit;
     const number = (name, field) => integer(args, name) === undefined ? {} : { [field]: integer(args, name) };
@@ -256,7 +275,11 @@ function settings(args, kit, kind) {
         ...(flag(args, "cdn") === undefined ? {} : { cdn: onOff(flag(args, "cdn"), kit) }),
         ...number("health-fail", "healthFailSeconds"),
         ...(kind.minCopies
-            ? { ...number("stop-grace", "stopGraceSeconds"), ...volume(args, kit) }
+            ? {
+                ...number("stop-grace", "stopGraceSeconds"),
+                ...volume(args, kit),
+                ...releases(args, kit),
+            }
             : {}),
     };
 }
@@ -273,11 +296,13 @@ const SETTINGS = [
     "health-fail",
     "stop-grace",
     "volume",
+    "release",
+    "soak",
     "label",
 ];
 const settingsOf = (kind) => kind.minCopies
     ? SETTINGS
-    : SETTINGS.filter((name) => !["min-copies", "stop-grace", "volume"].includes(name));
+    : SETTINGS.filter((name) => !["min-copies", "stop-grace", "volume", "release", "soak"].includes(name));
 /** A version's copies replaced while live: how many, and why. */
 function replaced(list) {
     if (!list?.length)
@@ -418,9 +443,16 @@ async function copiesCommand(kind, argv, env, out, client, kit) {
                 ...(healthPath === undefined ? {} : { healthPath }),
                 wait,
             };
+            // A staged App's deploy walks up to four stages, each soaking.
+            const app = wait && kind.minCopies ? await api.get(id) : undefined;
+            const staged = app && "releaseStages" in app && app.releaseStages === "staged" ? app : undefined;
             if (wait && !out.json)
-                out.error(`Deploying ${args.positional[0]}...`);
-            const deploy = await api.deploy(id, input, { timeoutMs: 15 * 60_000 });
+                out.error(staged
+                    ? `Deploying ${args.positional[0]} in stages, each soaking ${staged.releaseSoakSeconds} s...`
+                    : `Deploying ${args.positional[0]}...`);
+            const deploy = await api.deploy(id, input, {
+                timeoutMs: 15 * 60_000 + (staged ? 4 * staged.releaseSoakSeconds * 1000 : 0),
+            });
             const failed = deployFailure(deploy);
             if (failed && !out.json)
                 throw failed;

package/dist/browsers/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/browsers`: Browsers alone. Chromium on its own sandbox, with a private CDP address and screenshots, at the sandbox rates. In a private beta.
+ *
+ *   import { browsers } from "withruntime/browsers";
+ *   const client = browsers(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/browsers.js";
+/** `runtime.browsers` of a client made with `options`. */
+export declare function browsers(options?: RuntimeOptions): Runtime["browsers"];

package/dist/browsers/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/browsers`: Browsers alone. Chromium on its own sandbox, with a private CDP address and screenshots, at the sandbox rates. In a private beta.
+ *
+ *   import { browsers } from "withruntime/browsers";
+ *   const client = browsers(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.browsers` of a client made with `options`. */
+export function browsers(options) {
+    return new Runtime(options).browsers;
+}

package/dist/browsers-cli.d.ts

@@ -0,0 +1,13 @@
+import type { CliKit } from "./cli.js";
+import type { Runtime } from "./client.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare const BROWSER_HELP = "runtime browsers <command>\n\n  A browser is Chromium on its own sandbox, billed at the sandbox rates, with a\n  private CDP address for Playwright, Puppeteer, browser-use or Stagehand.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [--memory <1024-16384>] [--vcpu <1-16>] [--visible] [--width <px>] [--height <px>]\n         [--timeout <seconds>] [--name <name>] [--label key=value]...\n                                              Start one; prints its id, then its cdpUrl\n  ls                                          Your browsers\n  get <browser>                               One browser, with a fresh cdpUrl (an id or its name)\n  screenshot <browser> [<url>] [--out <file.png>] [--full] [--jpeg] [--wait <ms>]\n                                              Open url in a new tab and save its screenshot\n                                              (without url: what it shows now)\n  rm <browser>                                Delete it and its sandbox\n\nExamples\n  runtime browsers create --name scraper\n  runtime browsers screenshot scraper https://withruntime.com --out home.png\n  runtime browsers rm scraper\n";
+export declare const DESKTOP_HELP = "runtime desktops <command>\n\n  A desktop is a Linux desktop on its own sandbox, billed at the sandbox rates,\n  with a private live view and computer use: screenshot, click, type, open.\n  In a private beta: outside it, each command says how to ask to join.\n\n  create [--memory <1024-16384>] [--vcpu <1-16>] [--width <px>] [--height <px>]\n         [--timeout <seconds>] [--name <name>] [--label key=value]...\n                                              Start one; prints its id, then its live view\n  ls                                          Your desktops\n  get <desktop>                               One desktop, with a fresh live view (an id or its name)\n  screenshot <desktop> [--out <file.png>]     Save its screen\n  open <desktop> <url>                        Open url in its Chromium\n  rm <desktop>                                Delete it and its sandbox\n\nExamples\n  runtime desktops create --name qa\n  runtime desktops open qa https://withruntime.com\n  runtime desktops screenshot qa --out screen.png\n";
+/** `runtime browsers` and `runtime desktops`: the five verbs, a screenshot
+ * saved to a file, and a desktop's open. */
+export declare function machineProductCommand(which: "browsers" | "desktops", argv: string[], out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
+export {};

package/dist/browsers-cli.js

@@ -0,0 +1,160 @@
+import { writeFileSync } from "node:fs";
+import { me, named } from "./cli-name.js";
+import { browsers } from "./products/browsers.js";
+import { desktops } from "./products/desktops.js";
+export const BROWSER_HELP = `runtime browsers <command>
+
+  A browser is Chromium on its own sandbox, billed at the sandbox rates, with a
+  private CDP address for Playwright, Puppeteer, browser-use or Stagehand.
+  In a private beta: outside it, each command says how to ask to join.
+
+  create [--memory <1024-16384>] [--vcpu <1-16>] [--visible] [--width <px>] [--height <px>]
+         [--timeout <seconds>] [--name <name>] [--label key=value]...
+                                              Start one; prints its id, then its cdpUrl
+  ls                                          Your browsers
+  get <browser>                               One browser, with a fresh cdpUrl (an id or its name)
+  screenshot <browser> [<url>] [--out <file.png>] [--full] [--jpeg] [--wait <ms>]
+                                              Open url in a new tab and save its screenshot
+                                              (without url: what it shows now)
+  rm <browser>                                Delete it and its sandbox
+
+Examples
+  runtime browsers create --name scraper
+  runtime browsers screenshot scraper https://withruntime.com --out home.png
+  runtime browsers rm scraper
+`;
+export const DESKTOP_HELP = `runtime desktops <command>
+
+  A desktop is a Linux desktop on its own sandbox, billed at the sandbox rates,
+  with a private live view and computer use: screenshot, click, type, open.
+  In a private beta: outside it, each command says how to ask to join.
+
+  create [--memory <1024-16384>] [--vcpu <1-16>] [--width <px>] [--height <px>]
+         [--timeout <seconds>] [--name <name>] [--label key=value]...
+                                              Start one; prints its id, then its live view
+  ls                                          Your desktops
+  get <desktop>                               One desktop, with a fresh live view (an id or its name)
+  screenshot <desktop> [--out <file.png>]     Save its screen
+  open <desktop> <url>                        Open url in its Chromium
+  rm <desktop>                                Delete it and its sandbox
+
+Examples
+  runtime desktops create --name qa
+  runtime desktops open qa https://withruntime.com
+  runtime desktops screenshot qa --out screen.png
+`;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `runtime browsers` and `runtime desktops`: the five verbs, a screenshot
+ * saved to a file, and a desktop's open. */
+export async function machineProductCommand(which, argv, out, client, kit) {
+    const { parse, flag, has, integer, need, pairs, table, usage } = kit;
+    const noun = which === "browsers" ? "browser" : "desktop";
+    const help = which === "browsers" ? BROWSER_HELP : DESKTOP_HELP;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(help), { usage: named(help) });
+        return 0;
+    }
+    const transport = (await client()).transport;
+    const api = which === "browsers" ? browsers(transport) : desktops(transport);
+    const idOf = async (target) => {
+        const given = need(target, `a ${noun}'s id or name`);
+        if (UUID.test(given))
+            return given;
+        const found = (await api.list({ name: given })).data;
+        if (found.length === 1)
+            return found[0].id;
+        throw usage(found.length
+            ? `${found.length} ${which} are named ${given}; give one's id (${me} ${which} ls).`
+            : `No ${noun} is named ${given}. Your ${which}: ${me} ${which} ls`);
+    };
+    const save = (file, bytes, value) => {
+        writeFileSync(file, bytes);
+        print(`Saved ${file} (${bytes.length} bytes).`, { ...value, file, base64: undefined });
+    };
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, ["visible"], ["memory", "vcpu", "width", "height", "timeout", "name", "label"]);
+            const input = {
+                ...(integer(args, "memory") === undefined ? {} : { memoryMiB: integer(args, "memory") }),
+                ...(integer(args, "vcpu") === undefined ? {} : { vcpu: integer(args, "vcpu") }),
+                ...(integer(args, "width") === undefined ? {} : { width: integer(args, "width") }),
+                ...(integer(args, "height") === undefined ? {} : { height: integer(args, "height") }),
+                ...(integer(args, "timeout") === undefined
+                    ? {}
+                    : { timeoutSeconds: integer(args, "timeout") }),
+                ...(flag(args, "name") === undefined ? {} : { name: flag(args, "name") }),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+                ...(which === "browsers" && has(args, "visible") ? { headless: false } : {}),
+            };
+            const made = (await api.create(input));
+            const reach = which === "browsers" ? made.cdpUrl : made.liveViewUrl;
+            print(`${String(made.id)}\n${typeof reach === "string" ? reach : ""}`, made);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const all = (await (await api.list({ limit: 100 })).toArray(Infinity));
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "SIZE", "SANDBOX"],
+                    ...all.map((item) => [
+                        String(item.id),
+                        typeof item.name === "string" ? item.name : "-",
+                        String(item.state),
+                        `${String(item.vcpu)} vCPU, ${String(item.memoryMiB)} MiB`,
+                        String(item.sandboxId),
+                    ]),
+                ])
+                : `No ${which}. Start one: ${me} ${which} create`, all);
+            return 0;
+        }
+        case "get": {
+            const found = await api.get(await idOf(rest[0]));
+            print(JSON.stringify(found, null, 2), found);
+            return 0;
+        }
+        case "screenshot":
+        case "shot": {
+            const args = parse(rest, ["full", "jpeg"], ["out", "wait"]);
+            const id = await idOf(args.positional[0]);
+            const jpeg = has(args, "jpeg");
+            const file = flag(args, "out") ?? `${noun}-${id.slice(0, 8)}.${jpeg ? "jpg" : "png"}`;
+            if (which === "desktops") {
+                const bytes = await desktops(transport).screenshot(id, jpeg ? { format: "jpeg" } : {});
+                save(file, bytes, { id });
+                return 0;
+            }
+            const url = args.positional[1];
+            const shot = await browsers(transport).screenshot(id, {
+                ...(url ? { url } : {}),
+                ...(has(args, "full") ? { fullPage: true } : {}),
+                ...(jpeg ? { format: "jpeg" } : {}),
+                ...(integer(args, "wait") === undefined ? {} : { waitMs: integer(args, "wait") }),
+            });
+            if (!out.json)
+                out.error(`${shot.url} (${shot.status ?? "-"}): ${shot.title}`);
+            save(file, Buffer.from(shot.base64, "base64"), shot);
+            return 0;
+        }
+        case "open": {
+            if (which !== "desktops")
+                break;
+            const id = await idOf(rest[0]);
+            const url = need(rest[1], "a URL to open");
+            const done = await desktops(transport).act(id, { action: "open", url });
+            print(`Opened ${url}.`, done);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const gone = await api.delete(await idOf(rest[0]));
+            print(`${String(rest[0])} deleted.`, gone ?? { deleted: true });
+            return 0;
+        }
+    }
+    throw kit.unknown(`${which} command`, verb, which === "browsers"
+        ? ["create", "ls", "get", "screenshot", "rm"]
+        : ["create", "ls", "get", "screenshot", "open", "rm"]);
+}

package/dist/ci-cli.d.ts

@@ -5,6 +5,6 @@ type Out = {
     write: (text: string) => void;
     error: (text: string) => void;
 };
-export declare const CI_HELP = "runtime ci <command>\n\n  CI/CD checks each push and pull request of a connected GitHub repository in\n  sandboxes, as the steps its config file names. A fork's pull request runs\n  nothing; a writer can open it again from a branch of the repository. In a\n  private beta: outside it, each command says how to ask to join.\n\n  import [dir] [--write] [--force]            This folder's GitHub Actions workflows and CircleCI\n                                              config as a runtime.yml: printed, or written with\n                                              --write; what isn't carried over is noted at its top.\n                                              Needs no key and sends nothing\n  connect <owner/name> [--branch main] [--config runtime.yml] [--installation <id>]\n          [--trust <app-slug>[bot]]... [--name <name>]\n                                              Connect a repository; prints its id. Takes a full key.\n                                              --trust runs that App's pushes as its own from the start\n  repos [ls] [--all]                          Connected repositories, with the Apps each trusts;\n                                              --all: disconnected ones too\n  repos trust <repoId | owner/name> <app-slug>[bot]...\n                                              Run that App's pushes as the repository's own code,\n                                              keeping the Apps it trusts already\n  repos untrust <repoId | owner/name> <app-slug>[bot]...\n                                              Stop trusting those Apps, keeping the rest\n  repos undo <repoId | owner/name> on|off     When main's check fails, find the first commit that\n                                              fails it and open a pull request reverting it, which\n                                              lands once its check passes. Off until turned on;\n                                              takes an owner's or admin's full key\n  disconnect <repoId | owner/name>            Stop checking it; its checks still going are cancelled\n  checks [--repository <repoId>] [--branch <name>] [--commit <sha>] [--pr <number>]\n     [--state <state>]... [--limit 20]        Checks, newest first, with their jobs by state (or ls)\n  check <checkId>                             One check and its jobs in plan order (or get)\n  cancel <checkId>                            Cancel a queued or running check: its jobs end,\n                                              its machines are let go, GitHub is told\n  logs <jobId>                                A job's output, its last 256 KiB, and its sandboxes\n  tests <repoId> [--quarantined]              Its test files: time, recent outcomes, quarantine\n  flakes [--repository <repoId>] [--all]      Flaky tests: each quarantined (or still gating), its\n                                              owner and 48-hour deadline; --all: ended ones too\n  flake <flakeId>                             One flaky test: its proof, owner, and recent runs\n  flake prove <flakeId>                       Its 100 proof runs again at main's next commit\n  flake hand <flakeId> <login | org/team>     Hand it to someone else\n  flake delete <flakeId> --reason <why>       Say why its test is deleted; it ends once main\n                                              no longer holds the file\n  releases [--repository <repoId>] [--commit <sha>] [--limit 50]\n                                              A release's steps as they were taken, oldest\n                                              first: migrations, deploys, servers, waits\n\n  A failed job's sandbox may be kept paused: `runtime sandboxes wake <id>`, then\n  `runtime sandboxes shell <id>` to look around where it failed. A key reads the\n  checks of repositories its own agent connected; an account-wide key reads and\n  cancels every check of the account (switch one at withruntime.com/account/keys).\n\nExamples\n  runtime ci import --write\n  runtime ci connect acme/web --config .runtime/ci.yml\n  runtime ci repos trust acme/web acme-bot[bot]\n  runtime ci repos undo acme/web on\n  runtime ci checks --commit $(git rev-parse HEAD)\n  runtime ci cancel <checkId>\n  runtime ci logs <jobId>\n";
+export declare const CI_HELP = "runtime ci <command>\n\n  CI/CD checks each push and pull request of a connected GitHub repository in\n  sandboxes, as the steps its config file names. A fork's pull request runs\n  nothing; a writer can open it again from a branch of the repository. In a\n  private beta: outside it, each command says how to ask to join.\n\n  import [dir] [--write] [--force]            This folder's GitHub Actions workflows and CircleCI\n                                              config as a runtime.yml: printed, or written with\n                                              --write; what isn't carried over is noted at its top.\n                                              Needs no key and sends nothing\n  connect <owner/name> [--branch main] [--config runtime.yml] [--installation <id>]\n          [--trust <app-slug>[bot]]... [--name <name>]\n                                              Connect a repository; prints its id. Takes a full key.\n                                              --trust runs that App's pushes as its own from the start\n  repos [ls] [--all]                          Connected repositories, with the Apps each trusts;\n                                              --all: disconnected ones too\n  repos trust <repoId | owner/name> <app-slug>[bot]...\n                                              Run that App's pushes as the repository's own code,\n                                              keeping the Apps it trusts already\n  repos untrust <repoId | owner/name> <app-slug>[bot]...\n                                              Stop trusting those Apps, keeping the rest\n  repos undo <repoId | owner/name> on|off     When main's check fails, find the first commit that\n                                              fails it and open a pull request reverting it, which\n                                              lands once its check passes. Off until turned on;\n                                              takes an owner's or admin's full key\n  disconnect <repoId | owner/name>            Stop checking it; its checks still going are cancelled\n  checks [--repository <repoId>] [--branch <name>] [--commit <sha>] [--pr <number>]\n     [--state <state>]... [--limit 20]        Checks, newest first, with their jobs by state (or ls)\n  check <checkId>                             One check and its jobs in plan order (or get)\n  cancel <checkId>                            Cancel a queued or running check: its jobs end,\n                                              its machines are let go, GitHub is told\n  rerun <checkId>                             Run a check again: a new check of its commit, a\n                                              pull request's as it would land now\n  logs <jobId>                                A job's output, its last 256 KiB, and its sandboxes\n  tests <repoId> [--quarantined]              Its test files: time, recent outcomes, quarantine\n  flakes [--repository <repoId>] [--all]      Flaky tests: each quarantined (or still gating), its\n                                              owner and 48-hour deadline; --all: ended ones too\n  flake <flakeId>                             One flaky test: its proof, owner, and recent runs\n  flake prove <flakeId>                       Its 100 proof runs again at main's next commit\n  flake hand <flakeId> <login | org/team>     Hand it to someone else\n  flake delete <flakeId> --reason <why>       Say why its test is deleted; it ends once main\n                                              no longer holds the file\n  releases [--repository <repoId>] [--commit <sha>] [--limit 50]\n                                              A release's steps as they were taken, oldest\n                                              first: migrations, deploys, servers, waits\n\n  A failed job's sandbox may be kept paused: `runtime sandboxes wake <id>`, then\n  `runtime sandboxes shell <id>` to look around where it failed. A key reads the\n  checks of repositories its own agent connected; an account-wide key reads and\n  cancels every check of the account (switch one at withruntime.com/account/keys).\n\nExamples\n  runtime ci import --write\n  runtime ci connect acme/web --config .runtime/ci.yml\n  runtime ci repos trust acme/web acme-bot[bot]\n  runtime ci repos undo acme/web on\n  runtime ci checks --commit $(git rev-parse HEAD)\n  runtime ci cancel <checkId>\n  runtime ci logs <jobId>\n";
 export declare function ciCommand(argv: string[], out: Out, client: () => Promise<Runtime>, kit: CliKit): Promise<number>;
 export {};

package/dist/ci-cli.js

@@ -35,6 +35,8 @@ export const CI_HELP = `runtime ci <command>
   check <checkId>                             One check and its jobs in plan order (or get)
   cancel <checkId>                            Cancel a queued or running check: its jobs end,
                                               its machines are let go, GitHub is told
+  rerun <checkId>                             Run a check again: a new check of its commit, a
+                                              pull request's as it would land now
   logs <jobId>                                A job's output, its last 256 KiB, and its sandboxes
   tests <repoId> [--quarantined]              Its test files: time, recent outcomes, quarantine
   flakes [--repository <repoId>] [--all]      Flaky tests: each quarantined (or still gating), its
@@ -310,6 +312,16 @@ export async function ciCommand(argv, out, client, kit) {
             print(`${check.repository} ${check.commit.slice(0, 12)} ${where(check)}: ${check.state}${check.reason ? ` (${check.reason})` : ""}`, check);
             return 0;
         }
+        case "rerun": {
+            const check = await api.checks.rerun(need(rest[0], "a check's id (runtime ci ls)"));
+            // A key that may run the check again but not read it is told the new one's id alone.
+            if (!("commit" in check)) {
+                print(`${check.id}: ${check.state}`, check);
+                return 0;
+            }
+            print(`${check.id} ${check.repository} ${check.commit.slice(0, 12)} ${where(check)}: ${check.state}${check.reason ? ` (${check.reason})` : ""}`, check);
+            return 0;
+        }
         case "logs":
         case "job": {
             const job = await api.jobs.get(need(rest[0], "a job's id (runtime ci get <checkId>)"));
@@ -440,6 +452,7 @@ export async function ciCommand(argv, out, client, kit) {
         "ls",
         "get",
         "cancel",
+        "rerun",
         "logs",
         "tests",
         "flakes",
@@ -447,15 +460,15 @@ export async function ciCommand(argv, out, client, kit) {
         "releases",
     ]);
 }
-/** A review's verdict in words: each finding with its place and fix, then
- * the notes, then who reviewed. */
+/** An agent step's verdict in words: each finding with its place and fix,
+ * then the notes, then who judged. */
 function reviewed(r) {
     const at = (f) => (f.line > 0 ? `${f.file}:${f.line}` : f.file);
     return [
         `\n${r.verdict === "pass" ? "Passed review" : `Blocked: ${r.findings.length} finding(s)`}. ${r.summary}`,
         ...r.findings.map((f) => `  ${f.kind} at ${at(f)}: ${f.what}\n    Fix: ${f.fix}`),
         ...r.notes.map((n) => `  note at ${at(n)}: ${n.what}`),
-        `Reviewed by agent ${r.agent} (${r.model}) on ${r.account}${r.cut ? ", diff cut short" : ""}: session ${r.session}`,
+        `Judged by agent ${r.agent}${r.model ? ` (${r.model})` : ""}${r.account ? ` on ${r.account}` : ""}${r.cut ? ", diff cut short" : ""}: session ${r.session}`,
         "",
     ].join("\n");
 }

package/dist/cli.d.ts

@@ -2,6 +2,7 @@
 import { type Sandbox } from "./sandbox.js";
 import { RuntimeError } from "./errors.js";
 import type { OutOfMemory, Usage } from "./types.js";
+import type { UsageExportPage } from "./products/observability.js";
 import type { SwitchProvider } from "./products/switching.js";
 import type { SecretRule, SecretScope } from "./products/secrets.js";
 type Out = {
@@ -38,6 +39,9 @@ declare const kit: {
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;
+/** `usage export`'s last word, on stderr beside the CSV: how much of the
+ * range can still change. */
+export declare function finalLine(page: Pick<UsageExportPage, "until" | "finalThrough">): string;
 /** `runtime usage` for a person: the balance, the free usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */

package/dist/cli.js

@@ -69,7 +69,9 @@ Account
                                                (job create --secret NAME); with --host, both
   secrets scope <NAME> --only-label k=v... | --only-sandbox <id>... | --only-app <id>... | --all-sandboxes
                                                Change which sandboxes get it; no value needed
-  secrets ls | get <NAME>                      Names, hosts, placeholders and jobs versions, never values
+  secrets ls [--limit N] [--after NAME] | get <NAME>
+                                               Names, hosts, placeholders and jobs versions, never values;
+                                               by name, a page of N after NAME
   secrets rotate <NAME>                        A new version of the jobs copy, from standard input
   secrets reveal <NAME> [--version N]          Print the jobs copy's value. The sandboxes' copy is
                                                never readable, by anyone
@@ -136,6 +138,8 @@ Products
   builds     A connected repository's commits built into what an App deploys (beta)
   ci         CI/CD: each push and pull request of a repository checked in sandboxes (beta)
   containers One OCI image's process on its own microVM, at the sandbox rates (beta)
+  browsers   Chromium on its own sandbox: a CDP address and screenshots (beta)
+  desktops   A Linux desktop on its own sandbox: live view, computer use (beta)
   agents     Claude Code, Codex, Gemini CLI or your own agent in a sandbox per session (beta)
   domains    Your own hostname for a sandbox's port, with HTTPS
   ports      A public TCP port to a sandbox: databases, game servers
@@ -476,6 +480,8 @@ const COMMANDS = [
     "builds",
     "ci",
     "containers",
+    "browsers",
+    "desktops",
     "agents",
     "domains",
     "ports",
@@ -500,6 +506,8 @@ const OWN_HELP = [
     "builds",
     "ci",
     "containers",
+    "browsers",
+    "desktops",
     "agents",
     "keys",
     "reservations",
@@ -872,6 +880,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             const rt = await client(env);
             const cursors = new Set();
             let cursor;
+            // The export is final only as far as its earliest page's finalThrough.
+            let finalThrough;
             for (;;) {
                 const page = await rt.usageExport({
                     since,
@@ -891,8 +901,19 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
                 else if (page.csv)
                     out.write(page.csv);
                 await out.drain?.();
-                if (page.nextCursor === null)
+                const at = page.finalThrough;
+                finalThrough =
+                    finalThrough === undefined
+                        ? at
+                        : finalThrough === null || at === null
+                            ? null
+                            : at < finalThrough
+                                ? at
+                                : finalThrough;
+                if (page.nextCursor === null) {
+                    out.error(finalLine({ until: page.until, finalThrough: finalThrough ?? null }));
                     return 0;
+                }
                 cursors.add(page.nextCursor);
                 cursor = page.nextCursor;
             }
@@ -1351,6 +1372,10 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         product = "containers";
         return (await import("./apps-cli.js")).containersCommand(rest, env, out, () => client(env), kit);
     }
+    if (["browser", "browsers", "desktop", "desktops"].includes(command)) {
+        product = command.endsWith("s") ? command : `${command}s`;
+        return (await import("./browsers-cli.js")).machineProductCommand(product, rest, out, () => client(env), kit);
+    }
     if (command === "agent" || command === "agents") {
         product = "agents";
         return (await import("./agents-cli.js")).agentsCommand(rest, env, out, () => client(env), kit);
@@ -1365,6 +1390,15 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     throw unknown("command", command, COMMANDS);
 }
+/** `usage export`'s last word, on stderr beside the CSV: how much of the
+ * range can still change. */
+export function finalLine(page) {
+    if (page.finalThrough === null)
+        return "Charges in this range may still settle; export it again later for a final copy.";
+    if (Date.parse(page.finalThrough) >= Date.parse(page.until))
+        return "Final: no more charges will settle in this range.";
+    return `Final up to ${page.finalThrough}; charges after that may still settle. Export again later for the rest.`;
+}
 /** `runtime usage` for a person: the balance, the free usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
@@ -2689,6 +2723,8 @@ read = readSecret) {
         "only-app",
         "agent",
         "env",
+        "limit",
+        "after",
     ]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const rows = (list) => list.length
@@ -2706,11 +2742,19 @@ read = readSecret) {
         ])
         : "No secrets.";
     if (verb === "ls" || verb === "list" || verb === undefined) {
+        const limit = integer(args, "limit");
+        if (limit !== undefined && (limit < 1 || limit > 100))
+            throw usage("--limit takes 1 to 100 secrets a page.");
+        const after = flag(args, "after");
         const runtime = await client(env);
-        const all = await runtime.secrets.all();
+        // A page of both copies by name, as the API pages each: an organization
+        // keeps at most 50 secrets for sandboxes, so both are read whole.
+        const every = (await runtime.secrets.all()).filter((s) => after === undefined || s.name > after);
+        const all = limit === undefined ? every : every.slice(0, limit);
+        const more = all.length < every.length ? all.at(-1).name : undefined;
         // --json keeps the sandboxes' list it always printed; the jobs copies
         // are in `runtime secrets get <NAME> --json`.
-        print(rows(all), all.flatMap((s) => (s.sandboxes ? [s.sandboxes] : [])));
+        print(more ? `${rows(all)}\nMore: ${me} secrets ls --limit ${limit} --after ${more}` : rows(all), all.flatMap((s) => (s.sandboxes ? [s.sandboxes] : [])));
         return 0;
     }
     const jobsOnly = "Only a secret's copy for jobs has versions and can be read back";
@@ -4377,10 +4421,39 @@ const VOLUME_HELP = `runtime volumes <command>
   backup-rm <backupId>                        Delete a backup
   backup-policy <id> [--daily on|off] [--retention-days N]
                                               Daily backups on or off, and how long each is kept
+  backup-policy <id> --every <minutes> | --cron "<m h dom mon dow>" [--keep hourly=24,daily=7,...]
+                                              Back up on a schedule of its own (UTC), keeping
+                                              last, hourly, daily, weekly, monthly, yearly counts
+  backup-policy <id> --no-schedule            Back to daily backups
   Attach one: runtime sandboxes create --volume <id>:/data
-  Volumes are backed up off their host daily unless you turn it off.
+  Volumes are backed up off their host daily, or on their own schedule, unless you turn it off.
   Shared commands work where shared disks are enabled.
 `;
+const KEEP_TIERS = ["last", "hourly", "daily", "weekly", "monthly", "yearly"];
+/** `hourly=24,daily=7` as keep counts; the server checks the numbers. */
+function keepCounts(text) {
+    const counts = {};
+    for (const part of text.split(",")) {
+        const [name, value, extra] = part.trim().split("=");
+        const tier = KEEP_TIERS.find((t) => t === name);
+        if (!tier || value === undefined || extra !== undefined || !/^\d+$/.test(value))
+            throw usage(`--keep takes name=count pairs such as hourly=24,daily=7; names: ${KEEP_TIERS.join(", ")}.`);
+        counts[tier] = Number(value);
+    }
+    return counts;
+}
+/** "daily backups on, kept 7 days", or the schedule, its keep counts and next run. */
+function backupPolicyWords(b) {
+    if (!b.schedule)
+        return `daily backups ${b.daily ? "on" : "off"}, kept ${b.retentionDays} days`;
+    const when = "everyMinutes" in b.schedule
+        ? `every ${b.schedule.everyMinutes} minutes`
+        : `on cron "${b.schedule.cron.trim()}" (UTC)`;
+    const kept = KEEP_TIERS.filter((t) => (b.keep?.[t] ?? 0) > 0)
+        .map((t) => `${t} ${b.keep[t]}`)
+        .join(", ");
+    return `backups ${when}${b.daily ? "" : " (off)"}, keeping ${kept}${b.daily && b.nextAt ? `; next ${b.nextAt}` : ""}`;
+}
 async function volume(argv, env, out) {
     const [verb, ...rest] = argv;
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
@@ -4489,7 +4562,7 @@ async function volume(argv, env, out) {
                         String(b.sizeMiB),
                         b.storedBytes === null ? "-" : `${Math.ceil(b.storedBytes / 1048576)} MiB`,
                         b.createdAt,
-                        b.expiresAt,
+                        b.expiresAt ?? "by keep counts",
                     ]),
                 ])
                 : "No backups yet.", all);
@@ -4510,19 +4583,30 @@ async function volume(argv, env, out) {
             return 0;
         }
         case "backup-policy": {
-            const args = parse(rest, [], ["daily", "retention-days"]);
+            const args = parse(rest, ["no-schedule"], ["daily", "retention-days", "every", "cron", "keep"]);
             const id = need(args.positional[0], "a volume id");
             const daily = flag(args, "daily");
             if (daily !== undefined && !["on", "off", "true", "false"].includes(daily))
                 throw usage("--daily takes on or off.");
             const days = integer(args, "retention-days");
-            if (daily === undefined && days === undefined)
-                throw usage("Give --daily on|off, --retention-days N or both.");
+            const every = integer(args, "every");
+            const cron = flag(args, "cron");
+            const off = has(args, "no-schedule");
+            if ([every !== undefined, cron !== undefined, off].filter(Boolean).length > 1)
+                throw usage("Give one of --every, --cron and --no-schedule.");
+            const keepText = flag(args, "keep");
+            const keep = keepText === undefined ? undefined : keepCounts(keepText);
+            if ([daily, days, every, cron, keep].every((x) => x === undefined) && !off)
+                throw usage("Give --daily on|off, --retention-days N, --every, --cron, --keep or --no-schedule.");
             const updated = await api.setBackupPolicy(id, {
                 ...(daily === undefined ? {} : { daily: daily === "on" || daily === "true" }),
                 ...(days === undefined ? {} : { retentionDays: days }),
+                ...(every === undefined ? {} : { schedule: { everyMinutes: every } }),
+                ...(cron === undefined ? {} : { schedule: { cron } }),
+                ...(off ? { schedule: null } : {}),
+                ...(keep === undefined ? {} : { keep }),
             });
-            print(`${updated.id} daily backups ${updated.backups.daily ? "on" : "off"}, kept ${updated.backups.retentionDays} days`, updated);
+            print(`${updated.id} ${backupPolicyWords(updated.backups)}`, updated);
             return 0;
         }
     }

package/dist/desktops/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/desktops`: Desktops alone. A Linux desktop on its own sandbox, with a live view and computer use, at the sandbox rates. In a private beta.
+ *
+ *   import { desktops } from "withruntime/desktops";
+ *   const client = desktops(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/desktops.js";
+/** `runtime.desktops` of a client made with `options`. */
+export declare function desktops(options?: RuntimeOptions): Runtime["desktops"];

package/dist/desktops/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/desktops`: Desktops alone. A Linux desktop on its own sandbox, with a live view and computer use, at the sandbox rates. In a private beta.
+ *
+ *   import { desktops } from "withruntime/desktops";
+ *   const client = desktops(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.desktops` of a client made with `options`. */
+export function desktops(options) {
+    return new Runtime(options).desktops;
+}