withruntime 0.6.0 → 0.7.0

package/dist/billing-cli.js

@@ -0,0 +1,158 @@
+import { RuntimeError } from "./errors.js";
+import { named } from "./cli-name.js";
+export const BILLING_HELP = `runtime billing <command>
+
+  topup <usd> [--wait]      Buy credit with stablecoins (USDC on Base, Solana or Tempo).
+                            Prints an address per network and the exact amount to send.
+                            Send exactly that, from any wallet, before the time shown.
+                            --wait keeps checking until the credit lands.
+  status <id> [--wait]      Whether a top-up's payment has arrived
+
+  No account yet? An agent can open one with a wallet alone:
+  topup <usd> --new-account --accept-terms [--wait]
+                            Opens an account and its first top-up. Prints a claim code,
+                            shown once. --wait saves the key here once the money lands.
+  claim <code> [--wait]     Exchange a paid account's claim code for its key, saved here
+
+  $10 to $10,000 a top-up; $500 in an account's first week. By card:
+  https://withruntime.com/account/billing
+`;
+function usage(message) {
+    return new RuntimeError({
+        message,
+        code: "usage",
+        status: 0,
+        hint: `Run \`${named("runtime")} billing help\`.`,
+    });
+}
+const DONE = new Set(["paid", "failed", "expired"]);
+function describe(topup) {
+    const me = named("runtime");
+    if (topup.status === "paid")
+        return `Paid: $${topup.amountUsd} of credit is on the account.`;
+    if (topup.status === "expired")
+        return `Expired: no payment arrived in time. Open a new one with \`${me} billing topup ${topup.amountUsd}\`.`;
+    if (topup.status === "failed")
+        return "Failed. Nothing was credited.";
+    if (topup.status === "pending")
+        return `Stripe has seen the payment and is confirming it. Check again with \`${me} billing status ${topup.purchaseId}\`.`;
+    const lines = [`Send exactly ${topup.amount} of one of these tokens, on one network:`, ""];
+    for (const network of topup.networks)
+        for (const token of network.tokens)
+            lines.push(`  ${network.network.padEnd(7)} ${token.currency.toUpperCase().padEnd(6)} to ${network.address}`, `  ${"".padEnd(7)} ${"".padEnd(6)}    token ${token.contract}`);
+    lines.push("", ...(topup.payBy ? [`Send before ${topup.payBy}.`] : []), "A different amount, token or network cannot be matched or returned automatically.", `The credit lands a few minutes after the transfer: \`${me} billing status ${topup.purchaseId}\`.`);
+    return lines.join("\n");
+}
+const FLAGS = new Set(["wait", "new-account", "accept-terms"]);
+export async function billingCommand(argv, args, out, client, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), wallet) {
+    const [verb, value] = args.positional;
+    const has = (name) => args.flags.get(name)?.at(-1) === "true";
+    const wait = has("wait");
+    for (const name of args.flags.keys())
+        if (!FLAGS.has(name))
+            throw usage(`Unknown option --${name}.`);
+    if (!verb || verb === "help") {
+        out.write(BILLING_HELP);
+        return 0;
+    }
+    if ((verb === "topup" && has("new-account")) || verb === "claim") {
+        if (!wallet)
+            throw usage("Wallet accounts are not available here.");
+        return walletCommand(verb, value, has("accept-terms"), wait, out, sleep, wallet);
+    }
+    const api = (await client()).billing;
+    let topup;
+    if (verb === "topup") {
+        topup = await api.topup({ usd: dollarsOf(value) }, { idempotencyKey: crypto.randomUUID() });
+    }
+    else if (verb === "status") {
+        if (!value)
+            throw usage("Give the top-up's id.");
+        topup = await api.topupStatus(value);
+    }
+    else {
+        throw usage(`Unknown billing command ${verb}.`);
+    }
+    const shown = new Set();
+    const show = (current) => {
+        if (out.json)
+            out.write(JSON.stringify(current));
+        else if (!shown.has(current.status))
+            out.write(describe(current));
+        shown.add(current.status);
+    };
+    show(topup);
+    if (!wait)
+        return 0;
+    /* Stripe takes a few minutes to see a transfer; checking every ten seconds
+       is quick enough and costs nothing. Stops once the top-up has an end, or
+       an hour after its deadline. */
+    const until = (topup.payBy ? Date.parse(topup.payBy) : Date.now()) + 60 * 60_000;
+    while (!DONE.has(topup.status) && Date.now() < until) {
+        await sleep(10_000);
+        topup = await api.topupStatus(topup.purchaseId);
+        show(topup);
+    }
+    return topup.status === "paid" ? 0 : 1;
+}
+function dollarsOf(value) {
+    const usd = Number(value?.replace(/^\$/, ""));
+    if (!value || !Number.isFinite(usd) || usd <= 0)
+        throw usage("Say how many dollars of credit to buy, such as `billing topup 20`.");
+    return usd;
+}
+/** `topup <usd> --new-account` and `claim <code>`: an account with no key. */
+async function walletCommand(verb, value, acceptTerms, wait, out, sleep, wallet) {
+    const me = named("runtime");
+    let code;
+    let payBy = null;
+    if (verb === "topup") {
+        if (!acceptTerms)
+            throw usage("Opening an account means agreeing to https://withruntime.com/legal/terms. Add --accept-terms once the person you work for agrees.");
+        const opened = await wallet.open({ usd: dollarsOf(value), acceptTerms: true });
+        code = opened.claimCode;
+        payBy = opened.payBy;
+        if (out.json)
+            out.write(JSON.stringify(opened));
+        else
+            out.write([
+                describe(opened),
+                "",
+                `Claim code (shown once, keep it secret): ${code}`,
+                `Once paid: \`${me} billing claim ${code}\` gives this machine the account's key.`,
+                "A person can take the account over at https://withruntime.com/account/claim with the same code.",
+            ].join("\n"));
+        if (!wait)
+            return 0;
+    }
+    else {
+        if (!value)
+            throw usage("Give the claim code.");
+        code = value;
+    }
+    const until = (payBy ? Date.parse(payBy) : Date.now()) + 60 * 60_000;
+    for (let first = verb === "claim";; first = false) {
+        if (!first)
+            await sleep(10_000);
+        const claim = await wallet.claim(code);
+        if (claim.status === "paid") {
+            await wallet.save(claim.apiKey, claim.orgId);
+            out.write(out.json
+                ? JSON.stringify({ status: "paid", orgId: claim.orgId, connected: true })
+                : "Paid. This machine is connected to the new account; its key is saved, not shown.");
+            return 0;
+        }
+        if (claim.status === "expired" || claim.status === "failed") {
+            out.write(out.json
+                ? JSON.stringify(claim)
+                : `The top-up ${claim.status}: nothing was credited. Open a new one with \`${me} billing topup <usd> --new-account --accept-terms\`.`);
+            return 1;
+        }
+        if (!wait || Date.now() >= until) {
+            out.write(out.json
+                ? JSON.stringify(claim)
+                : `Not paid yet (${claim.status}). Run \`${me} billing claim ${code}\` again once the transfer has gone through.`);
+            return wait ? 1 : 0;
+        }
+    }
+}

