withruntime 0.11.2 → 0.12.0

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) };
     }));
 }
@@ -525,7 +575,9 @@ export class SandboxInstance {
      * 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
      * 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/logs.test.d.ts

@@ -0,0 +1 @@
+export {};

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