withruntime 0.6.1 → 0.7.1

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.6.1";
+export declare const VERSION = "0.7.1";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export type RequestOptions = {
     /** Sent as Idempotency-Key. Omit it: the SDK makes one per call and keeps
@@ -30,6 +30,9 @@ export type Call = RequestOptions & {
      * full trial, a full quota, a full region. Then the refusal is thrown as
      * it came. Only a create sets it; 0 or absent fails at once. */
     waitForCapacityMs?: number;
+    /** Called each time a call waits for room, with the refusal it is waiting
+     * out and how long it will sleep before sending the call again. */
+    onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
 };
 export declare function apiOrigin(value: string): string;
 export declare function encodeQuery(query: Query | undefined): string;
@@ -66,10 +69,23 @@ export declare class Transport {
     send(call: Call): Promise<Response>;
     json<T>(call: Call): Promise<T>;
     bytes(call: Call): Promise<Uint8Array>;
+    /** A file's bytes, read whole and checked: the API says a body's length
+     * (x-content-length) and, when small, its SHA-256 (x-content-sha256) before
+     * sending it, and a body that falls short or differs is read again, twice,
+     * then refused. Nothing between the API and here reliably turns a stream
+     * cut part way into an error: on 25 September 2026 a 50 MB file came back
+     * 29 MB long, exit 0. */
+    fileBytes(call: Call): Promise<Uint8Array>;
+    /** A file's bytes as they arrive, for files too big to hold. The stream
+     * errors with `download_incomplete` if it ends short of the length the API
+     * promised; it is never retried part way. */
+    fileStream(call: Call): Promise<ReadableStream<Uint8Array>>;
     /** Newline-delimited JSON events, as they arrive. */
     events<T>(call: Call): AsyncGenerator<T>;
     /** A WebSocket to an API path, authenticated with the same key. */
     websocket(path: string, query?: Query): Promise<WebSocket>;
 }
+/** A download that ended short of (or past) the length the API promised. */
+export declare function incompleteDownload(got: number, expected: number): RuntimeError;
 /** No key given, none in RUNTIME_API_KEY, and none saved by `runtime login`. */
 export declare function missingKey(): RuntimeError;

package/dist/transport.js

@@ -1,6 +1,6 @@
 import { ConnectionError, errorFor, RuntimeError, WAITS_FOR_ROOM } from "./errors.js";
 import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
-export const VERSION = "0.6.1";
+export const VERSION = "0.7.1";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);
@@ -198,8 +198,22 @@ export class Transport {
                 await sleep(backoff(attempt), signal);
                 continue;
             }
-            if (response.ok)
+            /* An answer that took longer than the API holds its headers (90 s)
+               comes as a 200 sent early, and then its JSON: the answer, or
+               {"error": ...} when the work failed after the status went
+               (runtime-late-answer, api.md). Either way it is read here, so a
+               failure is thrown as the error it is, never returned as a success. */
+            let late;
+            if (response.ok && response.headers.get("runtime-late-answer") === "true") {
+                const text = await response.text();
+                const failed = lateFailure(text);
+                if (failed === undefined)
+                    return new Response(text, { headers: response.headers });
+                late = { status: failed, text };
+            }
+            else if (response.ok)
                 return response;
+            const status = late?.status ?? response.status;
             // Runtime never answers 407: it is a proxy refusing the tunnel, which
             // Bun's fetch hands back as a response rather than an error.
             if (response.status === 407 && this.#routed) {
@@ -213,15 +227,15 @@ export class Transport {
                     ...(key ? { idempotencyKey: key } : {}),
                 });
             }
-            const text = await response.text();
+            const text = late?.text ?? (await response.text());
             let parsed = null;
             try {
                 parsed = JSON.parse(text);
             }
             catch {
-                parsed = { error: { message: text.slice(0, 500) || `HTTP ${response.status}` } };
+                parsed = { error: { message: text.slice(0, 500) || `HTTP ${status}` } };
             }
-            const error = errorFor(response.status, parsed, key);
+            const error = errorFor(status, parsed, key);
             // A full house: wait for a slot or for room, then send the same call
             // again. A request that can never fit (a fork of more copies than the
             // trial runs) is not waited for.
@@ -232,10 +246,12 @@ export class Transport {
                 const left = roomUntil - performance.now();
                 if (left <= 0)
                     throw error;
-                await sleep(Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++)), signal);
+                const pause = Math.min(left, error.retryAfterMs ?? roomBackoff(roomAttempt++));
+                call.onCapacityWait?.(error, pause);
+                await sleep(pause, signal);
                 continue;
             }
