withruntime 0.3.0 → 0.4.0

package/dist/e2b/sandbox.js

@@ -0,0 +1,458 @@
+import { clientFor, request, } from "./client.js";
+import { Commands } from "./commands.js";
+import { guard, InvalidArgumentError, NotSupportedError, SandboxError, SandboxNotFoundError, TemplateError, } from "./errors.js";
+import { Filesystem } from "./filesystem.js";
+/* E2B's Sandbox over Runtime's. Every call is one or a few calls of the
+   withruntime SDK; nothing here speaks HTTP. What Runtime cannot do the same
+   way throws NotSupportedError before anything happens. */
+/** E2B's default machine: 2 vCPU and 512 MiB (docs.e2b.dev/billing, checked
+ * 23 September 2026). Pass `runtime: { create: { memoryMiB } }` for another. */
+export const DEFAULT_SHAPE = { vcpu: 2, memoryMiB: 512 };
+/** E2B's default sandbox timeout, 300 s. */
+export const DEFAULT_TIMEOUT_MS = 300_000;
+/** Runtime's lease bounds (MAX_TIMEOUT_SECONDS in the API). */
+const MIN_LEASE_SECONDS = 60;
+const MAX_LEASE_SECONDS = 3600;
+/** E2B template names that mean "the stock environment": Runtime's default image. */
+const STOCK_TEMPLATES = new Set(["base", "code-interpreter-v1", "code-interpreter"]);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+let warnedShortLease = false;
+function leaseSeconds(timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
+    const seconds = Math.ceil(timeoutMs / 1000);
+    if (seconds > MAX_LEASE_SECONDS)
+        throw new NotSupportedError(`A sandbox timeout of ${timeoutMs} ms (over one hour)`, "Runtime leases last up to an hour (3_600_000 ms); call sandbox.setTimeout(...) before it ends to keep going, as often as needed.");
+    if (seconds < MIN_LEASE_SECONDS) {
+        if (!warnedShortLease && typeof process !== "undefined") {
+            warnedShortLease = true;
+            process.emitWarning(`timeoutMs ${timeoutMs} is under Runtime's shortest lease; the sandbox gets 60 s. Call kill() when done.`, { code: "RUNTIME_E2B_SHORT_TIMEOUT" });
+        }
+        return MIN_LEASE_SECONDS;
+    }
+    return seconds;
+}
+function onLeaseEnd(lifecycle) {
+    if (!lifecycle)
+        return "stop";
+    if (lifecycle.autoResume)
+        throw new NotSupportedError("Auto-resume on traffic (lifecycle.autoResume)", "Wake a paused sandbox with Sandbox.connect(id) before sending it work.");
+    const action = typeof lifecycle.onTimeout === "string" ? lifecycle.onTimeout : lifecycle.onTimeout.action;
+    if (typeof lifecycle.onTimeout === "object" && lifecycle.onTimeout.keepMemory === false)
+        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    return action === "pause" ? "pause" : "stop";
+}
+function refuseCreate(opts) {
+    const refusals = [
+        [
+            "mcp",
+            "E2B's MCP gateway (mcp)",
+            "Run MCP servers yourself with commands.run(..., { background: true }).",
+        ],
+        [
+            "network",
+            "E2B's network rules (network)",
+            "Pass Runtime's rules instead: runtime: { create: { network: { internet: true, allow: [...], deny: [...] } } }.",
+        ],
+        ["iam", "E2B workload identity (iam)", "Pass credentials with envs."],
+        [
+            "volumeMounts",
+            "E2B volumes (volumeMounts)",
+            "Use a Runtime volume: runtime: { create: { volumes: [{ volumeId, path }] } }.",
+        ],
+    ];
+    for (const [field, feature, alternative] of refusals)
+        if (opts[field] !== undefined)
+            throw new NotSupportedError(feature, alternative);
+}
+/** Where a template sends the create: the stock image, a Runtime image by
+ * name or id, or a Runtime snapshot by id. */
+async function resolveTemplate(client, template) {
+    if (STOCK_TEMPLATES.has(template))
+        return {};
+    if (UUID.test(template)) {
+        try {
+            await client.images.get(template);
+            return { image: template };
+        }
+        catch (error) {
+            if (error.status !== 404)
+                throw error;
+        }
+        return { snapshot: template };
+    }
+    const page = await client.images.list({ name: template, state: "ready", limit: 1 });
+    const image = page.data[0];
+    if (image)
+        return { image: image.id };
+    const error = new TemplateError(`No Runtime image is named "${template}". E2B templates do not run on Runtime; build the same ` +
+        `environment as a Runtime image with that name and this call starts from it: ` +
+        `\`npx withruntime image build --dockerfile e2b.Dockerfile --name ${template}\`, or ` +
+        `runtime.images.build({ name: "${template}", dockerfile }).`);
+    error.code = "template_not_found";
+    throw error;
+}
+function state(runtime) {
+    const current = runtime.state;
+    if (current === "paused" || current === "pausing")
+        return "paused";
+    if (current === "stopped" || current === "stopping")
+        return "stopped";
+    return "running";
+}
+function infoOf(runtime) {
+    const info = runtime.info;
+    const templateId = typeof info.image === "string"
+        ? info.image
+        : typeof info.snapshot === "string"
+            ? info.snapshot
+            : "base";
+    const current = state(runtime);
+    return {
+        sandboxId: info.id,
+        templateId,
+        ...(info.name ? { name: info.name } : {}),
+        metadata: info.labels ?? {},
+        startedAt: new Date(info.createdAt),
+        endAt: new Date(info.expiresAt),
+        state: current === "stopped" ? "paused" : current,
+        cpuCount: info.vcpu,
+        memoryMB: info.memoryMiB,
+        envdVersion: "runtime",
+        lifecycle: { onTimeout: info.onLeaseEnd === "stop" ? "kill" : "pause", autoResume: false },
+    };
+}
+function unsupported(feature, alternative) {
+    return Promise.reject(new NotSupportedError(feature, alternative));
+}
+/** A sandbox, with E2B's methods. `sandbox.runtime` is the Runtime sandbox
+ * underneath, for anything E2B has no name for. */
+export class Sandbox {
+    static defaultTemplate = "base";
+    files;
+    commands;
+    #client;
+    #runtime;
+    #envs;
+    #home;
+    /** Use Sandbox.create or Sandbox.connect. */
+    constructor(runtime, client, envs = {}) {
+        this.#runtime = runtime;
+        this.#client = client;
+        this.#envs = envs;
+        const ctx = {
+            envs,
+            ensureHome: (text) => this.#ensureHome(text),
+        };
+        // A getter, so the modules see the sandbox as it is after each refresh.
+        Object.defineProperty(ctx, "runtime", { get: () => this.#runtime });
+        this.files = new Filesystem(ctx);
+        this.commands = new Commands(ctx);
+    }
+    get sandboxId() {
+        return this.#runtime.id;
+    }
+    /** The Runtime sandbox underneath: previews, network, desktop, interpreter,
+     * processes, terminal and the rest of Runtime's SDK. */
+    get runtime() {
+        return this.#runtime;
+    }
+    get client() {
+        return this.#client;
+    }
+    get envs() {
+        return this.#envs;
+    }
+    /** E2B's home is /home/user and Runtime's is /workspace. The first time a
+     * path or command names /home/user, it is made a link to /workspace (unless
+     * something is already there), so paths written for E2B work. */
+    #ensureHome(text) {
+        if (this.#home || !text?.includes("/home/user"))
+            return this.#home ?? Promise.resolve();
+        this.#home = (async () => {
+            const result = await guard("sandbox", () => this.#runtime.exec("[ -e /home/user ] || sudo ln -s /workspace /home/user"));
+            if (result.exitCode !== 0 && typeof process !== "undefined")
+                process.emitWarning(`Could not link /home/user to /workspace: ${result.stderr.trim()}`, {
+                    code: "RUNTIME_E2B_HOME",
+                });
+        })();
+        return this.#home;
+    }
+    static async create(templateOrOpts, maybeOpts) {
+        const opts = (typeof templateOrOpts === "string" ? maybeOpts : templateOrOpts) ?? {};
+        const template = (typeof templateOrOpts === "string" ? templateOrOpts : opts.template) ?? this.defaultTemplate;
+        refuseCreate(opts);
+        const client = clientFor(opts);
+        const input = {
+            timeoutSeconds: leaseSeconds(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            onLeaseEnd: onLeaseEnd(opts.lifecycle),
+            ...(opts.metadata && Object.keys(opts.metadata).length ? { labels: opts.metadata } : {}),
+            ...(opts.allowInternetAccess === false ? { network: { internet: false } } : {}),
+        };
+        const source = await guard("other", () => resolveTemplate(client, template));
+        const create = {
+            // A snapshot carries its own machine; everything else gets E2B's shape.
+            ...(source.snapshot ? {} : DEFAULT_SHAPE),
+            ...input,
+            ...source,
+            ...opts.runtime?.create,
+        };
+        const runtime = await guard("sandbox", () => client.sandboxes.create(create, request(opts)));
+        return new this(runtime, client, { ...opts.envs });
+    }
+    /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
+     * `timeoutMs` moves a running sandbox's end later, never earlier. */
+    static async connect(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        await resume(runtime, opts);
+        return new this(runtime, client);
+    }
+    /** Wakes this sandbox if it is paused. */
+    async connect(opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        await resume(this.#runtime, opts);
+        return this;
+    }
+    /** Running and paused sandboxes, a page at a time, as E2B's paginator. */
+    static list(opts = {}) {
+        return new SandboxPaginator(clientFor(opts), opts);
+    }
+    // ---- lifecycle --------------------------------------------------------
+    /** Stops the sandbox. False when it was not found or had already ended. */
+    static async kill(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        try {
+            const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+            return await stop(runtime, opts);
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    async kill(opts = {}) {
+        try {
+            return await stop(this.#runtime, opts);
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Sets the sandbox to end `timeoutMs` from now. Runtime leases only move
+     * later: a shorter timeout than the one it has is refused. */
+    static async setTimeout(sandboxId, timeoutMs, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        await extendTo(runtime, timeoutMs, opts);
+    }
+    async setTimeout(timeoutMs, opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        await extendTo(this.#runtime, timeoutMs, opts);
+    }
+    static async getInfo(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        return infoOf(await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts))));
+    }
+    async getInfo(opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        return infoOf(this.#runtime);
+    }
+    async isRunning(opts = {}) {
+        try {
+            await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        }
+        catch (error) {
+            if (error instanceof SandboxNotFoundError)
+                return false;
+            throw error;
+        }
+        return this.#runtime.state === "running";
+    }
+    /** Pauses the sandbox, keeping memory and files. False when it was paused. */
+    static async pause(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        return pause(await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts))), opts);
+    }
+    static betaPause(sandboxId, opts = {}) {
+        return this.pause(sandboxId, opts);
+    }
+    async pause(opts = {}) {
+        await guard("sandbox", () => this.#runtime.refresh(request(opts)));
+        return pause(this.#runtime, opts);
+    }
+    async betaPause(opts = {}) {
+        return this.pause(opts);
+    }
+    // ---- forks and snapshots ---------------------------------------------
+    /** Copies of this sandbox, memory and all. While Runtime's forks are
+     * switched off this throws NotSupportedError with Runtime's own words. */
+    static async fork(sandboxId, opts = {}) {
+        const { count: _count, timeoutMs: _timeoutMs, ...connection } = opts;
+        const source = await this.connect(sandboxId, connection);
+        return source.fork(opts);
+    }
+    async fork(opts = {}) {
+        if (opts.timeoutMs !== undefined)
+            // A fork's lease is Runtime's to set; one shorter than asked could not be
+            // honoured after the forks exist, so this is refused before any are made.
+            throw new NotSupportedError("A timeout for forks (fork timeoutMs)", "Fork without it, then call setTimeout(ms) on each fork.");
+        const copies = await guard("sandbox", () => this.#runtime.fork({ count: opts.count ?? 1, ...request(opts) }));
+        const Kind = this.constructor;
+        return copies.map((copy) => new Kind(copy, this.#client, { ...this.#envs }));
+    }
+    /** Keeps the sandbox's whole machine as a Runtime snapshot; start from it
+     * with Sandbox.create(snapshotId). */
+    async createSnapshot(opts = {}) {
+        const snapshot = await guard("sandbox", () => this.#runtime.snapshot({ ...(opts.name ? { name: opts.name } : {}), ...request(opts) }));
+        return { snapshotId: snapshot.id, names: snapshot.name ? [snapshot.name] : [] };
+    }
+    static async createSnapshot(sandboxId, opts = {}) {
+        const client = clientFor(opts);
+        const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
+        return new Sandbox(runtime, client).createSnapshot(opts);
+    }
+    static async deleteSnapshot(snapshotId, opts = {}) {
+        const client = clientFor(opts);
+        try {
+            await guard("other", () => client.snapshots.delete(snapshotId, request(opts)));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof SandboxError && error.statusCode === 404)
+                return false;
+            throw error;
+        }
+    }
+    // ---- ports ------------------------------------------------------------
+    /** Refused: E2B answers getHost without a call, and a Runtime port becomes
+     * reachable only once it is shared. Use getPublicHost. */
+    getHost(port) {
+        throw new NotSupportedError(`sandbox.getHost(${port}), which answers without asking the server`, `Use \`await sandbox.getPublicHost(${port})\`: it shares the port at a public HTTPS address and returns its host, as getHost does.`);
+    }
+    /** Shares `port` at a public HTTPS address (a Runtime preview) and returns
+     * its host, `<port>-<id>.<domain>`, like E2B's getHost. Anyone with the
+     * address can reach it; a browser sees a one-time page naming Runtime. */
+    async getPublicHost(port) {
+        const preview = await guard("sandbox", () => this.#runtime.previews.create(port, { visibility: "public" }));
+        return new URL(preview.url).host;
+    }
+    // ---- what Runtime does differently -----------------------------------
+    get pty() {
+        throw new NotSupportedError("E2B's pty module", "Use `await sandbox.runtime.terminal({ cols, rows, onData })` for an interactive terminal, or runtime.spawn(cmd, { pty: {} }).");
+    }
+    get git() {
+        throw new NotSupportedError("E2B's git module (deprecated by E2B too)", "Run git with sandbox.commands.run('git ...'); git is installed.");
+    }
+    getMetrics() {
+        return unsupported("Sandbox metrics (getMetrics)", "Runtime reports CPU, memory and charges per sandbox in `npx withruntime usage` and runtime.usage().");
+    }
+    static getMetrics() {
+        return unsupported("Sandbox metrics (getMetrics)", "Runtime reports CPU, memory and charges per sandbox in `npx withruntime usage` and runtime.usage().");
+    }
+    updateNetwork() {
+        return unsupported("E2B's network rules (updateNetwork)", "Use sandbox.runtime.network.set({ internet, allow, deny }).");
+    }
+    uploadUrl() {
+        return unsupported("Signed upload URLs", "Use sandbox.files.write(path, data).");
+    }
+    downloadUrl() {
+        return unsupported("Signed download URLs", "Use sandbox.files.read(path, { format: 'bytes' }).");
+    }
+    getMcpUrl() {
+        throw new NotSupportedError("E2B's MCP gateway", "Runtime's own MCP server is `npx withruntime mcp`.");
+    }
+    getMcpToken() {
+        return unsupported("E2B's MCP gateway", "Runtime's own MCP server is `npx withruntime mcp`.");
+    }
+}
+async function resume(runtime, opts) {
+    if (opts.onResume === "reboot")
+        throw new NotSupportedError("Resuming by reboot (onResume: 'reboot')", "Runtime's wake restores memory; stop the sandbox and create a new one for a clean boot.");
+    const current = state(runtime);
+    if (current === "stopped")
+        throw new SandboxNotFoundError(`Sandbox ${runtime.id} has ended.`);
+    if (current === "paused") {
+        await guard("sandbox", () => runtime.wake({
+            ...(opts.timeoutMs === undefined ? {} : { timeoutSeconds: leaseSeconds(opts.timeoutMs) }),
+            ...request(opts),
+        }));
+        return;
+    }
+    if (opts.timeoutMs !== undefined) {
+        const later = Date.now() + opts.timeoutMs - Date.parse(runtime.info.expiresAt);
+        if (later > 1000)
+            await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
+    }
+}
+async function stop(runtime, opts) {
+    if (state(runtime) === "stopped")
+        return false;
+    await guard("sandbox", () => runtime.stop({ wait: false, ...request(opts) }));
+    return true;
+}
+async function extendTo(runtime, timeoutMs, opts) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new InvalidArgumentError(`timeoutMs must be a positive number, not ${timeoutMs}.`);
+    const later = Date.now() + timeoutMs - Date.parse(runtime.info.expiresAt);
+    if (later < -1000)
+        throw new NotSupportedError("Shortening a sandbox's timeout", "Runtime leases only move later. Call kill() when the work is done.");
+    if (later > 1000)
+        await guard("sandbox", () => runtime.extend(Math.ceil(later / 1000), request(opts)));
+}
+async function pause(runtime, opts) {
+    if (opts.keepMemory === false)
+        throw new NotSupportedError("A files-only pause (keepMemory: false)", "Runtime's pause keeps memory and files; leave keepMemory out.");
+    const current = state(runtime);
+    if (current === "paused")
+        return false;
+    if (current === "stopped")
+        throw new SandboxNotFoundError(`Sandbox ${runtime.id} has ended.`);
+    await guard("sandbox", () => runtime.pause(request(opts)));
+    return true;
+}
+const RUNNING = ["starting", "running", "resuming"];
+const PAUSED = ["pausing", "paused"];
+/** E2B's paginator: `while (p.hasNext) items.push(...(await p.nextItems()))`. */
+export class SandboxPaginator {
+    #client;
+    #filter;
+    #page;
+    #hasNext = true;
+    constructor(client, opts) {
+        this.#client = client;
+        const query = opts.query ?? {};
+        if (query.template !== undefined && !STOCK_TEMPLATES.has(query.template))
+            throw new NotSupportedError("Listing by template", "Filter by metadata instead: give sandboxes a metadata key when you create them.");
+        if (query.startedAfter !== undefined)
+            throw new NotSupportedError("Listing by start time (startedAfter)", "List them all and filter on getInfo().startedAt.");
+        if (opts.order === "desc")
+            throw new NotSupportedError("Newest-first listing (order: 'desc')", "Runtime lists oldest first; reverse the list yourself.");
+        if (opts.nextToken !== undefined)
+            throw new NotSupportedError("Starting a list from a saved nextToken", "Keep the paginator and call nextItems() again.");
+        const states = query.state?.length ? query.state : ["running", "paused"];
+        this.#filter = {
+            state: states.flatMap((one) => (one === "running" ? [...RUNNING] : [...PAUSED])),
+            ...(query.metadata && Object.keys(query.metadata).length ? { labels: query.metadata } : {}),
+            ...(opts.limit ? { limit: Math.min(opts.limit, 100) } : {}),
+        };
+    }
+    get hasNext() {
+        return this.#hasNext;
+    }
+    get nextToken() {
+        return this.#page?.nextCursor ?? undefined;
+    }
+    async nextItems() {
+        if (!this.#hasNext)
+            throw new SandboxError("No more items to fetch.");
+        const previous = this.#page;
+        const page = await guard("other", async () => previous ? await previous.next() : await this.#client.sandboxes.list(this.#filter));
+        this.#page = page ?? undefined;
+        this.#hasNext = Boolean(page?.hasMore);
+        return (page?.data ?? []).map(infoOf);
+    }
+}

package/dist/e2b/unsupported.d.ts

@@ -0,0 +1,19 @@
+/** A stand-in for an E2B export Runtime has no counterpart for. Importing it
+ * works, so a module that only mentions it still loads; calling it, building
+ * it or reading anything from it throws NotSupportedError naming the
+ * alternative. */
+export type Unsupported = {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};
+export declare function unsupportedExport(name: string, alternative: string): Unsupported;
+export declare const Template: Unsupported;
+export declare const TemplateBase: Unsupported;
+export declare const waitForPort: Unsupported;
+export declare const waitForURL: Unsupported;
+export declare const waitForProcess: Unsupported;
+export declare const waitForFile: Unsupported;
+export declare const waitForTimeout: Unsupported;
+export declare const Volume: Unsupported;
+export declare const Secret: Unsupported;

package/dist/e2b/unsupported.js

@@ -0,0 +1,27 @@
+import { NotSupportedError } from "./errors.js";
+export function unsupportedExport(name, alternative) {
+    const fail = () => {
+        throw new NotSupportedError(`E2B's ${name}`, alternative);
+    };
+    return new Proxy(function unsupported() { }, {
+        apply: fail,
+        construct: fail,
+        get: (_target, property) => {
+            // Let the module system, inspectors and promise checks look at it
+            // without tripping: only a real use throws.
+            if (typeof property === "symbol" || property === "then" || property === "prototype")
+                return undefined;
+            return fail();
+        },
+    });
+}
+const TEMPLATES = "Build a Runtime image instead: `npx withruntime image build --dockerfile e2b.Dockerfile --name <template>` or runtime.images.build({ name, dockerfile | recipe }), then Sandbox.create('<template>').";
+export const Template = unsupportedExport("Template builder", TEMPLATES);
+export const TemplateBase = unsupportedExport("TemplateBase", TEMPLATES);
+export const waitForPort = unsupportedExport("waitForPort (a template ready check)", TEMPLATES);
+export const waitForURL = unsupportedExport("waitForURL (a template ready check)", TEMPLATES);
+export const waitForProcess = unsupportedExport("waitForProcess (a template ready check)", TEMPLATES);
+export const waitForFile = unsupportedExport("waitForFile (a template ready check)", TEMPLATES);
+export const waitForTimeout = unsupportedExport("waitForTimeout (a template ready check)", TEMPLATES);
+export const Volume = unsupportedExport("Volume", "Use runtime.volumes (Runtime volumes) and mount one with runtime: { create: { volumes: [{ volumeId, path }] } }.");
+export const Secret = unsupportedExport("Secret", "Pass secrets as envs at create or per command, never inside the command text.");

package/dist/index.d.ts

@@ -12,6 +12,7 @@ import type { RequestOptions } from "./transport.js";
 export { Runtime, Sandboxes, FeedbackApi, SupportApi, type RuntimeOptions, type SupportReply, } from "./client.js";
 export { Files, Process, Processes, Terminal } from "./sandbox.js";
 export { Page } from "./page.js";
+export type { KeyLimits } from "./products/limits.js";
 export { Snapshots, type Snapshot, type SnapshotOptions } from "./snapshots.js";
 export { Transport, VERSION, apiOrigin, type RequestOptions, type Call } from "./transport.js";
 export * from "./errors.js";

package/dist/login.js

@@ -3,6 +3,7 @@ import { generateKeyPair, privateDecrypt } from "node:crypto";
 import { promisify } from "node:util";
 import { Runtime } from "./index.js";
 import { connectionOrigins, connectionStore } from "./credentials.js";
+import { describeRoute, envFetch } from "./proxy.js";
 class ConnectionError extends Error {
     status;
     constructor(status, message) {
@@ -71,11 +72,12 @@ async function browser(url) {
 function connection(env, options) {
     const origins = connectionOrigins(env);
     const store = connectionStore(env);
-    const fetcher = options.fetch ?? fetch;
+    const fetcher = options.fetch ?? envFetch;
     async function request(path, body, key) {
         let response;
+        const address = `${origins.auth}/api/connect/${path}`;
         try {
-            response = await fetcher(`${origins.auth}/api/connect/${path}`, {
+            response = await fetcher(address, {
                 method: "POST",
                 redirect: "error",
                 signal: AbortSignal.timeout(20_000),
@@ -86,8 +88,15 @@ function connection(env, options) {
                 body: JSON.stringify(body ?? {}),
             });
         }
-        catch {
-            throw new ConnectionError(503, "Runtime could not be reached. Retry the connection.");
+        catch (cause) {
+            const route = options.fetch ? { via: "" } : describeRoute(address, cause, env);
+            throw new ConnectionError(503, route.hint
+                ? `Runtime could not be reached at ${origins.auth}${route.via}. ${route.hint}`
+                : "Runtime could not be reached. Retry the connection.");
+        }
+        if (response.status === 407 && !options.fetch) {
+            const route = describeRoute(address, 407, env);
+            throw new ConnectionError(503, `Runtime could not be reached at ${origins.auth}${route.via}. ${route.hint ?? ""}`.trim());
         }
         if (!response.ok)
             throw new ConnectionError(response.status, response.status === 401

package/dist/mcp.d.ts

@@ -1,8 +1,8 @@
 /** Bridges an MCP client that speaks stdio to Runtime's hosted MCP endpoint.
  * Newline-delimited JSON-RPC in, the same out; every message is forwarded as
  * it is, so the server's tools, schemas and `instructions` reach the client
- * unchanged, and nothing here keeps a second catalogue. No dependencies:
- * starting it costs a process and one TLS connection.
+ * unchanged, and nothing here keeps a second catalogue. Starting it costs a
+ * process and one TLS connection (undici loads only behind a proxy).
  *
  * With no key on this machine it does not fail: it serves one tool,
  * runtime_connect, that walks the agent and its person through the browser

package/dist/mcp.js

@@ -2,6 +2,7 @@ import process from "node:process";
 import { resolveCredential } from "./credentials.js";
 import { RuntimeError } from "./errors.js";
 import { beginDeviceLogin } from "./login.js";
+import { envFetch } from "./proxy.js";
 import { apiOrigin, VERSION } from "./transport.js";
 const CONNECT_INSTRUCTIONS = "Runtime is not connected on this machine yet. Call runtime_connect: it gives you a link and a code for the person you work for to approve in their browser (no key to copy). Once they have, call runtime_connect again; Runtime's tools then appear (sandboxes, commands, files and the rest).";
 const connectTool = {
@@ -13,8 +14,8 @@ const connectTool = {
 /** Bridges an MCP client that speaks stdio to Runtime's hosted MCP endpoint.
  * Newline-delimited JSON-RPC in, the same out; every message is forwarded as
  * it is, so the server's tools, schemas and `instructions` reach the client
- * unchanged, and nothing here keeps a second catalogue. No dependencies:
- * starting it costs a process and one TLS connection.
+ * unchanged, and nothing here keeps a second catalogue. Starting it costs a
+ * process and one TLS connection (undici loads only behind a proxy).
  *
  * With no key on this machine it does not fail: it serves one tool,
  * runtime_connect, that walks the agent and its person through the browser
@@ -22,7 +23,7 @@ const connectTool = {
  * So `claude mcp add runtime -- npx -y withruntime mcp` is the whole
  * setup. */
 export async function serveMcp(env = process.env, options = {}) {
-    const fetcher = options.fetch ?? fetch;
+    const fetcher = options.fetch ?? envFetch;
     let key;
     try {
         key = await resolveCredential(env);

package/dist/products/index.d.ts

@@ -6,11 +6,13 @@ import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
+import { limits } from "./limits.js";
 import { volumes } from "./volumes.js";
 export declare const clientExtensions: {
     images: typeof images;
     volumes: typeof volumes;
     referrals: typeof referrals;
+    limits: typeof limits;
 };
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;

package/dist/products/index.js

@@ -4,6 +4,7 @@ import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
+import { limits } from "./limits.js";
 import { volumes } from "./volumes.js";
 /* HOW A LANE ADDS A PRODUCT TO THE SDK
  *
@@ -20,7 +21,7 @@ import { volumes } from "./volumes.js";
  * 2. Add ONE line to the matching object below. The Runtime client and every
  *    Sandbox pick it up, typed, with the shared auth, retries, keys and errors.
  */
-export const clientExtensions = { images, volumes, referrals };
+export const clientExtensions = { images, volumes, referrals, limits };
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,
     previews: sandboxPreviews,

package/dist/products/limits.d.ts

@@ -0,0 +1,25 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** What this key may do, and the daily spending limit on its agent. Money is
+ * integer microdollars in strings (1,000,000 = $1). */
+export type KeyLimits = {
+    /** full: every action. read: every read and nothing else (a read-only key).
+     * selected: the actions the key names. */
+    access: "full" | "read" | "selected" | null;
+    daily: {
+        /** The most this agent may commit in any 24 hours, or null for no limit. */
+        limitMicros: string | null;
+        /** Committed in the last 24 hours: charges settled plus money on hold. */
+        usedMicros: string;
+        /** What is left under the limit now, or null for no limit. */
+        remainingMicros: string | null;
+        window: "24h";
+    };
+};
+/** `runtime.limits.get()`: whether this key is read-only, and what its agent
+ * may still spend today. An owner sets the limit at
+ * https://withruntime.com/account/keys; a key can read it, never change it.
+ * Past it, a create, wake, extension or renewal fails with
+ * `spending_limit_reached` (HTTP 402). */
+export declare function limits(t: Transport): {
+    get: (options?: RequestOptions) => Promise<KeyLimits>;
+};

package/dist/products/limits.js

@@ -0,0 +1,10 @@
+/** `runtime.limits.get()`: whether this key is read-only, and what its agent
+ * may still spend today. An owner sets the limit at
+ * https://withruntime.com/account/keys; a key can read it, never change it.
+ * Past it, a create, wake, extension or renewal fails with
+ * `spending_limit_reached` (HTTP 402). */
+export function limits(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/limits", ...options }),
+    };
+}