withruntime 0.33.2 → 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 waits\n  until a writer re-runs it on GitHub. In a private beta: outside it, each\n  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  ls [--repository <repoId>] [--branch <name>] [--commit <sha>] [--pr <number>]\n     [--state <state>]... [--limit 20]        Checks, newest first, with their jobs by state\n  get <checkId>                               One check and its jobs in plan order\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\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.\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 ls --commit $(git rev-parse HEAD)\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

@@ -6,9 +6,9 @@ import { ci, } from "./products/ci.js";
 export const CI_HELP = `runtime ci <command>
 
   CI/CD checks each push and pull request of a connected GitHub repository in
-  sandboxes, as the steps its config file names. A fork's pull request waits
-  until a writer re-runs it on GitHub. In a private beta: outside it, each
-  command says how to ask to join.
+  sandboxes, as the steps its config file names. A fork's pull request runs
+  nothing; a writer can open it again from a branch of the repository. In a
+  private beta: outside it, each command says how to ask to join.
 
   import [dir] [--write] [--force]            This folder's GitHub Actions workflows and CircleCI
                                               config as a runtime.yml: printed, or written with
@@ -30,11 +30,13 @@ export const CI_HELP = `runtime ci <command>
                                               lands once its check passes. Off until turned on;
                                               takes an owner's or admin's full key
   disconnect <repoId | owner/name>            Stop checking it; its checks still going are cancelled
-  ls [--repository <repoId>] [--branch <name>] [--commit <sha>] [--pr <number>]
-     [--state <state>]... [--limit 20]        Checks, newest first, with their jobs by state
-  get <checkId>                               One check and its jobs in plan order
+  checks [--repository <repoId>] [--branch <name>] [--commit <sha>] [--pr <number>]
+     [--state <state>]... [--limit 20]        Checks, newest first, with their jobs by state (or ls)
+  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
@@ -44,16 +46,22 @@ export const CI_HELP = `runtime ci <command>
   flake hand <flakeId> <login | org/team>     Hand it to someone else
   flake delete <flakeId> --reason <why>       Say why its test is deleted; it ends once main
                                               no longer holds the file
+  releases [--repository <repoId>] [--commit <sha>] [--limit 50]
+                                              A release's steps as they were taken, oldest
+                                              first: migrations, deploys, servers, waits
 
   A failed job's sandbox may be kept paused: \`runtime sandboxes wake <id>\`, then
-  \`runtime sandboxes shell <id>\` to look around where it failed.
+  \`runtime sandboxes shell <id>\` to look around where it failed. A key reads the
+  checks of repositories its own agent connected; an account-wide key reads and
+  cancels every check of the account (switch one at withruntime.com/account/keys).
 
 Examples
   runtime ci import --write
   runtime ci connect acme/web --config .runtime/ci.yml
   runtime ci repos trust acme/web acme-bot[bot]
   runtime ci repos undo acme/web on
-  runtime ci ls --commit $(git rev-parse HEAD)
+  runtime ci checks --commit $(git rev-parse HEAD)
+  runtime ci cancel <checkId>
   runtime ci logs <jobId>
 `;
 const when = (ms) => (ms === null ? "-" : new Date(ms).toISOString());
@@ -236,7 +244,8 @@ export async function ciCommand(argv, out, client, kit) {
         case "disconnect":
             return disconnect(need(rest[0], "the repository's id or owner/name"));
         case "ls":
-        case "list": {
+        case "list":
+        case "checks": {
             const args = parse(rest, [], ["repository", "branch", "commit", "pr", "state", "limit"]);
             const commit = flag(args, "commit");
             if (commit !== undefined && !/^([0-9a-f]{40}|[0-9a-f]{64})$/.test(commit))
@@ -273,7 +282,8 @@ export async function ciCommand(argv, out, client, kit) {
                 : "No checks.", all);
             return 0;
         }
-        case "get": {
+        case "get":
+        case "check": {
             const check = await api.checks.get(need(rest[0], "a check's id"));
             const job = (j) => [
                 j.id,
@@ -294,9 +304,24 @@ export async function ciCommand(argv, out, client, kit) {
         }
         case "cancel": {
             const check = await api.checks.cancel(need(rest[0], "a check's id (runtime ci ls)"));
+            // A key that may cancel the check but not read it is told its state alone.
+            if (!("commit" in check)) {
+                print(`${check.id}: ${check.state}`, check);
+                return 0;
+            }
             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>)"));
@@ -370,6 +395,30 @@ export async function ciCommand(argv, out, client, kit) {
             ].join("\n"), f);
             return 0;
         }
+        case "releases": {
+            const args = parse(rest, [], ["repository", "commit", "limit"]);
+            const repositoryId = flag(args, "repository");
+            const commit = flag(args, "commit");
+            const limit = flag(args, "limit");
+            const steps = (await api.releases.list({
+                limit: limit ? whole(limit, "--limit") : 50,
+                ...(repositoryId ? { repositoryId } : {}),
+                ...(commit ? { commit } : {}),
+            })).data.reverse();
+            print(steps.length
+                ? table([
+                    ["AT", "RELEASE", "BY", "SERVER", "STEP"],
+                    ...steps.map((s) => [
+                        when(s.at),
+                        s.commit.slice(0, 9),
+                        s.source,
+                        s.host ?? "-",
+                        s.line,
+                    ]),
+                ])
+                : "No release steps.", steps);
+            return 0;
+        }
         case "tests": {
             const args = parse(rest, ["quarantined"], []);
             const repositoryId = need(args.positional[0], "a repository's id (runtime ci repos)");
@@ -398,24 +447,28 @@ export async function ciCommand(argv, out, client, kit) {
         "connect",
         "repos",
         "disconnect",
+        "checks",
+        "check",
         "ls",
         "get",
         "cancel",
+        "rerun",
         "logs",
         "tests",
         "flakes",
         "flake",
+        "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. */