withruntime 0.11.2 → 0.14.0

package/dist/blaxel/sandbox.d.ts

@@ -40,6 +40,18 @@ export type SandboxArchiveOptions = {
     maxWait?: number;
     interval?: number;
 };
+/** The longest creation `timeout` Blaxel accepts, in seconds. */
+export declare const MAX_CREATION_TIMEOUT_SECONDS = 50;
+/** Options of SandboxInstance.create / createIfNotExists, as Blaxel's. */
+export type SandboxCreateOptions = {
+    /** List `/` once it runs, and delete it if that fails. */
+    safe?: boolean;
+    /** Answer the sandbox already holding the name instead of a 409. */
+    createIfNotExist?: boolean;
+    /** Give up after this many whole seconds (1 to 50): the sandbox is deleted
+     * and the call rejects with SandboxCreationTimeoutError. */
+    timeout?: number;
+};
 /** What a create asked for that no label keeps: shown by `spec` in the
  * client that created the sandbox. */
 type Asked = {
@@ -127,15 +139,12 @@ export declare class SandboxInstance {
     get expiresIn(): number | undefined;
     /** Creates a sandbox and answers once it runs. Blaxel's defaults: the base
      * image (Runtime's stock image) and 4096 MB, with vCPUs at one per 2048 MB.
-     * Funding is left to Runtime: the included usage first, then prepaid credit. A name another live sandbox holds is refused
+     * Funding is left to Runtime: the free usage first, then prepaid credit. A name another live sandbox holds is refused
      * with a 409, as in Blaxel. */
-    static create<T extends typeof SandboxInstance>(this: T, sandbox?: SandboxCreateConfiguration | SandboxModel, { createIfNotExist }?: {
-        safe?: boolean;
-        createIfNotExist?: boolean;
-    }): Promise<InstanceType<T>>;
+    static create<T extends typeof SandboxInstance>(this: T, sandbox?: SandboxCreateConfiguration | SandboxModel, options?: SandboxCreateOptions): Promise<InstanceType<T>>;
     /** The named sandbox, or a new one when no live sandbox has the name.
      * Runtime settles a race between two callers: both get the same sandbox. */
-    static createIfNotExists<T extends typeof SandboxInstance>(this: T, sandbox: SandboxCreateConfiguration | SandboxModel): Promise<InstanceType<T>>;
+    static createIfNotExists<T extends typeof SandboxInstance>(this: T, sandbox: SandboxCreateConfiguration | SandboxModel, options?: Omit<SandboxCreateOptions, "createIfNotExist">): Promise<InstanceType<T>>;
     /** The live sandbox with this name (or Runtime id). It is not woken: the
      * next call wakes it. */
     static get<T extends typeof SandboxInstance>(this: T, sandboxName: string, options?: RuntimeOptions): Promise<InstanceType<T>>;

package/dist/blaxel/sandbox.js

@@ -1,7 +1,7 @@
 import { RuntimeError } from "../errors.js";
 import { clientFor, defaultRegion, } from "./client.js";
 import { checkEnvNames, envFileCommand, envFileLines, parseProcessLine, toRuntimePath, } from "./context.js";
-import { codeOf, guard, NotSupportedError, responseError, translate } from "./errors.js";
+import { codeOf, guard, NotSupportedError, responseError, SandboxCreationTimeoutError, translate, } from "./errors.js";
 import { SandboxFileSystem } from "./filesystem.js";
 import { ARCHIVED, DISPLAY_NAME, EXTERNAL_ID, IDLE_PAUSE, LABEL, findByExternalId, findSandbox, LEASE_SECONDS, ownLabels, STANDBY, userLabels, whenNameFree, } from "./lookup.js";
 import { paginate } from "./pagination.js";
@@ -38,6 +38,56 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const DAY_MS = 86_400_000;
 /** The lease is renewed in the background once this little of it is left. */
 const RENEW_BELOW_MS = 10 * 60_000;
+/** The longest creation `timeout` Blaxel accepts, in seconds. */
+export const MAX_CREATION_TIMEOUT_SECONDS = 50;
+/** Blaxel's own check of `timeout`, with its words. */
+function creationTimeout({ timeout }) {
+    if (timeout === undefined)
+        return undefined;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > MAX_CREATION_TIMEOUT_SECONDS)
+        throw new Error(`SandboxInstance.create: 'timeout' must be a whole number of seconds between 1 and ${MAX_CREATION_TIMEOUT_SECONDS}, got ${timeout}.`);
+    return timeout;
+}
+/** A create that must be running within `timeout` seconds of the call, the
+ * wait for capacity included. One that is not is deleted, so the name is
+ * free again, and the call rejects with SandboxCreationTimeoutError. */
+async function createWithin(client, input, timeout) {
+    const deadline = performance.now() + timeout * 1000;
+    const runtime = await guard(() => whenNameFree(client, () => client.sandboxes.create({ ...input, wait: false }, { waitForCapacityMs: timeout * 1000 })));
+    // A sandbox the name already had is the caller's, whatever its state: it is
+    // answered as it is, as without a timeout, and never deleted here.
+    if (runtime.state === "running" || runtime.info.reused)
+        return runtime;
+    const left = deadline - performance.now();
+    if (left > 0)
+        try {
+            await runtime.waitFor("running", {
+                timeoutSeconds: Math.max(1, Math.ceil(left / 1000)),
+                timeoutMs: Math.ceil(left) + 5_000,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof RuntimeError && error.code === "timeout")) {
+                await runtime.delete().catch(() => undefined);
+                throw translate(error);
+            }
+        }
+    // waitFor updated the state TypeScript narrowed above.
+    const state = runtime.state;
+    if (state === "running")
+        return runtime;
+    await runtime.delete().catch(() => undefined);
+    if (state !== "starting")
+        throw translate(new RuntimeError({
+            message: `Sandbox ${runtime.id} is ${runtime.state}, not running.`,
+            code: "start_failed",
+            status: 0,
+            hint: "Create it again; SandboxInstance.get(name) reads why it stopped.",
+        }));
+    throw new SandboxCreationTimeoutError(input.name, timeout, {
+        message: `It was still starting after ${timeout}s.`,
+    });
+}
 /** The labels a new sandbox carries: the caller's, and under `blaxel/` what
  * Blaxel keeps and Runtime has no field for, so any client (the Python
  * adapter too) reads the same `spec`. */
@@ -212,7 +262,7 @@ async function resolveImage(client, image) {
     if (found && found.state === "ready")
         return { image: found.id };
     const feature = `The image ${image}, which is not a Runtime image`;
-    const alternative = `Build it as a Runtime image named ${name}: \`npx withruntime image build --dockerfile Dockerfile --name ${name} -t ${name}:${tag}\`. The code can keep "${image}": the adapter starts from ${name}:${tag}.`;
+    const alternative = `Build it as a Runtime image named ${name}: \`npx withruntime images build --dockerfile Dockerfile --name ${name} -t ${name}:${tag}\`. The code can keep "${image}": the adapter starts from ${name}:${tag}.`;
     throw new NotSupportedError(feature, alternative, `${feature}, is not supported on Runtime. ${alternative}`);
 }
 /** Blaxel volumes (by name) as Runtime volumes. */
@@ -228,7 +278,7 @@ async function resolveVolumes(client, volumes) {
     return Promise.all(volumes.map(async (volume) => {
         const found = (await guard(() => client.volumes.list({ name: volume.name }))).data[0];
         if (!found)
-            throw new NotSupportedError(`The volume ${volume.name}, which is not a Runtime volume`, `Create it first: runtime.volumes.create({ name: "${volume.name}" }) or \`npx withruntime volume create --name ${volume.name}\`.`);
+            throw new NotSupportedError(`The volume ${volume.name}, which is not a Runtime volume`, `Create it first: runtime.volumes.create({ name: "${volume.name}" }) or \`npx withruntime volumes create --name ${volume.name}\`.`);
         return { volumeId: found.id, path: toRuntimePath(volume.mountPath) };
     }));
 }
@@ -523,9 +573,11 @@ export class SandboxInstance {
     // ---- create, get, list ---------------------------------------------------
     /** Creates a sandbox and answers once it runs. Blaxel's defaults: the base
      * image (Runtime's stock image) and 4096 MB, with vCPUs at one per 2048 MB.
-     * Funding is left to Runtime: the included usage first, then prepaid credit. A name another live sandbox holds is refused
+     * Funding is left to Runtime: the free usage first, then prepaid credit. A name another live sandbox holds is refused
      * with a 409, as in Blaxel. */
-    static async create(sandbox, { createIfNotExist = false } = {}) {
+    static async create(sandbox, options = {}) {
+        const { createIfNotExist = false, safe = false } = options;
+        const timeout = creationTimeout(options);
         const config = configOf(sandbox);
         const region = config.region || defaultRegion();
         checkRegion(region);
@@ -559,7 +611,9 @@ export class SandboxInstance {
             ...(createIfNotExist && config.name ? { getOrCreate: true } : {}),
             ...config.withruntime?.create,
         };
-        const runtime = await guard(() => whenNameFree(client, () => client.sandboxes.create(input)));
+        const runtime = timeout === undefined
+            ? await guard(() => whenNameFree(client, () => client.sandboxes.create(input)))
+            : await createWithin(client, input, timeout);
         const asked = {
             ...(Object.keys(envs).length ? { envs } : {}),
             ...(config.network ? { network: config.network } : {}),
@@ -571,6 +625,8 @@ export class SandboxInstance {
         const instance = new this({ runtime, client, asked });
         try {
             await instance.#setUp(envs, lifetime.days);
+            if (safe)
+                await instance.fs.ls("/");
         }
         catch (error) {
             await runtime.stop({ wait: false }).catch(() => undefined);
@@ -580,8 +636,8 @@ export class SandboxInstance {
     }
     /** The named sandbox, or a new one when no live sandbox has the name.
      * Runtime settles a race between two callers: both get the same sandbox. */
-    static async createIfNotExists(sandbox) {
-        return this.create(sandbox, { createIfNotExist: true });
+    static async createIfNotExists(sandbox, options = {}) {
+        return this.create(sandbox, { ...options, createIfNotExist: true });
     }
     /** The live sandbox with this name (or Runtime id). It is not woken: the
      * next call wakes it. */

package/dist/blaxel/snapshot.d.ts

@@ -71,6 +71,10 @@ export declare function appendEnvs(runtime: RuntimeSandbox, envs: Record<string,
 export declare function startFromSnapshot(client: Runtime, snapshotId: string, name: string, labels: Record<string, string>, envs: Record<string, string>): Promise<RuntimeSandbox>;
 declare function refuseApplication(options?: {
     targetType?: string;
+    port?: number;
+    traffic?: number;
+    customDomain?: string;
+    prefix?: string;
 }): void;
 /** A snapshot, as Blaxel's Snapshot class. */
 export declare class Snapshot {

package/dist/blaxel/snapshot.js

@@ -63,6 +63,10 @@ export async function startFromSnapshot(client, snapshotId, name, labels, envs)
 function refuseApplication(options = {}) {
     if (options.targetType === "application")
         throw new NotSupportedError("Forking into an application", "Fork into a sandbox and share its port with sandbox.previews.create.");
+    // Blaxel's application-fork routing: a sandbox fork has no use for them.
+    for (const key of ["port", "traffic", "customDomain", "prefix"])
+        if (options[key] !== undefined)
+            throw new NotSupportedError(`A fork's ${key}`, "Fork without it, then share a port of the copy with sandbox.previews.create({ metadata: { name }, spec: { port } }).");
 }
 /** A snapshot, as Blaxel's Snapshot class. */
 export class Snapshot {

package/dist/cli/logs.d.ts

@@ -0,0 +1,21 @@
+import type { ObservabilityClient } from "../products/logs.js";
+type Product = "logs" | "traces" | "alerts";
+type Args = {
+    positional: string[];
+    flags: Map<string, string[]>;
+};
+type Out = {
+    json: boolean;
+    tty?: boolean;
+    drain?: () => Promise<void>;
+    write(text: string): void;
+    error(text: string): void;
+};
+export declare const LOGS_HELP = "runtime logs tail <selector|app> [--since 1h] [--grep text] [--json] [--raw]\nruntime logs query '<LogQL>' [--from <time>] [--to <time>] [--limit <n>]\nruntime logs labels | values <label>\nruntime logs views ls|get|create|update|delete [id] [--body '<JSON>']\nruntime traces get <id> | search '<TraceQL>' | tags\nruntime traces views ls|get|create|update|delete [id] [--body '<JSON>']\nruntime logs ingest --body '<OTLP JSON>'\nruntime traces ingest --body '<OTLP JSON>'\nruntime alerts ls|get|create|update|delete|test|silence [id]\n  create/update: --body '<JSON: name, labels, query, condition, for, actions>'\n  silence: --until <RFC3339> [--reason <text>]\nEvery command takes --json. Writes take --idempotency-key <key>.\nOn a terminal, control characters in logs show as \\uXXXX; --raw prints them as written.";
+/** Same parsed argument and output ports as the existing CLI. No registration
+ * occurs here: the launch owner supplies a client only after launch. */
+export declare function logsProductCommand(product: Product, argv: string[], args: Args, out: Out, client: () => Promise<ObservabilityClient>, options?: {
+    signal?: AbortSignal;
+    now?: number;
+}): Promise<number>;
+export {};

package/dist/cli/logs.js

@@ -0,0 +1,188 @@
+import { RuntimeError } from "../errors.js";
+import { terminalSafe } from "../terminal.js";
+export const LOGS_HELP = `runtime logs tail <selector|app> [--since 1h] [--grep text] [--json] [--raw]
+runtime logs query '<LogQL>' [--from <time>] [--to <time>] [--limit <n>]
+runtime logs labels | values <label>
+runtime logs views ls|get|create|update|delete [id] [--body '<JSON>']
+runtime traces get <id> | search '<TraceQL>' | tags
+runtime traces views ls|get|create|update|delete [id] [--body '<JSON>']
+runtime logs ingest --body '<OTLP JSON>'
+runtime traces ingest --body '<OTLP JSON>'
+runtime alerts ls|get|create|update|delete|test|silence [id]
+  create/update: --body '<JSON: name, labels, query, condition, for, actions>'
+  silence: --until <RFC3339> [--reason <text>]
+Every command takes --json. Writes take --idempotency-key <key>.
+On a terminal, control characters in logs show as \\uXXXX; --raw prints them as written.`;
+const usage = (message) => new RuntimeError({ code: "usage", status: 0, message, hint: LOGS_HELP });
+function since(text, now) {
+    const match = /^(\d+)(s|m|h|d)$/.exec(text);
+    if (!match)
+        throw usage("Use --since with seconds, minutes, hours or days, such as 1h.");
+    const factors = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+    const at = now - Number(match[1]) * factors[match[2]];
+    if (!Number.isSafeInteger(at) || at < 0)
+        throw usage("--since is outside the supported time range.");
+    return new Date(at).toISOString();
+}
+/** Same parsed argument and output ports as the existing CLI. No registration
+ * occurs here: the launch owner supplies a client only after launch. */
+export async function logsProductCommand(product, argv, args, out, client, options = {}) {
+    const verb = argv[0];
+    const rest = args.positional.slice(1);
+    const flag = (name) => args.flags.get(name)?.at(-1);
+    const json = out.json || flag("json") === "true";
+    // On a terminal, what customers' programs wrote is shown escaped, JSON
+    // included (an escape is still valid JSON); --raw prints it as it is.
+    const safe = (text) => (out.tty && flag("raw") !== "true" ? terminalSafe(text) : text);
+    const lines = (text) => text.split("\n").map(safe).join("\n");
+    const print = (value, text) => out.write(json ? safe(JSON.stringify(value)) : lines(text ?? JSON.stringify(value, null, 2)));
+    const need = (value, name) => {
+        if (!value)
+            throw usage(`Give ${name}.`);
+        return value;
+    };
+    const body = () => {
+        try {
+            const value = JSON.parse(need(flag("body"), "--body with a JSON object"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw usage("--body must be a JSON object.");
+            return value;
+        }
+        catch (error) {
+            if (error instanceof RuntimeError)
+                throw error;
+            throw usage("--body is not valid JSON.");
+        }
+    };
+    const request = {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(flag("idempotency-key") ? { idempotencyKey: flag("idempotency-key") } : {}),
+    };
+    if (!verb || verb === "help" || verb === "--help") {
+        print({ usage: LOGS_HELP }, LOGS_HELP);
+        return 0;
+    }
+    const runtime = await client();
+    if ((product === "logs" || product === "traces") && verb === "views") {
+        const views = runtime[product].views;
+        const action = need(rest[0], "a views command");
+        if (action === "ls") {
+            const result = await views.list({}, request);
+            print({ data: result.data, nextCursor: result.nextCursor });
+        }
+        else if (action === "create")
+            print(await views.create(body(), request));
+        else {
+            const id = need(rest[1], "a view id");
+            if (action === "get")
+                print(await views.get(id, request));
+            else if (action === "update")
+                print(await views.update(id, body(), request));
+            else if (action === "delete") {
+                await views.delete(id, request);
+                print({ deleted: id });
+            }
+            else
+                throw usage(`Unknown views command: ${action}.`);
+        }
+        return 0;
+    }
+    if ((product === "logs" || product === "traces") && verb === "ingest") {
+        const input = body();
+        if (product === "logs") {
+            if (!Array.isArray(input.resourceLogs))
+                throw usage("OTLP logs need resourceLogs.");
+            const resourceLogs = input.resourceLogs;
+            print(await runtime.logs.ingest({ resourceLogs }, request));
+        }
+        else {
+            if (!Array.isArray(input.resourceSpans))
+                throw usage("OTLP spans need resourceSpans.");
+            const resourceSpans = input.resourceSpans;
+            print(await runtime.traces.ingest({ resourceSpans }, request));
+        }
+        return 0;
+    }
+    if (product === "logs") {
+        if (verb === "tail") {
+            const selector = need(rest[0], "a selector or app name");
+            let query = selector.trim().startsWith("{") ? selector : `{app=${JSON.stringify(selector)}}`;
+            if (flag("grep") !== undefined)
+                query += ` |= ${JSON.stringify(flag("grep"))}`;
+            for await (const event of runtime.logs.tail(query, {
+                ...request,
+                ...(flag("since") ? { start: since(flag("since"), options.now ?? Date.now()) } : {}),
+            })) {
+                if (json)
+                    out.write(safe(JSON.stringify(event)));
+                else if (event.gap) {
+                    const text = safe(`Logs expired between ${event.from} and ${event.to}; continuing from retained logs.`);
+                    out.write(out.tty ? `\x1b[2m${text}\x1b[0m` : text);
+                }
+                else {
+                    const time = safe(event.time);
+                    const text = safe(typeof event.body === "string" ? event.body : JSON.stringify(event.body));
+                    out.write(`${out.tty ? `\x1b[2m${time}\x1b[0m` : time} ${safe(event.severityText)} ${text}`);
+                }
+                await out.drain?.();
+            }
+        }
+        else if (verb === "query") {
+            const limit = flag("limit") === undefined ? undefined : Number(flag("limit"));
+            if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1))
+                throw usage("--limit must be a positive integer.");
+            print(await runtime.logs.queryRange({
+                query: need(rest[0], "a LogQL query"),
+                ...(flag("from") ? { start: flag("from") } : {}),
+                ...(flag("to") ? { end: flag("to") } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+            }, request));
+        }
+        else if (verb === "labels")
+            print(await runtime.logs.labels({}, request));
+        else if (verb === "values")
+            print(await runtime.logs.labelValues(need(rest[0], "a label name"), {}, request));
+        else
+            throw usage(`Unknown logs command: ${verb}.`);
+    }
+    else if (product === "traces") {
+        if (verb === "get")
+            print(await runtime.traces.get(need(rest[0], "a trace id"), request));
+        else if (verb === "search")
+            print(await runtime.traces.search(need(rest[0], "a TraceQL query"), request));
+        else if (verb === "tags")
+            print(await runtime.traces.tags(request));
+        else
+            throw usage(`Unknown traces command: ${verb}.`);
+    }
+    else {
+        if (verb === "ls") {
+            const result = await runtime.alerts.list({}, request);
+            print({ data: result.data, nextCursor: result.nextCursor });
+        }
+        else if (verb === "create")
+            print(await runtime.alerts.create(body(), request));
+        else {
+            const id = need(rest[0], "an alert id");
+            if (verb === "get")
+                print(await runtime.alerts.get(id, request));
+            else if (verb === "update")
+                print(await runtime.alerts.update(id, body(), request));
+            else if (verb === "delete") {
+                await runtime.alerts.delete(id, request);
+                print({ deleted: id });
+            }
+            else if (verb === "test")
+                print(await runtime.alerts.test(id, request));
+            else if (verb === "silence") {
+                const until = need(flag("until"), "--until with an RFC3339 time");
+                if (!/T.*(?:Z|[+-]\d\d:\d\d)$/.test(until) || !Number.isFinite(Date.parse(until)))
+                    throw usage("--until must be an RFC3339 time with timezone.");
+                print(await runtime.alerts.silence(id, { until, ...(flag("reason") ? { reason: flag("reason") } : {}) }, request));
+            }
+            else
+                throw usage(`Unknown alerts command: ${verb}.`);
+        }
+    }
+    return 0;
+}

package/dist/cli-extras.d.ts

@@ -22,9 +22,9 @@ export declare function lostOutput(result: {
     stdoutTruncated?: boolean;
     stderrTruncated?: boolean;
 }, id: string): string | undefined;
-/** Feeds `runtime sandbox shell` from standard input. When piped input ends,
+/** Feeds `runtime sandboxes 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`
+ * if the last line had none: `echo ls | runtime sandboxes 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. */
@@ -33,7 +33,7 @@ export declare function pipeShellInput(stdin: NodeJS.ReadableStream & {
 }, terminal: {
     write(data: Uint8Array | string): void;
 }): () => void;
-/** `runtime snapshot get`, as `runtime sandbox get` reads: one fact a line.
+/** `runtime snapshots get`, as `runtime sandboxes 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

@@ -13,12 +13,12 @@ export async function recordCommand(sbx, argv, out, kit) {
                 ...(integer(args, "max-seconds") ? { maxSeconds: integer(args, "max-seconds") } : {}),
                 ...(integer(args, "max-mib") ? { maxMiB: integer(args, "max-mib") } : {}),
             });
-            print(`Recording ${rec.id}. Stop it: ${me} sandbox desktop ${sbx.id} record stop ${rec.id}`, rec);
+            print(`Recording ${rec.id}. Stop it: ${me} sandboxes desktop ${sbx.id} record stop ${rec.id}`, rec);
             return 0;
         }
         case "stop": {
             const rec = await r.stop(need(rest[0], "the recording id"));
-            print(`Stopped ${rec.id}: ${(rec.bytes / 1_048_576).toFixed(1)} MiB (${rec.reason ?? "stopped"}). Fetch it: ${me} sandbox desktop ${sbx.id} record fetch ${rec.id}`, rec);
+            print(`Stopped ${rec.id}: ${(rec.bytes / 1_048_576).toFixed(1)} MiB (${rec.reason ?? "stopped"}). Fetch it: ${me} sandboxes desktop ${sbx.id} record fetch ${rec.id}`, rec);
             return 0;
         }
         case "ls": {
@@ -47,7 +47,7 @@ export async function recordCommand(sbx, argv, out, kit) {
             print("Deleted.", await r.delete(need(rest[0], "the recording id")));
             return 0;
     }
-    throw usage(`${me} sandbox desktop <id> record start|stop|ls|fetch|rm`);
+    throw usage(`${me} sandboxes desktop <id> record start|stop|ls|fetch|rm`);
 }
 export async function watchCommand(sbx, argv, out, kit) {
     const { parse, flag, has, need } = kit;
@@ -110,7 +110,7 @@ export async function mcpCommand(sbx, argv, out, kit) {
         case "start": {
             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");
+                throw usage("Name the servers: runtime sandboxes mcp <id> start github fetch");
             const scoped = (name) => {
                 const found = {};
                 for (const [key, value] of Object.entries(pairs(args, name))) {
@@ -134,7 +134,7 @@ export async function mcpCommand(sbx, argv, out, kit) {
                 ...(integer(args, "port") ? { port: integer(args, "port") } : {}),
                 ...(has(args, "replace") ? { replace: true } : {}),
             });
-            print(`${show(gw)}\nServers are installing; \`${me} sandbox mcp ${sbx.id}\` shows when they are ready.`, gw);
+            print(`${show(gw)}\nServers are installing; \`${me} sandboxes mcp ${sbx.id}\` shows when they are ready.`, gw);
             return 0;
         }
         case "status": {
@@ -146,7 +146,7 @@ export async function mcpCommand(sbx, argv, out, kit) {
             print("Stopped.", await sbx.mcp.stop());
             return 0;
     }
-    throw usage(`${me} sandbox mcp <id> start|status|stop, or ${me} sandbox mcp catalog`);
+    throw usage(`${me} sandboxes mcp <id> start|status|stop, or ${me} sandboxes mcp catalog`);
 }
 /** Standard input when it is piped or redirected from a file, read whole, up
  * to the API's 1 MiB; undefined for a terminal. A pipe that says nothing for
@@ -184,7 +184,7 @@ export async function pipedStdin(options = {}) {
             clearTimeout(quiet);
             size += chunk.length;
             if (size > limit)
-                return done(undefined, Object.assign(new Error(`Standard input is over ${limit / 1_048_576} MiB. Copy the file in with \`${me} sandbox cp\` and read it there.`), { code: "usage" }));
+                return done(undefined, Object.assign(new Error(`Standard input is over ${limit / 1_048_576} MiB. Copy the file in with \`${me} sandboxes cp\` and read it there.`), { code: "usage" }));
             chunks.push(chunk);
         };
         const onEnd = () => done(size ? new Uint8Array(Buffer.concat(chunks)) : undefined);
@@ -201,11 +201,11 @@ export async function pipedStdin(options = {}) {
 export function lostOutput(result, id) {
     if (!result.stdoutTruncated && !result.stderrTruncated)
         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 .`;
+    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} sandboxes cp ${id}:/workspace/out.txt .`;
 }
-/** Feeds `runtime sandbox shell` from standard input. When piped input ends,
+/** Feeds `runtime sandboxes 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`
+ * if the last line had none: `echo ls | runtime sandboxes 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. */
@@ -229,7 +229,7 @@ export function pipeShellInput(stdin, terminal) {
         stdin.off("end", onEnd);
     };
 }
-/** `runtime snapshot get`, as `runtime sandbox get` reads: one fact a line.
+/** `runtime snapshots get`, as `runtime sandboxes 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`;
@@ -249,7 +249,12 @@ export function describeSnapshot(s, table) {
                 : s.durability.state,
         ],
         ["created", s.createdAt],
-        ["kept until", `${s.expiresAt} (${s.retentionDays} days)`],
+        [
+            "kept until",
+            s.expiresAt === null
+                ? "kept while you have credit"
+                : `${s.expiresAt} (${s.retentionDays} days)`,
+        ],
         [
             "labels",
             Object.entries(labels)

package/dist/cli-words.d.ts

@@ -1,4 +1,5 @@
-import type { RuntimeError } from "./errors.js";
+import { RuntimeError } from "./errors.js";
+import type { ProductName } from "./product-names.js";
 import type { SandboxMetrics } from "./products/observability.js";
 /** A refusal of what a command sent, reworded for the command line: every
  * issue named by its option, since the CLI never prints details.issues, and
@@ -25,3 +26,11 @@ export declare function newestCpu(m: SandboxMetrics, now?: number): {
  * help` filed "help" as feedback, and `runtime support help` sent it to
  * support, until 30 September 2026. */
 export declare function topicHelp(help: string, command: string): string | null;
+/** A command line's product words (CLOUD.md section 4): the plural, or the
+ * singular as a typing shortcut, reach the product silently; an old word
+ * reaches it with `warning` to print, and from its date throws name_retired
+ * naming the new command. Anything else passes through. */
+export declare function productWords(argv: string[], now?: Date, table?: readonly ProductName[]): {
+    argv: string[];
+    warning?: string;
+};

package/dist/cli-words.js

@@ -1,3 +1,5 @@
+import { RuntimeError } from "./errors.js";
+import { cliWords } from "./product-renames.js";
 /* What the CLI says in its own words where the API's would mislead: the
    option a refusal is about rather than the request field it was sent as,
    one fact a line for a resource read, and the newest CPU reading a
@@ -133,3 +135,19 @@ export function topicHelp(help, command) {
     }
     return out.length ? out.join("\n") : null;
 }
+/** A command line's product words (CLOUD.md section 4): the plural, or the
+ * singular as a typing shortcut, reach the product silently; an old word
+ * reaches it with `warning` to print, and from its date throws name_retired
+ * naming the new command. Anything else passes through. */
+export function productWords(argv, now = new Date(), table) {
+    const found = cliWords(argv, now, table);
+    if (!found)
+        return { argv };
+    const { use } = found;
+    if (use.kind === "retired")
+        throw new RuntimeError({ ...use.error });
+    return {
+        argv: found.args,
+        ...(use.kind === "renamed" ? { warning: use.warning } : {}),
+    };
+}

package/dist/cli.d.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { RuntimeError } from "./errors.js";
-import type { Usage } from "./types.js";
+import type { OutOfMemory, Usage } from "./types.js";
 import type { SwitchProvider } from "./products/switching.js";
-import type { SecretRule } from "./products/secrets.js";
+import type { SecretRule, SecretScope } from "./products/secrets.js";
 type Out = {
     json: boolean;
     write: (text: string) => void;
@@ -30,7 +30,7 @@ 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 included usage and what each kind
+/** `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. */
 /** One row per resource, for a spreadsheet: when it ran, how big it was, how
@@ -38,14 +38,33 @@ export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out):
  * 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;
+/** What a person reads when the sandbox's out-of-memory killer ended a
+ * command: the API's message and hint, on standard error. A bare exit -9 (or
+ * 137) said nothing of memory until 9 October 2026. */
+export declare function outOfMemoryLines(memory: OutOfMemory | undefined): string | undefined;
 /** How to move a rival's code across, when one import does it. */
 export declare function dropInLines(provider: SwitchProvider | undefined): string[];
+/** A secret's value, from standard input only, so it never sits in shell
+ * history or a process list. Piped: everything, less one trailing newline.
+ * A terminal: one line, not shown. */
+/** A pasted secret as the header it becomes: no line breaks (a token copied
+ * from a terminal arrives wrapped), no bracketed-paste markers, no space at
+ * either end. 13 October 2026: Marc's pasted Claude token was refused as
+ * "not visible ASCII". A header cannot hold a line break, so none is lost. */
+export declare function cleanSecret(raw: string): 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[];
+/** `--only-label role=hub,tier=x --only-sandbox <id>`: a sandbox whose labels
+ * hold every pair of any one --only-label gets the secret, and so does each
+ * --only-sandbox. `--all-sandboxes`: every sandbox again. Nothing: undefined,
+ * so a replacement keeps the scope it has. */
+export declare function parseSecretScope(labels: string[] | undefined, sandboxes: string[] | undefined, all: boolean): SecretScope | undefined;
+/** Who gets a secret, in a few words. */
+export declare const scopeText: (only: SecretScope | undefined) => string;
 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>;