-            const retryable = [429, 502, 503, 504].includes(response.status) && !DELIBERATE.has(error.code);
+            const retryable = [429, 502, 503, 504].includes(status) && !DELIBERATE.has(error.code);
             if (!retry || !retryable || attempt >= this.#maxRetries)
                 throw error;
             const header = Number(response.headers.get("retry-after"));
@@ -263,6 +279,54 @@ export class Transport {
             this.#slots.give();
         }
     }
+    /** A file's bytes, read whole and checked: the API says a body's length
+     * (x-content-length) and, when small, its SHA-256 (x-content-sha256) before
+     * sending it, and a body that falls short or differs is read again, twice,
+     * then refused. Nothing between the API and here reliably turns a stream
+     * cut part way into an error: on 25 September 2026 a 50 MB file came back
+     * 29 MB long, exit 0. */
+    async fileBytes(call) {
+        for (let attempt = 0;; attempt++) {
+            await this.#slots.take();
+            let failure;
+            try {
+                const response = await this.send(call);
+                const body = new Uint8Array(await response.arrayBuffer());
+                const problem = await checkBody(response.headers, body);
+                if (!problem)
+                    return body;
+                failure = problem;
+            }
+            finally {
+                this.#slots.give();
+            }
+            if (attempt >= 2 || call.signal?.aborted)
+                throw failure;
+            await sleep(backoff(attempt), call.signal);
+        }
+    }
+    /** A file's bytes as they arrive, for files too big to hold. The stream
+     * errors with `download_incomplete` if it ends short of the length the API
+     * promised; it is never retried part way. */
+    async fileStream(call) {
+        const response = await this.send(call);
+        const expected = promisedLength(response.headers);
+        const body = response.body ?? new ReadableStream({ start: (c) => c.close() });
+        let got = 0;
+        return body.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                got += chunk.byteLength;
+                if (expected !== undefined && got > expected)
+                    controller.error(incompleteDownload(got, expected));
+                else
+                    controller.enqueue(chunk);
+            },
+            flush(controller) {
+                if (expected !== undefined && got !== expected)
+                    controller.error(incompleteDownload(got, expected));
+            },
+        }));
+    }
     /** Newline-delimited JSON events, as they arrive. */
     async *events(call) {
         const response = await this.send({ ...call, accept: "application/x-ndjson" });
@@ -305,6 +369,59 @@ export class Transport {
         });
     }
 }