package/dist/cli-extras.d.ts

@@ -1,5 +1,6 @@
 import type { CliKit } from "./cli.js";
 import type { Sandbox } from "./sandbox.js";
+import type { Snapshot } from "./snapshots.js";
 type Out = {
     json: boolean;
     write: (text: string) => void;
@@ -21,4 +22,18 @@ export declare function lostOutput(result: {
     stdoutTruncated?: boolean;
     stderrTruncated?: boolean;
 }, id: string): string | undefined;
+/** Feeds `runtime sandbox shell` from standard input. When piped input ends,
+ * the shell is told so the way a terminal says it, Ctrl-D, after a newline
+ * if the last line had none: `echo ls | runtime sandbox shell <id>` runs `ls`
+ * and exits, as ssh does, where it used to wait forever (25 September 2026).
+ * A keyboard never ends, so a terminal's input is left alone. Returns the
+ * function that unhooks it. */
+export declare function pipeShellInput(stdin: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}, terminal: {
+    write(data: Uint8Array | string): void;
+}): () => void;
+/** `runtime snapshot get`, as `runtime sandbox get` reads: one fact a line.
+ * It printed raw JSON until 25 September 2026; `--json` still does. */
+export declare function describeSnapshot(s: Snapshot, table: (rows: string[][]) => string): string;
 export {};

