withruntime 0.6.1 → 0.7.0

package/E2B.md

@@ -50,38 +50,38 @@ machine. An E2B key (`e2b_...`) is never sent anywhere. If one is passed as
 
 ## Mapping
 
-| E2B                                                                                      | On Runtime                                                                                                                                                                     |
-| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `Sandbox.create()`, `Sandbox.create(template, opts)`                                     | `sandboxes.create`. `base` and `code-interpreter-v1` are Runtime's stock image. Any other name must be a ready Runtime image with that name. A UUID is an image or a snapshot. |
-| `timeoutMs` (Python `timeout`, seconds)                                                  | `timeoutSeconds`, rounded up. Under 60 s becomes 60 s, with a warning. Over an hour is refused.                                                                                |
-| `metadata`                                                                               | labels (at most 32).                                                                                                                                                           |
-| `envs`                                                                                   | Given to every command and code run through this object.                                                                                                                       |
-| `allowInternetAccess: false`                                                             | `network: { internet: false }`.                                                                                                                                                |
-| `lifecycle.onTimeout`                                                                    | `onLeaseEnd`: `kill` is `stop`, `pause` is `pause`.                                                                                                                            |
-| `commands.run(cmd, { cwd, envs, timeoutMs, onStdout, onStderr })`                        | `exec`, streamed, so the whole output comes back however large. Default timeout 60 s. `0` means no limit (Runtime's longest, 24 hours).                                        |
-| Non-zero exit                                                                            | Throws `CommandExitError` with `exitCode`, `stdout`, `stderr` and `error` (`exit status N`). A command killed by a signal has `exitCode` -1.                                   |
-| Command past its timeout                                                                 | Throws `TimeoutError`.                                                                                                                                                         |
-| `commands.run(cmd, { background: true })`                                                | `spawn`. Returns a `CommandHandle` with `pid`, `wait()`, `kill()` (SIGKILL), `sendStdin`, `closeStdin`, `disconnect`, `stdout`, `stderr`, `exitCode`.                          |
-| `commands.list`, `kill(pid)`, `sendStdin(pid)`, `closeStdin(pid)`, `connect(pid)`        | Runtime's processes. A pid is a number derived from Runtime's process id, not the Linux pid.                                                                                   |
-| `files.read(path, { format })`                                                           | `files.read`. `text`, `bytes`, `blob` and `stream` (Python: `text`, `bytes`, `stream`).                                                                                        |
-| `files.write(path, data)`, `write([...])`, `writeFiles`                                  | `files.write`. Parent directories are made, and a file that exists is replaced.                                                                                                |
-| `files.list(path, { depth })`                                                            | `files.list`, hidden files included. `owner` and `group` are always `""`.                                                                                                      |
-| `files.makeDir`, `exists`, `getInfo`, `rename`, `remove`                                 | `files.stat`, `mkdir`, `rename` (replacing a file that exists) and `remove` (recursive). A missing file throws `FileNotFoundError`.                                            |
-| Relative paths                                                                           | Resolved against the home directory, `/workspace` on Runtime.                                                                                                                  |
-| `/home/user` (E2B's home)                                                                | The first time a path, `cwd` or command names it, it becomes a link to `/workspace`, unless something is already there.                                                        |
-| `sandbox.kill()`, `Sandbox.kill(id)`                                                     | `stop`, without waiting. `false` when the sandbox was not found or had already ended.                                                                                          |
-| `sandbox.setTimeout(ms)`, `Sandbox.setTimeout(id, ms)`                                   | `extend`: the end moves to now + ms. Moving it earlier is refused.                                                                                                             |
-| `Sandbox.connect(id, { timeoutMs })`, `sandbox.connect()`                                | `get`. A paused sandbox is woken. A running one's end moves later, never earlier. An ended one throws `SandboxNotFoundError`.                                                  |
-| `sandbox.pause()`, `betaPause`, `Sandbox.pause(id)`                                      | `pause`, keeping memory and files. `false` when it was already paused.                                                                                                         |
-| `getInfo`, `isRunning`                                                                   | `get`. `templateId` is `base` or the image or snapshot id. `envdVersion` is `runtime`.                                                                                         |
-| `Sandbox.list({ query: { metadata, state }, limit })`                                    | `sandboxes.list` by labels and state, oldest first, with E2B's paginator (`hasNext`, `nextItems()`).                                                                           |
-| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's forks and snapshots. While Runtime has them switched off, they throw `NotSupportedError` with Runtime's own message.                                                 |
-| `getHost(port)`                                                                          | Refused, because E2B answers it without a call. `await sandbox.getPublicHost(port)` shares the port as a public Runtime preview and returns its host.                          |
-| `runCode(code, { language, context, onStdout, onStderr, onResult, onError, timeoutMs })` | Runtime's interpreter, Python and JavaScript. The sandbox's `envs` reach code through a context made once for them. `onResult` is called after the run ends.                   |
-| `Execution`, `Result`, `Logs`, `ExecutionError`, `OutputMessage`                         | The same shapes. Results that are too large to send inline are fetched and inlined. `logs.stdout` has one entry per line.                                                      |
-| `createCodeContext`, `listCodeContexts`, `restartCodeContext`, `removeCodeContext`       | Runtime's interpreter contexts.                                                                                                                                                |
-| `getMetrics({ start, end })`, `Sandbox.getMetrics(id)`                                   | Runtime's measured CPU and memory, one entry per host reading (every minute by default). `diskUsed` is null: Runtime does not read disk use inside the sandbox.                |
-| Error classes                                                                            | E2B's names and parents. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                       |
+| E2B                                                                                      | On Runtime                                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Sandbox.create()`, `Sandbox.create(template, opts)`                                     | `sandboxes.create`. `base` and `code-interpreter-v1` are Runtime's stock image. Any other name must be a ready Runtime image with that name. A UUID is an image or a snapshot.                                                                              |
+| `timeoutMs` (Python `timeout`, seconds)                                                  | `timeoutSeconds`, rounded up. Under 60 s becomes 60 s, with a warning. Over an hour is refused.                                                                                                                                                             |
+| `metadata`                                                                               | labels (at most 32).                                                                                                                                                                                                                                        |
+| `envs`                                                                                   | Given to every command and code run through this object.                                                                                                                                                                                                    |
+| `allowInternetAccess: false`                                                             | `network: { internet: false }`.                                                                                                                                                                                                                             |
+| `lifecycle.onTimeout`                                                                    | `onLeaseEnd`: `kill` is `stop`, `pause` is `pause`.                                                                                                                                                                                                         |
+| `commands.run(cmd, { cwd, envs, timeoutMs, onStdout, onStderr })`                        | `exec`, streamed, so the whole output comes back however large. Default timeout 60 s. `0` means no limit (Runtime's longest, 24 hours).                                                                                                                     |
+| Non-zero exit                                                                            | Throws `CommandExitError` with `exitCode`, `stdout`, `stderr` and `error` (`exit status N`). A command killed by a signal has `exitCode` -1.                                                                                                                |
+| Command past its timeout                                                                 | Throws `TimeoutError`.                                                                                                                                                                                                                                      |
+| `commands.run(cmd, { background: true })`                                                | `spawn`. Returns a `CommandHandle` with `pid`, `wait()`, `kill()` (SIGKILL), `sendStdin`, `closeStdin`, `disconnect`, `stdout`, `stderr`, `exitCode`.                                                                                                       |
+| `commands.list`, `kill(pid)`, `sendStdin(pid)`, `closeStdin(pid)`, `connect(pid)`        | Runtime's processes. A pid is a number derived from Runtime's process id, not the Linux pid.                                                                                                                                                                |
+| `files.read(path, { format })`                                                           | `files.read`. `text`, `bytes`, `blob` and `stream` (Python: `text`, `bytes`, `stream`).                                                                                                                                                                     |
+| `files.write(path, data)`, `write([...])`, `writeFiles`                                  | `files.write`. Parent directories are made, and a file that exists is replaced.                                                                                                                                                                             |
+| `files.list(path, { depth })`                                                            | `files.list`, hidden files included. `owner` and `group` are always `""`.                                                                                                                                                                                   |
+| `files.makeDir`, `exists`, `getInfo`, `rename`, `remove`                                 | `files.stat`, `mkdir`, `rename` (replacing a file that exists) and `remove` (recursive). A missing file throws `FileNotFoundError`.                                                                                                                         |
+| Relative paths                                                                           | Resolved against the home directory, `/workspace` on Runtime.                                                                                                                                                                                               |
+| `/home/user` (E2B's home)                                                                | The first time a path, `cwd` or command names it, it becomes a link to `/workspace`, unless something is already there.                                                                                                                                     |
+| `sandbox.kill()`, `Sandbox.kill(id)`                                                     | `stop`, without waiting. `false` when the sandbox was not found or had already ended.                                                                                                                                                                       |
+| `sandbox.setTimeout(ms)`, `Sandbox.setTimeout(id, ms)`                                   | `extend`: the end moves to now + ms. Moving it earlier is refused.                                                                                                                                                                                          |
+| `Sandbox.connect(id, { timeoutMs })`, `sandbox.connect()`                                | `get`. A paused sandbox is woken. A running one's end moves later, never earlier. An ended one throws `SandboxNotFoundError`.                                                                                                                               |
+| `sandbox.pause()`, `betaPause`, `Sandbox.pause(id)`                                      | `pause`, keeping memory and files. `false` when it was already paused.                                                                                                                                                                                      |
+| `getInfo`, `isRunning`                                                                   | `get`. `templateId` is `base` or the image or snapshot id. `envdVersion` is `runtime`.                                                                                                                                                                      |
+| `Sandbox.list({ query: { metadata, state }, limit })`                                    | `sandboxes.list` by labels and state, oldest first, with E2B's paginator (`hasNext`, `nextItems()`).                                                                                                                                                        |
+| `fork`, `createSnapshot`, `deleteSnapshot`                                               | Runtime's forks and snapshots. While Runtime has them switched off, they throw `NotSupportedError` with Runtime's own message.                                                                                                                              |
+| `getHost(port)`                                                                          | `<port>-<id>.runtimehost.com` at once, as E2B answers it, and the port is shared as a public Runtime preview beside the caller (the sync Python sandbox shares it before returning). `await sandbox.getPublicHost(port)` returns once the share has landed. |
+| `runCode(code, { language, context, onStdout, onStderr, onResult, onError, timeoutMs })` | Runtime's interpreter, Python and JavaScript. The sandbox's `envs` reach code through a context made once for them. `onResult` is called after the run ends.                                                                                                |
+| `Execution`, `Result`, `Logs`, `ExecutionError`, `OutputMessage`                         | The same shapes. Results that are too large to send inline are fetched and inlined. `logs.stdout` has one entry per line.                                                                                                                                   |
+| `createCodeContext`, `listCodeContexts`, `restartCodeContext`, `removeCodeContext`       | Runtime's interpreter contexts.                                                                                                                                                                                                                             |
+| `getMetrics({ start, end })`, `Sandbox.getMetrics(id)`                                   | Runtime's measured CPU and memory, one entry per host reading (every minute by default). `diskUsed` is null: Runtime does not read disk use inside the sandbox.                                                                                             |
+| Error classes                                                                            | E2B's names and parents. Each also carries Runtime's `code`, `hint` and `requestId`, with the original error as `cause`.                                                                                                                                    |
 
 ## Gaps
 

package/README.md

@@ -1,7 +1,7 @@
 # Runtime Cloud SDK and CLI
 
-One client for every Runtime Cloud product, and the `runtime` CLI. Node.js 22
-or later, or Bun. Its one dependency, undici (Node's own HTTP client), is
+One client for every Runtime Cloud product, and the `runtime` CLI. Node.js
+22.12 or later, or Bun. Its one dependency, undici (Node's own HTTP client), is
 loaded only behind a proxy.
 
 ```bash no-run
@@ -27,7 +27,7 @@ console.log(result.exitCode, result.stdout);
 `Sandbox.create()` needs no arguments and returns once the sandbox is running;
 `await using` stops it when the block ends (Node 24, Bun or TypeScript; on
 Node 22 call `await sbx.stop()`). With no arguments you get the free
-trial while it lasts (50 free hours, up to eight sandboxes running at once), 2 vCPU, 4 GiB of
+trial while it lasts (100 free hours, up to eight sandboxes running at once), 2 vCPU, 4 GiB of
 memory and a 4 GiB disk. The current default image includes NumPy, pandas and
 matplotlib; see the [sandbox environment](https://withruntime.com/docs/sandbox-environment).
 

package/dist/ai/index.d.ts

@@ -9,21 +9,37 @@
  *   await generateText({ model, tools: runtimeTools(sbx), stopWhen: stepCountIs(10), prompt });
  *
  * Needs the `ai` package (version 5 or newer) beside this one. */
-import { type Tool } from "ai";
+import { type Schema } from "ai";
 import type { Sandbox } from "../sandbox.js";
 import { type ExecInput, type ExecOutput, type ListEntry, type SandboxToolOptions } from "../tools/index.js";
 export type { SandboxToolOptions } from "../tools/index.js";
+/** One tool, typed so that both the AI SDK's `tools` and Mastra's accept it.
+ *
+ * ai 7's own `Tool` type is not assignable to Mastra's `tools` (checked with
+ * @mastra/core 1.71.0): ai 7 lets a description be a function, forbids an `id`
+ * and wants `context` in the call options, and Mastra wants a string
+ * description, an `id` or the older `parameters` field, and passes no
+ * `context`. This shape is the part both agree on. `parameters` is the same
+ * schema object as `inputSchema`: Mastra reads whichever it finds and the AI
+ * SDK reads only `inputSchema`. */
+export type RuntimeTool<I, O> = {
+    type?: undefined;
+    description: string;
+    inputSchema: Schema<I>;
+    parameters: Schema<I>;
+    execute: (input: I, options?: unknown) => Promise<O>;
+};
 /** `{ runtime_exec, runtime_read_file, runtime_write_file, runtime_list_files }`, bound to `sandbox`. */
 export type RuntimeTools = {
-    runtime_exec: Tool<ExecInput, ExecOutput>;
-    runtime_read_file: Tool<{
+    runtime_exec: RuntimeTool<ExecInput, ExecOutput>;
+    runtime_read_file: RuntimeTool<{
         path: string;
     }, string>;
-    runtime_write_file: Tool<{
+    runtime_write_file: RuntimeTool<{
         path: string;
         content: string;
     }, string>;
-    runtime_list_files: Tool<{
+    runtime_list_files: RuntimeTool<{
         path?: string;
         depth?: number;
     }, ListEntry[] | {

package/dist/ai/index.js

@@ -9,30 +9,23 @@
  *   await generateText({ model, tools: runtimeTools(sbx), stopWhen: stepCountIs(10), prompt });
  *
  * Needs the `ai` package (version 5 or newer) beside this one. */
-import { jsonSchema, tool } from "ai";
+import { jsonSchema } from "ai";
 import { sandboxTools, } from "../tools/index.js";
+function aiTool(source) {
+    const schema = jsonSchema(source.inputSchema);
+    return {
+        description: source.description,
+        inputSchema: schema,
+        parameters: schema,
+        execute: (input) => source.execute(input),
+    };
+}
 export function runtimeTools(sandbox, options = {}) {
     const [exec, read, write, list] = sandboxTools(sandbox, options);
     return {
-        runtime_exec: tool({
-            description: exec.description,
-            inputSchema: jsonSchema(exec.inputSchema),
-            execute: (input) => exec.execute(input),
-        }),
-        runtime_read_file: tool({
-            description: read.description,
-            inputSchema: jsonSchema(read.inputSchema),
-            execute: (input) => read.execute(input),
-        }),
-        runtime_write_file: tool({
-            description: write.description,
-            inputSchema: jsonSchema(write.inputSchema),
-            execute: (input) => write.execute(input),
-        }),
-        runtime_list_files: tool({
-            description: list.description,
-            inputSchema: jsonSchema(list.inputSchema),
-            execute: (input) => list.execute(input),
-        }),
+        runtime_exec: aiTool(exec),
+        runtime_read_file: aiTool(read),
+        runtime_write_file: aiTool(write),
+        runtime_list_files: aiTool(list),
     };
 }

package/dist/ai-harness/index.js

@@ -31,6 +31,19 @@ const DEFAULT_COMMAND_MS = 3_600_000;
 /** Exit codes for a command that ended without one, as coreutils `timeout` and SIGKILL give. */
 const TIMED_OUT_EXIT = 124;
 const KILLED_EXIT = 137;
+/** The exit code a shell would report, which harnesses expect. Runtime's API
+ * gives a command killed by a signal as the negative signal number (a command
+ * past its limit is killed with SIGKILL and reads -9); a shell says 128 plus
+ * the signal, so -15 is 143. A command past its limit exits 124, whatever
+ * killed it, as `timeout(1)` does. */
+function shellExitCode(exit) {
+    if (exit?.timedOut)
+        return TIMED_OUT_EXIT;
+    const code = exit?.exitCode;
+    if (code === undefined || code === null)
+        return KILLED_EXIT;
+    return code < 0 ? 128 - code : code;
+}
 /** A harness sandbox provider backed by Runtime Cloud. Construct it once, at
  * module scope; nothing is created until a session is. */
 export function createRuntimeSandbox(settings = {}) {
@@ -187,7 +200,7 @@ export class RuntimeSandboxSession {
             throw abortSignal.reason;
         const timedOut = exit?.timedOut ?? false;
         return {
-            exitCode: exit?.exitCode ?? (timedOut ? TIMED_OUT_EXIT : KILLED_EXIT),
+            exitCode: shellExitCode(exit),
             stdout: out.stdout,
             stderr: timedOut
                 ? `${out.stderr}${out.stderr && !out.stderr.endsWith("\n") ? "\n" : ""}Timed out: the command ran past its limit and was ended.\n`
@@ -266,7 +279,7 @@ export class RuntimeSandboxSession {
                 if (abortSignal?.aborted)
                     throw abortSignal.reason;
                 return {
-                    exitCode: exit?.exitCode ?? (exit?.timedOut ? TIMED_OUT_EXIT : KILLED_EXIT),
+                    exitCode: shellExitCode(exit),
                 };
             },
             kill: async () => {

package/dist/billing-cli.d.ts

@@ -0,0 +1,21 @@
+import type { Runtime } from "./client.js";
+import type { claimWalletAccount, openWalletAccount } from "./wallet.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+type Args = {
+    positional: string[];
+    flags: Map<string, string[]>;
+};
+export declare const BILLING_HELP = "runtime billing <command>\n\n  topup <usd> [--wait]      Buy credit with stablecoins (USDC on Base, Solana or Tempo).\n                            Prints an address per network and the exact amount to send.\n                            Send exactly that, from any wallet, before the time shown.\n                            --wait keeps checking until the credit lands.\n  status <id> [--wait]      Whether a top-up's payment has arrived\n\n  No account yet? An agent can open one with a wallet alone:\n  topup <usd> --new-account --accept-terms [--wait]\n                            Opens an account and its first top-up. Prints a claim code,\n                            shown once. --wait saves the key here once the money lands.\n  claim <code> [--wait]     Exchange a paid account's claim code for its key, saved here\n\n  $10 to $10,000 a top-up; $500 in an account's first week. By card:\n  https://withruntime.com/account/billing\n";
+/** Wallet-account commands need no key, and the claim saves the one they get. */
+export type WalletDeps = {
+    open: typeof openWalletAccount;
+    claim: typeof claimWalletAccount;
+    /** Saves a claimed key as this machine's connection, as `login --with-key` does. */
+    save: (key: string, orgId: string) => Promise<void>;
+};
+export declare function billingCommand(argv: string[], args: Args, out: Out, client: () => Promise<Runtime>, sleep?: (ms: number) => Promise<void>, wallet?: WalletDeps): Promise<number>;
+export {};

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>;