withruntime 0.8.4 → 0.9.0

package/dist/api-defaults.js

@@ -0,0 +1,22 @@
+/* Every value this SDK sends the API for a bounded time field when the caller
+ * names none, in one place. packages/cloud/tests/sdk-defaults.test.ts holds
+ * each inside the range the API's registry gives that field, and the same
+ * names in the Python, Go, Java and Ruby SDKs to theirs. The suffix is the
+ * unit; a new default goes here, under a name that test maps to its field. */
+/** A server-side wait for a state (`GET /v1/sandboxes/{id}?waitFor=`). */
+export const WAIT_FOR_TIMEOUT_SECONDS = 60;
+/** A streamed exec's command limit when none is given: the API's longest. */
+export const STREAMED_EXEC_TIMEOUT_MS = 86_400_000;
+/** The lease keepAlive keeps ahead of now, and so the most it extends by. */
+export const KEEP_ALIVE_MARGIN_SECONDS = 600;
+/** A webhook watch runs until stopped. */
+export const WEBHOOK_WATCH_TIMEOUT_MS = 0;
+/** A job run's limit, and the time added to it for its sandbox to start. */
+export const JOB_TIMEOUT_SECONDS = 1800;
+export const JOB_START_SECONDS = 60;
+/** A command the framework-free tools run without a timeout of its own. */
+export const TOOL_EXEC_TIMEOUT_SECONDS = 300;
+/** A command the AI SDK harness runs without a timeout of its own. */
+export const AI_HARNESS_COMMAND_TIMEOUT_MS = 3_600_000;
+/** A command the OpenAI Agents sandbox runs without a timeout of its own. */
+export const OPENAI_AGENTS_EXEC_TIMEOUT_MS = 3_600_000;

package/dist/blaxel/preview.d.ts

