withruntime 0.11.1 → 0.12.0

package/dist/cli/logs.test.js

@@ -0,0 +1,272 @@
+import { expect, test } from "bun:test";
+import { logsProductCommand } from "./logs.js";
+import { terminalSafe } from "../terminal.js";
+import { logs, traces, alerts } from "../products/logs.js";
+import { Transport } from "../transport.js";
+import { InvalidRequestError } from "../errors.js";
+const input = {
+    name: "errors",
+    labels: {},
+    query: '{app="api"}',
+    condition: "above 5",
+    for: "5m",
+    actions: [],
+};
+const cases = [
+    ["logs", ["query", "{}"], { from: "1", to: "2", limit: "5" }, "GET", "/v1/logs/query_range"],
+    ["logs", ["labels"], {}, "GET", "/v1/logs/labels"],
+    ["logs", ["values", "app"], {}, "GET", "/v1/logs/labels/app/values"],
+    ["logs", ["ingest"], { body: '{"resourceLogs":[]}' }, "POST", "/v1/logs"],
+    ["traces", ["ingest"], { body: '{"resourceSpans":[]}' }, "POST", "/v1/traces"],
+    ["traces", ["get", "id"], {}, "GET", "/v1/traces/id"],
+    ["traces", ["search", "{}"], {}, "GET", "/v1/traces:search"],
+    ["traces", ["tags"], {}, "GET", "/v1/traces/tags"],
+    ["alerts", ["test", "id"], {}, "POST", "/v1/alerts/id/test"],
+    [
+        "alerts",
+        ["silence", "id"],
+        { until: "2026-10-07T00:00:00Z", reason: "maintenance" },
+        "POST",
+        "/v1/alerts/id/silence",
+    ],
+];
+for (const product of ["logs", "traces", "alerts"])
+    for (const verb of ["ls", "get", "create", "update", "delete"]) {
+        const collection = `/v1/${product}${product === "alerts" ? "" : "/views"}`;
+        cases.push([
+            product,
+            [
+                ...(product === "alerts" ? [] : ["views"]),
+                verb,
+                ...(["get", "update", "delete"].includes(verb) ? ["id"] : []),
+            ],
+            ["create", "update"].includes(verb) ? { body: JSON.stringify(input) } : {},
+            { ls: "GET", get: "GET", create: "POST", update: "PUT", delete: "DELETE" }[verb],
+            collection + (["get", "update", "delete"].includes(verb) ? "/id" : ""),
+        ]);
+    }
+function setup() {
+    const requests = [];
+    const transport = new Transport({
+        apiKey: "fake",
+        baseUrl: "https://fake.test",
+        maxRetries: 0,
+        fetch: (async (url, init) => {
+            requests.push({ url: new URL(url instanceof Request ? url.url : url), init: init ?? {} });
+            return Response.json({ ...input, id: "id", data: [], nextCursor: null, marker: "ok" });
+        }),
+    });
+    return {
+        client: { logs: logs(transport), traces: traces(transport), alerts: alerts(transport) },
+        requests,
+    };
+}
+for (const [product, positional, flags, method, path] of cases)
+    for (const mode of ["tty", "pipe", "json"])
+        test(`${product} ${positional.join(" ")} ${mode}`, async () => {
+            const { client, requests } = setup(), output = [];
+            const result = await logsProductCommand(product, positional, {
+                positional,
+                flags: new Map(Object.entries({ ...flags, "idempotency-key": "retry-key" }).map(([key, value]) => [
+                    key,
+                    [value],
+                ])),
+            }, {
+                json: mode === "json",
+                tty: mode === "tty",
+                write: (text) => output.push(text),
+                error: () => {
+                    throw new Error("unexpected stderr");
+                },
+            }, async () => client);
+            expect(result).toBe(0);
+            expect(requests).toHaveLength(1);
+            expect(requests[0].url.pathname).toBe(path);
+            expect(requests[0].init.method).toBe(method);
+            expect(output).toHaveLength(1);
+            expect(output[0]).not.toContain("\x1b");
+            const printed = JSON.parse(output[0]);
+            if (positional.includes("delete"))
+                expect(printed).toEqual({ deleted: "id" });
+            else if (positional.includes("ls"))
+                expect(printed).toEqual({ data: [], nextCursor: null });
+            else
+                expect(printed.marker).toBe("ok");
+            if (method !== "GET")
+                expect(new Headers(requests[0].init.headers).get("idempotency-key")).toBe("retry-key");
+            if (positional[0] === "query")
+                expect(Object.fromEntries(requests[0].url.searchParams)).toEqual({
+                    query: "{}",
+                    start: "1",
+                    end: "2",
+                    limit: "5",
+                });
+        });
+for (const mode of ["tty", "pipe", "json"])
+    test(`tail ${mode}, selector escaping, gap and backpressure`, async () => {
+        const { client } = setup();
+        const output = [];
+        let drained = 0;
+        const events = [
+            {
+                time: "12:00",
+                timeUnixNano: "1",
+                severity: 9,
+                severityText: "INFO",
+                labels: {},
+                attributes: {},
+                traceId: null,
+                spanId: null,
+                body: "line\x1b[2J\nnext",
+                cursor: "one",
+            },
+            { gap: true, from: "old", to: "kept" },
+        ];
+        let received;
+        client.logs.tail = async function* (query, options) {
+            received = { query, options };
+            yield* events;
+        };
+        const positional = ["tail", 'app"name'];
+        await logsProductCommand("logs", positional, {
+            positional,
+            flags: new Map([
+                ["since", ["1h"]],
+                ["grep", ['a"b']],
+            ]),
+        }, {
+            json: mode === "json",
+            tty: mode === "tty",
+            write: (text) => output.push(text),
+            error() { },
+            async drain() {
+                drained++;
+            },
+        }, async () => client, { now: Date.parse("2026-10-06T12:00:00Z") });
+        expect(received).toEqual({
+            query: '{app="app\\"name"} |= "a\\"b"',
+            options: { start: "2026-10-06T11:00:00.000Z" },
+        });
+        expect(drained).toBe(2);
+        if (mode === "json")
+            expect(output.map((text) => JSON.parse(text))).toEqual(events);
+        else {
+            if (mode === "tty")
+                expect(output[0]).toContain("line\\u001b[2J\\u000anext");
+            else
+                expect(output[0]).toContain("line\u001b[2J\nnext");
+            expect(output[1]).toContain("Logs expired");
+            expect(output[1].includes("\x1b[2m")).toBe(mode === "tty");
+        }
+    });
+test("tail survives an actual fake-fetch disconnect through the SDK", async () => {
+    let calls = 0;
+    const cursors = [], output = [];
+    const abort = new AbortController();
+    const transport = new Transport({
+        apiKey: "fake",
+        baseUrl: "https://fake.test",
+        fetch: (async (input) => {
+            cursors.push(new URL(input instanceof Request ? input.url : input).searchParams.get("cursor"));
+            const cursor = String(++calls);
+            return new Response(`id: ${cursor}\ndata: ${JSON.stringify({ time: "now", timeUnixNano: "1", labels: {}, body: "same", severityText: "INFO" })}\n\n`, { headers: { "content-type": "text/event-stream" } });
+        }),
+    });
+    const client = { logs: logs(transport), traces: traces(transport), alerts: alerts(transport) };
+    const run = logsProductCommand("logs", ["tail", "{}"], { positional: ["tail", "{}"], flags: new Map() }, {
+        json: true,
+        write(text) {
+            output.push(text);
+            if (output.length === 2)
+                abort.abort(new Error("done"));
+        },
+        error() { },
+    }, async () => client, { signal: abort.signal });
+    await expect(run).rejects.toThrow("done");
+    expect(cursors).toEqual([null, "1"]);
+    expect(output.map((text) => JSON.parse(text).cursor)).toEqual(["1", "2"]);
+});
+for (const [product, positional, flags] of [
+    ["logs", ["query", "{}"], { limit: "0" }],
+    ["logs", ["query"], {}],
+    ["logs", ["tail", "api"], { since: "forever" }],
+    ["alerts", ["create"], { body: "[1]" }],
+    ["alerts", ["create"], { body: "broken" }],
+    ["alerts", ["silence", "id"], { until: "tomorrow" }],
+    ["logs", ["ingest"], { body: "{}" }],
+    ["traces", ["ingest"], { body: "{}" }],
+    ["alerts", ["oops", "id"], {}],
+])
+    test(`refuses ${positional.join(" ")} ${JSON.stringify(flags)}`, async () => {
+        const { client, requests } = setup();
+        await expect(logsProductCommand(product, positional, { positional, flags: new Map(Object.entries(flags).map(([key, value]) => [key, [value]])) }, { json: true, write() { }, error() { } }, async () => client)).rejects.toMatchObject({ code: "usage", hint: expect.any(String) });
+        expect(requests).toHaveLength(0);
+    });
+test("help needs no credentials", async () => {
+    const output = [];
+    await logsProductCommand("logs", ["help"], { positional: ["help"], flags: new Map() }, { json: false, write: (text) => output.push(text), error() { } }, async () => {
+        throw new Error("credentials requested");
+    });
+    expect(output[0]).toContain("\nruntime logs query");
+});
+test("typed failures reach the main CLI's JSON error renderer unchanged", async () => {
+    const { client } = setup();
+    const failure = new InvalidRequestError({
+        code: "query_limit",
+        message: "Too broad",
+        status: 400,
+        hint: "Narrow the time range.",
+    });
+    client.logs.queryRange = async () => {
+        throw failure;
+    };
+    await expect(logsProductCommand("logs", ["query", "{}"], { positional: ["query", "{}"], flags: new Map() }, {
+        json: true,
+        write() {
+            throw new Error("Do not print success on failure");
+        },
+        error() { },
+    }, async () => client)).rejects.toBe(failure);
+});
+test("human JSON keeps formatting but escapes C1 terminal controls", async () => {
+    const { client } = setup();
+    const output = [];
+    client.traces.get = async () => ({ resourceSpans: [], marker: "\u009b2J" });
+    await logsProductCommand("traces", ["get", "id"], { positional: ["get", "id"], flags: new Map() }, { json: false, tty: true, write: (text) => output.push(text), error() { } }, async () => client);
+    expect(output[0]).not.toContain("\u009b");
+    expect(output[0]).toContain("\\u009b");
+    expect(output[0]).toContain("\n");
+    expect(JSON.parse(output[0]).marker).toBe("\u009b2J");
+});
+test("a terminal shows what customers' programs wrote, escaped, and nothing acts", async () => {
+    // Clipboard (OSC 52), a forged link (OSC 8), screen clear, the one-byte C1
+    // CSI and a right-to-left override; tab stays.
+    const hostile = "a\tb \x1b]52;c;c2VjcmV0\x07 \x1b]8;;https://evil.test\x07ok\x1b]8;;\x07 \x1b[2J \u009b2J \u202eevil";
+    const shown = terminalSafe(hostile);
+    // eslint-disable-next-line no-control-regex -- the test looks for control characters
+    expect(shown).not.toMatch(/[\x00-\x08\x0a-\x1f\x7f-\x9f\u202e]/);
+    expect(shown).toContain("a\tb");
+    expect(shown).toContain("\\u001b]52;c;c2VjcmV0\\u0007");
+    expect(shown).toContain("\\u009b2J \\u202eevil");
+    const run = async (tty, raw, json) => {
+        const { client } = setup();
+        client.logs.tail = async function* () {
+            yield { cursor: "c", time: "t", severityText: "INFO", body: hostile, labels: {} };
+        };
+        const output = [];
+        const flags = new Map(raw ? [["raw", ["true"]]] : []);
+        await logsProductCommand("logs", ["tail", "{}"], { positional: ["tail", "{}"], flags }, { json, tty, write: (text) => output.push(text), error() { } }, async () => client);
+        return output.join("\n");
+    };
+    for (const json of [false, true]) {
+        const onTerminal = await run(true, false, json);
+        expect(onTerminal).not.toContain("\x1b]");
+        expect(onTerminal).not.toContain("\u009b");
+        expect(onTerminal).not.toContain("\u202e");
+        if (json)
+            expect(JSON.parse(onTerminal).body).toBe(hostile);
+        // A pipe, or --raw on a terminal, gets exactly what was written.
+        expect(await run(false, false, json)).toContain(json ? JSON.stringify(hostile) : hostile);
+        expect(await run(true, true, json)).toContain(json ? JSON.stringify(hostile) : hostile);
+    }
+});

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,6 +1,6 @@
 #!/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";
 type Out = {
@@ -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 trial and what each kind
+/** `runtime usage` for a person: the balance, the included 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,6 +38,10 @@ 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[];
 /** `--allow` values as secret rules: each is `[METHOD[,METHOD]...] PATH`, and