+/** The status a late answer's body failed with, or undefined when it is an
+ * answer. The body is the error the API would have sent as its status. */
+function lateFailure(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return 502;
+    }
+    // An API error is a body of `error` alone, with a code; an answer may carry
+    // an `error` of its own (a code cell's exception), next to other fields.
+    if (!body || typeof body !== "object" || Object.keys(body).length !== 1)
+        return undefined;
+    const error = body.error;
+    if (!error || typeof error !== "object" || typeof error.code !== "string")
+        return undefined;
+    const status = error.status;
+    return typeof status === "number" && status >= 400 ? status : 500;
+}
+function promisedLength(headers) {
+    const value = headers.get("x-content-length");
+    return value !== null && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+/** A download that ended short of (or past) the length the API promised. */
+export function incompleteDownload(got, expected) {
+    return new RuntimeError({
+        message: `The download ended at ${got} of ${expected} bytes.`,
+        code: "download_incomplete",
+        status: 0,
+        hint: "Read the file again; nothing was written for this read. If it keeps happening, report it with `npx withruntime feedback`.",
+        details: { received: got, expected },
+    });
+}
+/** Why a whole body cannot be trusted, or undefined when it can. */
+async function checkBody(headers, body) {
+    const expected = promisedLength(headers);
+    if (expected !== undefined && body.byteLength !== expected)
+        return incompleteDownload(body.byteLength, expected);
+    const sha256 = headers.get("x-content-sha256");
+    if (!sha256)
+        return undefined;
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", body));
+    const hex = Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (hex === sha256.toLowerCase())
+        return undefined;
+    return new RuntimeError({
+        message: "The file's bytes did not match the SHA-256 the API sent with them.",
+        code: "download_incomplete",
+        status: 0,
+        hint: "Read the file again. If it keeps happening, report it with `npx withruntime feedback`.",
+    });
+}
 /** No key given, none in RUNTIME_API_KEY, and none saved by `runtime login`. */
 export function missingKey() {
     return new RuntimeError({

package/dist/types.d.ts

@@ -100,8 +100,6 @@ export type CreateSandbox = {
         path: string;
         mode?: "rw" | "snapshot";
     }[];
-    /** Anything a newer server accepts (image, snapshotId, volumes, network...). */
-    [field: string]: unknown;
 };
 export type CommandResult = {
     exitCode: number | null;

package/dist/wallet.d.ts

@@ -0,0 +1,30 @@
+import type { Topup } from "./products/billing.js";
+export type WalletOptions = {
+    /** Default: RUNTIME_AUTH_URL, then https://withruntime.com. */
+    authUrl?: string;
+    fetch?: typeof fetch;
+};
+export type OpenedWalletAccount = Topup & {
+    orgId: string;
+    /** The only way to this account's key, shown once. Keep it secret. */
+    claimCode: string;
+};
+export type WalletClaim = {
+    status: "paid";
+    orgId: string;
+    apiKey: string;
+} | {
+    status: Exclude<Topup["status"], "paid">;
+    orgId: string;
+    topup: Topup | null;
+};
+/** Opens an account and a stablecoin top-up of `usd` dollars ($10 to $10,000).
+ *  `acceptTerms` must be true: opening one means agreeing to
+ *  https://withruntime.com/legal/terms, so ask the person you work for first. */
+export declare function openWalletAccount(input: {
+    usd: number;
+    acceptTerms: boolean;
+}, options?: WalletOptions): Promise<OpenedWalletAccount>;
+/** Exchanges a paid account's claim code for its API key, once. Until the
+ *  payment arrives it answers the top-up's status instead; call it again. */
+export declare function claimWalletAccount(claimCode: string, options?: WalletOptions): Promise<WalletClaim>;

package/dist/wallet.js

@@ -0,0 +1,48 @@
+import { RuntimeError } from "./errors.js";
+import { apiOrigin } from "./transport.js";
+function origin(options) {
+    const env = typeof process === "undefined" ? {} : process.env;
+    return apiOrigin(options.authUrl ?? env.RUNTIME_AUTH_URL ?? "https://withruntime.com");
+}
+async function post(options, path, body) {
+    const fetcher = options.fetch ?? fetch;
+    let response;
+    try {
+        response = await fetcher(`${origin(options)}${path}`, {
+            method: "POST",
+            redirect: "error",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (cause) {
+        throw new RuntimeError({
+            message: `No answer from ${origin(options)}.`,
+            code: "network",
+            status: 0,
+            hint: "Retry in a minute.",
+            cause,
+        });
+    }
+    const answer = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        throw new RuntimeError({
+            message: answer.error ?? `The request failed (HTTP ${response.status}).`,
+            code: answer.code ?? (response.status === 429 ? "rate_limited" : "request_failed"),
+            status: response.status,
+        });
+    return [response.status, answer];
+}
+/** Opens an account and a stablecoin top-up of `usd` dollars ($10 to $10,000).
+ *  `acceptTerms` must be true: opening one means agreeing to
+ *  https://withruntime.com/legal/terms, so ask the person you work for first. */
+export async function openWalletAccount(input, options = {}) {
+    const [, opened] = await post(options, "/api/wallet/topups", input);
+    return opened;
+}
+/** Exchanges a paid account's claim code for its API key, once. Until the
+ *  payment arrives it answers the top-up's status instead; call it again. */
+export async function claimWalletAccount(claimCode, options = {}) {
+    const [, claim] = await post(options, "/api/wallet/claim", { claimCode });
+    return claim;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "withruntime",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "license": "Apache-2.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
@@ -69,7 +69,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -110,14 +110,25 @@
     "registry": "https://registry.npmjs.org/"
   },
   "description": "Runtime Cloud: one client, CLI and MCP bridge for every Runtime product. Sandboxes first.",
+  "homepage": "https://withruntime.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withruntime/runtime.git",
+    "directory": "packages/cloud-sdk"
+  },
+  "bugs": "https://github.com/withruntime/runtime/issues",
   "sideEffects": false,
   "keywords": [
     "sandbox",
     "cloud",
     "agents",
+    "ai-agents",
     "mcp",
     "microvm",
-    "code-execution"
+    "firecracker",
+    "code-execution",
+    "code-interpreter",
+    "llm"
   ],
   "dependencies": {
     "undici": "^7.29.1"