@@ -98,7 +98,7 @@ export declare class SandboxPreviews {
     /** The named preview, or a new one when there is none. */
     createIfNotExists(preview: Preview, force?: boolean): Promise<SandboxPreview>;
     get(previewName: string): Promise<SandboxPreview>;
-    /** Stops sharing the port; open connections close within seconds. */
+    /** Stops sharing the port; its open connections are closed before this returns. */
     delete(previewName: string): Promise<Preview>;
 }
 /** A private preview of `port` with a token that lasts a while, for

package/dist/blaxel/preview.js

@@ -193,7 +193,7 @@ export class SandboxPreviews {
         const found = await this.#ctx.run((runtime) => runtime.previews.get(port));
         return new SandboxPreview(modelOf(found, previewName, this.sandboxName), this.#ctx);
     }
-    /** Stops sharing the port; open connections close within seconds. */
+    /** Stops sharing the port; its open connections are closed before this returns. */
     async delete(previewName) {
         const port = this.#portOf(previewName);
         if (port === undefined)

package/dist/blaxel/process.d.ts

@@ -87,7 +87,7 @@ export declare class SandboxProcess {
      * process running; with it, once the process ends, with its output. */
     exec(request: ProcessRequest | ProcessRequestWithLog): Promise<PostProcessResponse | ProcessResponseWithLog>;
     /** The process, with the output it has written so far. */
-    get(identifier: string, _options?: {
+    get(identifier: string, options?: {
         signal?: AbortSignal;
         retry?: boolean;
     }): Promise<GetProcessByIdentifierResponse>;

package/dist/blaxel/process.js

@@ -182,6 +182,8 @@ export class SandboxProcess {
         const startedAt = new Date().toISOString();
         const run = async () => {
             for await (const event of runtime.execStream(line, { ...options, signal: abort.signal })) {
+                if (event.type === "truncated")
+                    throw responseError(502, "Some command output is no longer available.");
                 if (event.type === "start") {
                     id = event.processId;
                     this.#remember(id, meta);
@@ -324,12 +326,15 @@ export class SandboxProcess {
         const runtime = await this.#ctx.live();
         const abort = new AbortController();
         const forward = () => abort.abort();
+        signal?.throwIfAborted();
         signal?.addEventListener("abort", forward, { once: true });
         try {
             for await (const event of runtime.processes.follow(found.id, {
                 cursor: 0,
                 signal: abort.signal,
             })) {
+                if (event.type === "truncated")
+                    throw responseError(502, "Some command output is no longer available.");
                 if (event.type === "stdout" || event.type === "stderr") {
                     out[event.type] += event.data;
                     out.logs += event.data;
@@ -362,9 +367,10 @@ export class SandboxProcess {
         return out;
     }
     /** The process, with the output it has written so far. */
-    async get(identifier, _options = {}) {
+    async get(identifier, options = {}) {
+        options.signal?.throwIfAborted();
         const found = await this.#find(identifier);
-        const out = await this.#output(found, false);
+        const out = await this.#output(found, false, options.signal);
         return this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
     }
     /** Waits for the process to end (at most `maxWait` ms, -1 for no limit) and
@@ -381,6 +387,7 @@ export class SandboxProcess {
             throw late();
         const abort = new AbortController();
         const forward = () => abort.abort(signal?.reason);
+        signal?.throwIfAborted();
         signal?.addEventListener("abort", forward, { once: true });
         const timer = maxWait === -1 ? undefined : setTimeout(() => abort.abort(late()), maxWait);
         try {
@@ -476,6 +483,8 @@ export class SandboxProcess {
                     cursor: 0,
                     signal: abort.signal,
                 })) {
+                    if (event.type === "truncated")
+                        throw responseError(502, "Some command output is no longer available.");
                     if (event.type === "stdout" || event.type === "stderr") {
                         const lines = (partial[event.type] + event.data).split(/\r?\n/);
                         partial[event.type] = lines.pop();

package/dist/cli-words.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeError } from "./errors.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
+ * a hint that names the options rather than the request's fields. Anything
+ * else is left as the API said it. */
+export declare function cliRefusal(error: RuntimeError): {
+    message: string;
+    hint?: string;
+};
+/** A resource read as one fact a line, as `sandbox get` prints: a list
+ * joined, a nested record as its own facts, nothing as `-`. */
+export declare function describeRecord(record: Record<string, unknown>, table: (rows: string[][]) => string): string;
+/** The newest CPU reading the metrics hold, and how old it is. `latest` is
+ * the last sample, which can carry no CPU figure (the first after a wake has
+ * nothing to compare with), while the points before it do; "no reading"
+ * above a sparkline of readings contradicted itself. */
+export declare function newestCpu(m: SandboxMetrics, now?: number): {
+    percent: number;
+    cores: number | null;
+    ago: string | null;
+} | null;
+/** The lines of the top-level help about one command, `  feedback ...` and
+ * the lines that continue it, or null when it has none. `runtime feedback
+ * 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;

package/dist/cli-words.js

@@ -0,0 +1,135 @@
+/* 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
+   sandbox's metrics hold. Kept out of cli.ts, which many hands edit. */
+/** The request fields a command line sets, by the option that sets them.
+ * An amount in microdollars is typed in dollars. */
+const OPTIONS = {
+    name: { flag: "--name" },
+    labels: { flag: "--label" },
+    env: { flag: "--env" },
+    region: { flag: "--region" },
+    vcpu: { flag: "--vcpu" },
+    memoryMiB: { flag: "--memory" },
+    diskMiB: { flag: "--disk" },
+    cpu: { flag: "--cpu" },
+    cpuFloorMillis: { flag: "--cpu-floor" },
+    timeoutSeconds: { flag: "--timeout" },
+    onLeaseEnd: { flag: "--on-timeout" },
+    idlePauseSeconds: { flag: "--idle-pause" },
+    autoWake: { flag: "--no-auto-wake / --auto-wake" },
+    persistent: { flag: "--persistent" },
+    funding: { flag: "--trial / --paid" },
+    image: { flag: "--image" },
+    snapshot: { flag: "--snapshot" },
+    volumes: { flag: "--volume" },
+    network: { flag: "--allow / --deny / --connect / --no-internet" },
+    maxCostMicros: { flag: "--max-cost", micros: true },
+    maxTotalCostMicros: { flag: "--max-total-cost", micros: true },
+};
+const usd = (micros) => `$${(micros / 1e6).toLocaleString("en-US", { maximumFractionDigits: 6 })}`;
+/** One issue the API found in a request, in the command line's words:
+ * `body.timeoutSeconds must be at least 60` is `--timeout must be at least 60`. */
+function issueWords(path, message) {
+    const field = /^(?:\$\.)?body\.([A-Za-z]+)/.exec(path)?.[1];
+    const option = field && Object.hasOwn(OPTIONS, field) ? OPTIONS[field] : undefined;
+    if (!option) {
+        const where = path.replace(/^\$\.?/, "").replace(/^(body|query|path)\./, "") || "the request";
+        return `${where} ${message}`;
+    }
+    const said = option.micros ? message.replace(/-?\d+(?:\.\d+)?/g, (n) => usd(Number(n))) : message;
+    return `${option.flag} ${said}`;
+}
+/** 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
+ * a hint that names the options rather than the request's fields. Anything
+ * else is left as the API said it. */
+export function cliRefusal(error) {
+    const issues = error.details?.issues;
+    if (error.code === "invalid_request" && Array.isArray(issues) && issues.length) {
+        const lines = issues
+            .filter((i) => typeof i.path === "string" && typeof i.message === "string")
+            .map((i) => issueWords(i.path, i.message));
+        if (lines.length)
+            return {
+                message: lines.length === 1 ? `${lines[0]}.` : lines.map((l) => `\n  ${l}`).join(""),
+                hint: "Change what is named above and run the command again.",
+            };
+    }
+    const field = typeof error.details?.field === "string" ? error.details.field : "";
+    const option = Object.hasOwn(OPTIONS, field) ? OPTIONS[field] : undefined;
+    if (option && !option.micros && error.message.includes(field)) {
+        const named = new RegExp(`\\b${field}\\b`, "g");
+        return {
+            message: error.message.replace(named, option.flag),
+            ...(error.hint ? { hint: error.hint.replace(named, option.flag) } : {}),
+        };
+    }
+    return { message: error.message, ...(error.hint ? { hint: error.hint } : {}) };
+}
+/** A resource read as one fact a line, as `sandbox get` prints: a list
+ * joined, a nested record as its own facts, nothing as `-`. */
+export function describeRecord(record, table) {
+    const rows = [];
+    const cell = (value) => {
+        if (value === null || value === undefined || value === "")
+            return "-";
+        if (Array.isArray(value))
+            return value.length
+                ? value.map((v) => (v && typeof v === "object" ? JSON.stringify(v) : String(v))).join(", ")
+                : "-";
+        // A string as it is; a number, a boolean or a record as JSON writes it.
+        return typeof value === "string" ? value : JSON.stringify(value);
+    };
+    const add = (prefix, value) => {
+        for (const [key, v] of Object.entries(value)) {
+            const name = prefix ? `${prefix}.${key}` : key;
+            if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length <= 8)
+                add(name, v);
+            else
+                rows.push([name, cell(v)]);
+        }
+    };
+    add("", record);
+    return table(rows);
+}
+/** The newest CPU reading the metrics hold, and how old it is. `latest` is
+ * the last sample, which can carry no CPU figure (the first after a wake has
+ * nothing to compare with), while the points before it do; "no reading"
+ * above a sparkline of readings contradicted itself. */
+export function newestCpu(m, now = Date.now()) {
+    if (m.latest?.cpuPercent != null)
+        return { percent: m.latest.cpuPercent, cores: m.latest.cpuCores, ago: null };
+    for (let i = m.points.length - 1; i >= 0; i--) {
+        const p = m.points[i];
+        if (p.cpuPercent == null)
+            continue;
+        const seconds = Math.max(0, Math.round((now - Date.parse(p.at)) / 1000));
+        const ago = seconds < 90
+            ? `${seconds} s ago`
+            : seconds < 5400
+                ? `${Math.round(seconds / 60)} min ago`
+                : `${Math.round(seconds / 3600)} h ago`;
+        return { percent: p.cpuPercent, cores: p.cpuCores, ago };
+    }
+    return null;
+}
+/** The lines of the top-level help about one command, `  feedback ...` and
+ * the lines that continue it, or null when it has none. `runtime feedback
+ * help` filed "help" as feedback, and `runtime support help` sent it to
+ * support, until 30 September 2026. */
+export function topicHelp(help, command) {
+    const lines = help.split("\n");
+    const out = [];
+    let inside = false;
+    for (const line of lines) {
+        const starts = line.startsWith(`  ${command} `) || line === `  ${command}`;
+        if (starts)
+            inside = true;
+        else if (inside && !/^ {3,}\S/.test(line))
+            inside = false;
+        if (inside)
+            out.push(line);
+    }
+    return out.length ? out.join("\n") : null;
+}