package/dist/cli-extras.js

@@ -1,5 +1,5 @@
 import { writeFile } from "node:fs/promises";
-import { me } from "./login.js";
+import { me } from "./cli-name.js";
 export async function recordCommand(sbx, argv, out, kit) {
     const { parse, integer, need, table, usage } = kit;
     const [action, ...rest] = argv;
@@ -7,7 +7,7 @@ export async function recordCommand(sbx, argv, out, kit) {
     const r = sbx.desktop.recordings;
     switch (action) {
         case "start": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["fps", "max-seconds", "max-mib"]);
             const rec = await r.start({
                 ...(integer(args, "fps") ? { fps: integer(args, "fps") } : {}),
                 ...(integer(args, "max-seconds") ? { maxSeconds: integer(args, "max-seconds") } : {}),
@@ -51,7 +51,7 @@ export async function recordCommand(sbx, argv, out, kit) {
 }
 export async function watchCommand(sbx, argv, out, kit) {
     const { parse, flag, has, need } = kit;
-    const args = parse(argv, ["recursive"]);
+    const args = parse(argv, ["recursive"], ["events", "include", "exclude"]);
     const path = need(args.positional[0], "a directory, e.g. /workspace");
     const events = flag(args, "events")?.split(",");
     const watch = await sbx.files.watch(path, (event) => {
@@ -108,7 +108,7 @@ export async function mcpCommand(sbx, argv, out, kit) {
     };
     switch (action) {
         case "start": {
-            const args = parse(rest, ["replace"]);
+            const args = parse(rest, ["replace"], ["secret", "env", "option", "port"]);
             if (!args.positional.length)
                 throw usage("Name the servers: runtime sandbox mcp <id> start github fetch");
             const scoped = (name) => {
@@ -203,3 +203,59 @@ export function lostOutput(result, id) {
         return undefined;
     return `runtime: some of the command's output was lost: it wrote faster than it was read, and the sandbox keeps the latest 1 MiB. Write it to a file and copy it out: ${me} sandbox cp ${id}:/workspace/out.txt .`;
 }
+/** Feeds `runtime sandbox shell` from standard input. When piped input ends,
+ * the shell is told so the way a terminal says it, Ctrl-D, after a newline
+ * if the last line had none: `echo ls | runtime sandbox shell <id>` runs `ls`
+ * and exits, as ssh does, where it used to wait forever (25 September 2026).
+ * A keyboard never ends, so a terminal's input is left alone. Returns the
+ * function that unhooks it. */
+export function pipeShellInput(stdin, terminal) {
+    let last = 10;
+    const onData = (chunk) => {
+        const bytes = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+        if (bytes.length)
+            last = bytes[bytes.length - 1];
+        terminal.write(new Uint8Array(bytes));
+    };
+    const onEnd = () => {
+        if (stdin.isTTY)
+            return;
+        terminal.write(last === 10 ? "\x04" : "\n\x04");
+    };
+    stdin.on("data", onData);
+    stdin.on("end", onEnd);
+    return () => {
+        stdin.off("data", onData);
+        stdin.off("end", onEnd);
+    };
+}
+/** `runtime snapshot get`, as `runtime sandbox get` reads: one fact a line.
+ * It printed raw JSON until 25 September 2026; `--json` still does. */
+export function describeSnapshot(s, table) {
+    const mib = (bytes) => bytes === null ? "-" : `${Math.ceil(bytes / 1_048_576).toLocaleString("en-US")} MiB`;
+    const labels = (s.labels ?? {});
+    return table([
+        ["id", s.id],
+        ["name", s.name ?? "-"],
+        ["state", s.state],
+        ["from", s.sourceSandboxId],
+        ["shape", `${s.shape.vcpu} vCPU, ${s.shape.memoryMiB} MiB memory, ${s.shape.diskMiB} MiB disk`],
+        ["stored", mib(s.storedBytes)],
+        ["billed for", mib(s.meteredBytes)],
+        [
+            "backed up",
+            s.backedUp
+                ? `yes${s.durability.durableAt ? `, ${s.durability.durableAt}` : ""}`
+                : s.durability.state,
+        ],
+        ["created", s.createdAt],
+        ["kept until", `${s.expiresAt} (${s.retentionDays} days)`],
+        [
+            "labels",
+            Object.entries(labels)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(", ") || "-",
+        ],
+        ...(s.error ? [["error", s.error]] : []),
+    ]);
+}

package/dist/cli-name.d.ts

@@ -0,0 +1,6 @@
+/** How this CLI was started, so what it tells you to type works: through npx
+ * the command is `npx withruntime`, installed it is `runtime`. Its own module
+ * so a command that only names itself does not load the login flow. */
+export declare const me: string;
+/** Text that names a command, with the command spelled the way it was run. */
+export declare function named(text: string, name?: string): string;

package/dist/cli-name.js

@@ -0,0 +1,8 @@
+/** How this CLI was started, so what it tells you to type works: through npx
+ * the command is `npx withruntime`, installed it is `runtime`. Its own module
+ * so a command that only names itself does not load the login flow. */
+export const me = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "") ? "npx withruntime" : "runtime";
+/** Text that names a command, with the command spelled the way it was run. */
+export function named(text, name = me) {
+    return name === "runtime" ? text : text.replace(/(^|[\s`(])runtime(?= [a-z<[])/g, `$1${name}`);
+}

package/dist/cli.d.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { RuntimeError } from "./errors.js";
+import type { Usage } from "./types.js";
+import type { SecretRule } from "./products/secrets.js";
 type Out = {
     json: boolean;
     write: (text: string) => void;
@@ -12,7 +14,7 @@ type Args = {
 };
 /** What the commands in cli-extras.ts use of this file. */
 declare const kit: {
-    parse: (argv: string[], booleans?: string[]) => Args;
+    parse: (argv: string[], booleans: readonly string[], values: readonly string[]) => Args;
     flag: (args: Args, name: string) => string | undefined;
     has: (args: Args, name: string) => boolean;
     integer: (args: Args, name: string) => number | undefined;
@@ -25,6 +27,20 @@ declare const kit: {
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;
+/** `runtime usage` for a person: the balance, the trial and what each kind
+ * of resource was charged, in dollars. --json keeps every figure, and each
+ * resource with its rates and CPU time. */
+/** One row per resource, for a spreadsheet: when it ran, how big it was, how
+ * long it ran, the CPU it used and what it cost. Money is exact dollars to the
+ * microdollar (the API's integer microdollars moved six places), so a column
+ * sums to the ledger to the last digit. */
+export declare function usageCsv(u: Usage): string;
+/** `--allow` values as secret rules: each is `[METHOD[,METHOD]...] PATH`, and
+ * rules naming the same methods share one rule's paths. Only the shape is read
+ * here; the API holds every rule to the same check the host makes
+ * (ARCHITECTURE.md section 10, "Per-path rules on an egress secret") and says
+ * which one it refused. */
+export declare function parseSecretRules(values: string[]): SecretRule[];
 export declare function secretsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, 
 /** Tests give the value here; the CLI reads standard input. */
 read?: () => Promise<string>): Promise<number>;