withruntime 0.3.1 → 0.4.0

package/dist/proxy.js

@@ -0,0 +1,178 @@
+/* Proxies named by the environment: HTTPS_PROXY, HTTP_PROXY and NO_PROXY, in
+   lower or upper case, the lower winning when both are set (as curl reads
+   them). Bun's fetch reads them itself; its WebSocket and Node's fetch and
+   WebSocket do not unless NODE_USE_ENV_PROXY was set before the process
+   started, which a library cannot do for its host. So every call the SDK and
+   the CLI make goes through `envFetch` and `openWebSocket`, which route by the
+   same rule on every runtime:
+
+   - an https:// or wss:// address uses HTTPS_PROXY; an http:// or ws:// one
+     uses HTTP_PROXY. HTTP_PROXY is never used for HTTPS (curl, Bun, Python
+     and Go agree; Node's own env support would fall back to it). A connection
+     error says so when that is why nothing was tried.
+   - NO_PROXY is a list of host names split by commas or spaces. A name
+     covers its subdomains, a leading dot is allowed, host:port limits it to
+     one port, and `*` alone means every host.
+   - A proxy address without a scheme is http://. Only http:// and https://
+     proxies are spoken to.
+
+   On Node the proxy is undici's ProxyAgent: undici is Node's own HTTP client
+   (the code under its fetch and WebSocket), loaded only when a proxy applies.
+   On Bun the proxy is passed to fetch and WebSocket as their `proxy` option. */
+import { RuntimeError } from "./errors.js";
+const processEnv = () => (typeof process === "undefined" ? {} : process.env);
+function variable(env, name) {
+    for (const candidate of [name.toLowerCase(), name.toUpperCase()]) {
+        const value = env[candidate]?.trim();
+        if (value)
+            return { value, name: candidate };
+    }
+    return undefined;
+}
+/** Whether a NO_PROXY list names this host (and port). Returns the entry. */
+export function exemption(list, hostname, port) {
+    const host = hostname
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "");
+    for (const raw of list.split(/[\s,]+/)) {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (entry === "*")
+            return entry;
+        const match = /^(.*?)(?::(\d+))?$/.exec(entry.replace(/^\[(.*)\]/, "$1"));
+        const name = match[1].replace(/^\./, "").replace(/\.$/, "");
+        if (!name || (match[2] && match[2] !== port))
+            continue;
+        if (host === name || host.endsWith(`.${name}`))
+            return entry;
+    }
+    return undefined;
+}
+/** The route the SDK takes to `target`, read from the environment now. */
+export function routeFor(target, env = processEnv()) {
+    const url = new URL(target);
+    const secure = url.protocol === "https:" || url.protocol === "wss:";
+    const port = url.port || (secure ? "443" : "80");
+    const found = variable(env, secure ? "https_proxy" : "http_proxy");
+    if (!found) {
+        const http = secure ? variable(env, "http_proxy") : undefined;
+        return http ? { httpOnly: http.name } : {};
+    }
+    const skip = variable(env, "no_proxy");
+    const exempt = skip && exemption(skip.value, url.hostname, port);
+    if (skip && exempt)
+        return { exempt, variable: skip.name };
+    const proxy = /^[a-z][a-z0-9+.-]*:\/\//i.test(found.value)
+        ? found.value
+        : `http://${found.value}`;
+    let parsed;
+    try {
+        parsed = new URL(proxy);
+    }
+    catch {
+        throw invalidProxy(found.name, found.value, "is not an address");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw invalidProxy(found.name, `${parsed.protocol}//${parsed.host}`, "is not an HTTP proxy");
+    return { proxy, shown: `${parsed.protocol}//${parsed.host}`, variable: found.name };
+}
+function invalidProxy(name, shown, problem) {
+    return new RuntimeError({
+        message: `${name} (${shown}) ${problem}; Runtime connects through http:// and https:// proxies.`,
+        code: "invalid_proxy",
+        status: 0,
+        hint: `Set ${name} to the proxy's address, for example http://proxy.example.com:3128, or unset it.`,
+    });
+}
+/** Words for a failed connection: the route it took, and what to check.
+ * `cause` is the error fetch threw, or the status a proxy answered with (Bun's
+ * fetch hands a refused tunnel back as a response). */
+export function describeRoute(target, cause, env = processEnv()) {
+    let route;
+    try {
+        route = routeFor(target, env);
+    }
+    catch {
+        return { via: "" };
+    }
+    const url = new URL(target);
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    if (route.proxy) {
+        const status = typeof cause === "number" ? cause : proxyStatus(cause);
+        return {
+            via: ` through the proxy ${route.shown} (${route.variable})${status ? `, which answered HTTP ${status} to the tunnel request` : ""}`,
+            hint: status === 407
+                ? `The proxy wants credentials: put them in ${route.variable}, as http://user:password@host:port.`
+                : `Check that the proxy is running and allows CONNECT to ${url.hostname}:${port}, or list ${url.hostname} in NO_PROXY to connect directly.`,
+        };
+    }
+    if (route.exempt)
+        return {
+            via: ` (directly: ${route.variable} lists ${route.exempt})`,
+            hint: `Check the network, or remove ${route.exempt} from ${route.variable} to go through the proxy.`,
+        };
+    if (route.httpOnly)
+        return {
+            via: " (directly: no HTTPS proxy is set)",
+            hint: `${route.httpOnly} is set but HTTPS_PROXY is not, and ${url.hostname} is HTTPS. Set HTTPS_PROXY to the proxy to use it.`,
+        };
+    return { via: "" };
+}
+/** The status a proxy refused a tunnel with, from undici's or Bun's error. */
+function proxyStatus(cause) {
+    for (let error = cause, depth = 0; error && depth < 5; depth++) {
+        const message = error.message;
+        const text = typeof message === "string" ? message : "";
+        const found = /proxy response \((\d{3})\)|proxy.*?\b(40[37]|50[0-9])\b/i.exec(text);
+        if (found)
+            return Number(found[1] ?? found[2]);
+        error = error.cause;
+    }
+    return undefined;
+}
+const isBun = () => typeof process !== "undefined" && !!process.versions?.bun;
+const isNode = () => typeof process !== "undefined" &&
+    !!process.versions?.node &&
+    !process.versions.bun &&
+    !("Deno" in globalThis);
+const agents = new Map();
+/** One undici ProxyAgent per proxy address, so connections are reused. */
+function undici(proxy) {
+    let agent = agents.get(proxy);
+    if (!agent) {
+        agent = import("undici").then((module) => ({
+            fetch: module.fetch,
+            WebSocket: module.WebSocket,
+            dispatcher: new module.ProxyAgent({ uri: proxy }),
+        }));
+        agent.catch(() => agents.delete(proxy));
+        agents.set(proxy, agent);
+    }
+    return agent;
+}
+/** fetch, through the proxy the environment names for the address. */
+export const envFetch = (async (input, init) => {
+    const target = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const { proxy } = routeFor(target);
+    if (proxy && isBun())
+        return fetch(input, { ...init, proxy });
+    if (proxy && isNode()) {
+        const { fetch: proxied, dispatcher } = await undici(proxy);
+        return (await proxied(target, { ...init, dispatcher }));
+    }
+    return fetch(input, init);
+});
+/** A WebSocket, through the proxy the environment names for the address. */
+export async function openWebSocket(url, headers) {
+    const { proxy } = routeFor(url);
+    if (proxy && isNode()) {
+        const { WebSocket: Proxied, dispatcher } = await undici(proxy);
+        return new Proxied(url, { headers, dispatcher });
+    }
+    const Socket = globalThis.WebSocket;
+    if (!Socket)
+        throw new Error("This runtime has no WebSocket; use Node 22+ or Bun.");
+    return new Socket(url, proxy && isBun() ? { headers, proxy } : { headers });
+}

package/dist/sandbox.d.ts

@@ -74,17 +74,20 @@ export declare class Sandbox implements AsyncDisposable {
     /** Copies of this sandbox as it is now (files, memory, running processes),
      * each its own sandbox, answered once they run. A running sandbox is paused
      * for the moment its snapshot takes, then woken. One without `count`; an
-     * array with it. */
+     * array with it. `funding` is what the copies run on, as for a create;
+     * omitted, they keep this sandbox's. */
     fork(options?: {
         name?: string;
         labels?: Record<string, string>;
         keepSnapshot?: boolean;
+        funding?: "trial" | "paid";
     } & RequestOptions): Promise<Sandbox>;
     fork(options: {
         count: number;
         name?: string;
         labels?: Record<string, string>;
         keepSnapshot?: boolean;
+        funding?: "trial" | "paid";
     } & RequestOptions): Promise<Sandbox[]>;
     /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
     restart(options?: RequestOptions & {

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.3.1";
+export declare const VERSION = "0.4.0";
 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

package/dist/transport.js

@@ -1,5 +1,6 @@
 import { ConnectionError, errorFor, RuntimeError } from "./errors.js";
-export const VERSION = "0.3.1";
+import { describeRoute, envFetch, openWebSocket } from "./proxy.js";
+export const VERSION = "0.4.0";
 export const DEFAULT_BASE_URL = "https://api.withruntime.com";
 export function apiOrigin(value) {
     const url = new URL(value);
@@ -83,6 +84,8 @@ export class Transport {
     #apiKey;
     #findKey;
     #fetch;
+    /** Whether calls go through envFetch, so a failure can name its proxy. */
+    #routed;
     #timeoutMs;
     #maxRetries;
     #client;
@@ -95,7 +98,10 @@ export class Transport {
         else
             this.#apiKey = options.apiKey;
         this.baseUrl = apiOrigin(options.baseUrl ?? DEFAULT_BASE_URL);
-        this.#fetch = options.fetch ?? fetch;
+        // The environment's proxy (HTTPS_PROXY, NO_PROXY) on Node and Bun alike;
+        // a fetch passed in is used as it is.
+        this.#fetch = options.fetch ?? envFetch;
+        this.#routed = options.fetch === undefined;
         this.#timeoutMs = options.timeoutMs ?? 300_000;
         this.#maxRetries = options.maxRetries ?? 4;
         this.#client = options.client ?? `sdk-js/${VERSION}`;
@@ -139,36 +145,65 @@ export class Transport {
         const retry = call.retry ?? true;
         for (let attempt = 0;; attempt++) {
             let response;
+            // Called as a plain function: Cloudflare Workers' fetch throws "Illegal
+            // invocation" when called as a method of another object (this.#fetch()).
+            const send = this.#fetch;
             try {
-                response = await this.#fetch(url, {
+                // "manual", not "error": Workers accept only "follow" and "manual".
+                // The API never redirects, so a redirect is refused here exactly as
+                // "error" refused it: thrown, retried, then a connection_error.
+                response = await send(url, {
                     method: call.method,
                     headers: this.#headers(call, key, apiKey),
-                    redirect: "error",
+                    redirect: "manual",
                     signal,
                     ...(body === undefined ? {} : { body: body }),
                 });
+                if (response.type === "opaqueredirect" ||
+                    (response.status >= 300 && response.status < 400)) {
+                    await response.body?.cancel().catch(() => { });
+                    throw new TypeError(`fetch failed: Runtime answered a redirect (${response.status}).`);
+                }
             }
             catch (cause) {
-                if (signal.aborted || !retry || attempt >= this.#maxRetries)
+                // A proxy variable the SDK cannot use: retrying cannot change it.
+                if (cause instanceof RuntimeError)
+                    throw cause;
+                if (signal.aborted || !retry || attempt >= this.#maxRetries) {
+                    const route = this.#routed && !signal.aborted ? describeRoute(url, cause) : { via: "" };
                     throw new ConnectionError({
                         message: signal.aborted
                             ? "The call was cancelled or ran past its deadline."
                             : write
-                                ? `No answer from Runtime at ${this.baseUrl}. The change may have happened; retrying with the same idempotencyKey is safe.`
-                                : `No answer from Runtime at ${this.baseUrl}.`,
+                                ? `No answer from Runtime at ${this.baseUrl}${route.via}. The change may have happened; retrying with the same idempotencyKey is safe.`
+                                : `No answer from Runtime at ${this.baseUrl}${route.via}.`,
                         hint: signal.aborted
                             ? "Raise timeoutMs for a long call, or retry with the same idempotencyKey."
-                            : "Check the network, and RUNTIME_API_URL if you set it.",
+                            : (route.hint ?? "Check the network, and RUNTIME_API_URL if you set it."),
                         code: signal.aborted ? "timeout" : "connection_error",
                         status: 0,
                         ...(key ? { idempotencyKey: key } : {}),
                         cause,
                     });
+                }
                 await sleep(backoff(attempt), signal);
                 continue;
             }
             if (response.ok)
                 return response;
+            // 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) {
+                await response.body?.cancel();
+                const route = describeRoute(url, 407);
+                throw new ConnectionError({
+                    message: `No answer from Runtime at ${this.baseUrl}${route.via}.`,
+                    code: "connection_error",
+                    status: 0,
+                    ...(route.hint ? { hint: route.hint } : {}),
+                    ...(key ? { idempotencyKey: key } : {}),
+                });
+            }
             const text = await response.text();
             let parsed = null;
             try {
@@ -239,11 +274,9 @@ export class Transport {
     async websocket(path, query) {
         const apiKey = await this.#key();
         const url = `${this.baseUrl.replace(/^http/, "ws")}${path}${encodeQuery(query)}`;
-        const Socket = globalThis.WebSocket;
-        if (!Socket)
-            throw new Error("This runtime has no WebSocket; use Node 22+ or Bun.");
-        return new Socket(url, {
-            headers: { authorization: `Bearer ${apiKey}`, "x-runtime-client": this.#client },
+        return openWebSocket(url, {
+            authorization: `Bearer ${apiKey}`,
+            "x-runtime-client": this.#client,
         });
     }
 }

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "withruntime",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "mcpName": "com.withruntime/runtime",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./e2b": {
+      "types": "./dist/e2b/index.d.ts",
+      "import": "./dist/e2b/index.js"
+    },
+    "./e2b/code-interpreter": {
+      "types": "./dist/e2b/code-interpreter.d.ts",
+      "import": "./dist/e2b/code-interpreter.js"
     }
   },
   "bin": {
@@ -15,7 +23,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "E2B.md"
   ],
   "engines": {
     "node": ">=22"
@@ -54,5 +63,8 @@
     "mcp",
     "microvm",
     "code-execution"
-  ]
+  ],
+  "dependencies": {
+    "undici": "^7.29.1"
+  }
 }