withruntime 0.8.3 → 0.9.0

package/dist/products/interpreter.js

@@ -1,3 +1,4 @@
+import { RuntimeError } from "../errors.js";
 /** A stateful interpreter in the sandbox, in Python, JavaScript, TypeScript,
  * R, Java, Bash or Go:
  * `await sbx.interpreter.run("import pandas as pd; pd.DataFrame({'a': [1]})")`.
@@ -7,33 +8,56 @@ export function sandboxInterpreter(t, sandbox) {
     return {
         /** Run a cell. With any of the on* callbacks, output streams as it happens. */
         async run(code, options = {}) {
-            const { language, context, timeoutMs, onStdout, onStderr, onResult, onError, ...request } = options;
+            const { language, context, timeoutMs, requestTimeoutMs, interruptOnDisconnect, onStdout, onStderr, onResult, onError, ...request } = options;
+            const transportOptions = {
+                ...request,
+                ...(requestTimeoutMs !== undefined
+                    ? { timeoutMs: requestTimeoutMs }
+                    : timeoutMs !== undefined
+                        ? { timeoutMs: timeoutMs === 0 ? 0 : timeoutMs + 60_000 }
+                        : {}),
+            };
             const body = {
                 code,
                 ...(language ? { language } : {}),
                 ...(context ? { context } : {}),
-                ...(timeoutMs ? { timeoutMs } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                ...(interruptOnDisconnect !== undefined ? { interruptOnDisconnect } : {}),
             };
             if (!onStdout && !onStderr && !onResult && !onError)
-                return t.json({ method: "POST", path: `${base()}:run`, body, ...request });
+                return t.json({
+                    method: "POST",
+                    path: `${base()}:run`,
+                    body,
+                    ...transportOptions,
+                });
             for await (const event of t.events({
                 method: "POST",
                 path: `${base()}:run`,
                 body: { ...body, stream: true },
-                ...request,
+                ...transportOptions,
             })) {
                 if (event.k === "stdout")
-                    onStdout?.(event.text);
+                    await onStdout?.(event.text);
                 else if (event.k === "stderr")
-                    onStderr?.(event.text);
+                    await onStderr?.(event.text);
                 else if (event.k === "result")
-                    onResult?.({ main: event.main, data: event.data, refs: event.refs });
+                    await onResult?.({ main: event.main, data: event.data, refs: event.refs });
                 else if (event.k === "error")
-                    onError?.(event);
+                    await onError?.(event);
                 else if (event.k === "execution")
                     return event.execution;
                 else if (event.k === "failure")
-                    throw new Error(`${event.code}: ${event.message}`);
+                    // As every other refusal: its code, words, hint and request id,
+                    // printed by the CLI as it prints the rest (28 September 2026:
+                    // "Error: forbidden: cloud forbidden", with no hint and no id).
+                    throw new RuntimeError({
+                        code: event.code,
+                        status: event.status ?? 0,
+                        message: event.message,
+                        ...(event.hint ? { hint: event.hint } : {}),
+                        ...(event.requestId ? { requestId: event.requestId } : {}),
+                    });
             }
             throw new Error("The interpreter stream ended without a result");
         },

package/dist/products/jobs.d.ts

@@ -134,7 +134,7 @@ export type CreateJob = {
     maxTotalCostMicros?: number;
 };
 /** The size a run gets when `compute` leaves a field out: the sandbox
- * defaults, in the region `us-east-vin`. */
+ * defaults, in the region `us-east`. */
 export declare const JOB_DEFAULTS: {
     region: string;
     vcpu: number;

package/dist/products/jobs.js

@@ -1,17 +1,18 @@
+import { JOB_START_SECONDS, JOB_TIMEOUT_SECONDS } from "../api-defaults.js";
 import { Page } from "../page.js";
 import { RuntimeError, ServiceUnavailableError } from "../errors.js";
 /** The size a run gets when `compute` leaves a field out: the sandbox
- * defaults, in the region `us-east-vin`. */
+ * defaults, in the region `us-east`. */
 export const JOB_DEFAULTS = {
-    region: "us-east-vin",
+    region: "us-east",
     vcpu: 2,
     cpuMode: "shared",
     cpuFloorMillis: 50,
     memoryMiB: 4096,
     diskMiB: 4096,
-    timeoutSeconds: 1800,
+    timeoutSeconds: JOB_TIMEOUT_SECONDS,
     /** Added to the timeout for the sandbox to start, within the hour. */
-    startSeconds: 60,
+    startSeconds: JOB_START_SECONDS,
 };
 /** A run is one sandbox: at most 16 vCPU and 64 GiB, a disk no smaller than
  * the system image, and paid for at most an hour. */

package/dist/products/limits.d.ts

@@ -14,6 +14,16 @@ export type KeyLimits = {
         remainingMicros: string | null;
         window: "24h";
     };
+    /** The account's free trial time in milliseconds, the same figures as
+     * `usage.get()`, or null when the account has no trial. A trial sandbox
+     * that has not ended holds its whole lease in `reservedMs`;
+     * `availableMs = totalMs - usedMs - reservedMs`. */
+    trial: {
+        totalMs: number;
+        usedMs: number;
+        reservedMs: number;
+        availableMs: number;
+    } | null;
 };
 /** `runtime.limits.get()`: whether this key is read-only, and what its agent
  * may still spend today. An owner sets the limit at

package/dist/products/previews.d.ts

@@ -17,6 +17,8 @@ export type Preview = {
     urlWithToken: string | null;
     /** Turned off by Runtime after a report. */
     disabled: boolean;
+    /** The sites that may show it in an iframe; null for any site. */
+    embedOrigins: string[] | null;
     createdAt: string;
     /** On create only: how to share the address, in one line. */
     hint?: string;
@@ -27,6 +29,11 @@ export type CreatePreview = {
     visibility?: "private" | "public";
     /** How long the returned token lasts, 60 s to 7 days (default 1 day). */
     ttlSeconds?: number;
+    /** The sites that may show it in an iframe, as origins
+     * (`https://app.example.com`, `https://*.example.com`, `http://localhost:3000`),
+     * up to 16. Any other site's iframe is refused. Omitted: a shared port keeps
+     * its list; `[]` or null: any site, the default. */
+    embedOrigins?: string[] | null;
 };
 /** `sbx.previews`: share ports of this sandbox at public HTTPS addresses.
  *
@@ -35,7 +42,8 @@ export type CreatePreview = {
  *
  * WebSockets work. The server must listen on 0.0.0.0 or localhost. */
 export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
-    /** Shares `port`, or changes its visibility if it is shared already. */
+    /** Shares `port`, or changes its visibility and embedOrigins if it is
+     * shared already. */
     create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
     /** Every shared port, each private one with a fresh token. */
     list: (options?: RequestOptions) => Promise<Preview[]>;
@@ -43,7 +51,7 @@ export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
     get: (port: number, ttlSeconds?: number, options?: RequestOptions) => Promise<Preview>;
     /** Refuses every token issued for this port so far and returns a new one. */
     rotate: (port: number, options?: RequestOptions) => Promise<Preview>;
-    /** Stops sharing `port`. Open connections close within seconds. */
+    /** Stops sharing `port`. Its open connections are closed before this returns. */
     delete: (port: number, options?: RequestOptions) => Promise<{
         id: string;
         sandboxId: string;

package/dist/products/previews.js

@@ -7,7 +7,8 @@
 export function sandboxPreviews(t, sandbox) {
     const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/previews`;
     return {
-        /** Shares `port`, or changes its visibility if it is shared already. */
+        /** Shares `port`, or changes its visibility and embedOrigins if it is
+         * shared already. */
         create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
         /** Every shared port, each private one with a fresh token. */
         list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
@@ -20,7 +21,7 @@ export function sandboxPreviews(t, sandbox) {
         }),
         /** Refuses every token issued for this port so far and returns a new one. */
         rotate: (port, options) => t.json({ method: "POST", path: `${base()}/${port}:rotate`, ...options }),
-        /** Stops sharing `port`. Open connections close within seconds. */
+        /** Stops sharing `port`. Its open connections are closed before this returns. */
         delete: (port, options) => t.json({
             method: "DELETE",
             path: `${base()}/${port}`,

package/dist/products/tailscale.d.ts

@@ -0,0 +1,57 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** Joining a sandbox to your tailnet. */
+export type TailscaleJoin = {
+    /** The name of a secret stored for jobs (`runtime secrets set NAME --jobs`)
+     * that holds a Tailscale auth key. Use an ephemeral, tagged key. */
+    authKeySecret: string;
+    /** The machine's name on the tailnet, a DNS label. Default: the sandbox's
+     * name, or runtime- and the first part of its id. */
+    hostname?: string;
+    /** Tags to advertise, such as `tag:agents`; the key must be allowed them. */
+    tags?: string[];
+};
+/** A sandbox's machine on your tailnet, as the sandbox reports it. */
+export type TailscaleNode = {
+    /** Logged in and running now. */
+    running: boolean;
+    /** Tailscale's own word: Running, NeedsLogin, Starting, Stopped. */
+    state: string | null;
+    /** kernel: a tailscale0 interface reaches 100.x directly. userspace: the
+     * tailnet reaches the sandbox's ports, and programs in it reach the tailnet
+     * through `proxy`. */
+    mode: "kernel" | "userspace" | null;
+    /** Its MagicDNS name, such as agent-1.tail1234.ts.net. */
+    dnsName: string | null;
+    /** Its tailnet addresses, 100.x and fd7a:… */
+    addresses: string[];
+    /** SOCKS5 and HTTP proxy to the tailnet in userspace mode. */
+    proxy: string | null;
+};
+/** What a join answers: the node, and what Runtime recorded. */
+export type TailscaleJoined = TailscaleNode & {
+    hostname: string;
+    tags: string[];
+    /** The secret the key was read from; never the key. */
+    authKeySecret: string | null;
+    joinedAt: number;
+};
+/** What `status()` answers: the node, and the join, or null on none. */
+export type TailscaleStatus = TailscaleNode & {
+    tailnet: Pick<TailscaleJoined, "hostname" | "tags" | "authKeySecret" | "joinedAt"> | null;
+};
+/** `sbx.tailscale`: this sandbox on your own Tailscale network. Paid
+ * sandboxes only.
+ *
+ *   const node = await sbx.tailscale.up({ authKeySecret: "TS_AUTHKEY", tags: ["tag:agents"] });
+ *   console.log(node.addresses);
+ *
+ * The auth key stays in the sandbox's memory. `down()` takes the machine off
+ * the tailnet at once; after a stop or a delete, Tailscale removes it. */
+export declare function sandboxTailscale(t: Transport, sandbox: Sandbox): {
+    up: (input: TailscaleJoin, options?: RequestOptions) => Promise<TailscaleJoined>;
+    status: (options?: RequestOptions) => Promise<TailscaleStatus>;
+    down: (options?: RequestOptions) => Promise<{
+        left: boolean;
+    }>;
+};

package/dist/products/tailscale.js

@@ -0,0 +1,17 @@
+const enc = encodeURIComponent;
+/** `sbx.tailscale`: this sandbox on your own Tailscale network. Paid
+ * sandboxes only.
+ *
+ *   const node = await sbx.tailscale.up({ authKeySecret: "TS_AUTHKEY", tags: ["tag:agents"] });
+ *   console.log(node.addresses);
+ *
+ * The auth key stays in the sandbox's memory. `down()` takes the machine off
+ * the tailnet at once; after a stop or a delete, Tailscale removes it. */
+export function sandboxTailscale(t, sandbox) {
+    const path = () => `/v1/sandboxes/${enc(sandbox.id)}/tailscale`;
+    return {
+        up: (input, options) => t.json({ method: "POST", path: path(), body: input, ...options }),
+        status: (options) => t.json({ method: "GET", path: path(), ...options }),
+        down: (options) => t.json({ method: "DELETE", path: path(), ...options }),
+    };
+}

package/dist/products/watch.d.ts

@@ -1,5 +1,5 @@
 import type { RequestOptions, Transport } from "../transport.js";
-export type FileEventType = "create" | "write" | "remove" | "rename" | "chmod";
+export type FileEventType = "create" | "write" | "remove" | "rename" | "chmod" | "access";
 export type FileEvent = {
     type: FileEventType;
     /** Absolute path in the sandbox. */
@@ -23,7 +23,7 @@ export type WatchNotice = {
 };
 export type WatchOptions = Omit<RequestOptions, "timeoutMs"> & {
     recursive?: boolean;
-    /** Only these event types; all five by default. */
+    /** Only these event types; the five mutation types by default; access is opt-in. */
     events?: FileEventType[];
     /** Globs relative to the path: only matching paths are reported. */
     include?: string[];
@@ -31,7 +31,7 @@ export type WatchOptions = Omit<RequestOptions, "timeoutMs"> & {
     exclude?: string[];
     /** Events are gathered this long and delivered together. Default 100. */
     batchMs?: number;
-    /** The watch ends by itself after running this long. Default 1 hour. */
+    /** The watch ends by itself after running this long. Default 1 hour; 0 runs until stopped or the sandbox ends. */
     timeoutMs?: number;
     maxWatches?: number;
     /** A batch at a time, rather than one call per event. */
@@ -49,6 +49,16 @@ export type WatchInfo = {
     processId: string;
     state: string;
     startedAt: number;
+    /** Its changes go to the account's webhooks as `sandbox.files.changed`. */
+    webhook?: boolean;
+};
+/** A watch whose changes Runtime sends to the account's webhooks. */
+export type WebhookWatchOptions = Omit<WatchOptions, "onBatch" | "onNotice" | "onExit" | "timeoutMs"> & {
+    /** The watch ends by itself after running this long; 0 (the default here)
+     * runs until stopped or the sandbox ends. */
+    timeoutMs?: number;
+    /** Its own id, 1 to 40 lowercase letters, digits or dashes. */
+    id?: string;
 };
 /** A running watch. Events arrive through the callbacks until `stop()`. */
 export declare class WatchHandle {
@@ -65,7 +75,9 @@ export declare class WatchHandle {
     get done(): Promise<void>;
     /** Start delivering again from where it left off, after a pause. */
     resume(): void;
-    /** Stop the watch in the sandbox, and stop delivering. */
+    /** Stop the watch in the sandbox. What changed before the stop is still
+     * delivered: the watch reports it and ends, and this returns once that has
+     * arrived (at most 5 s). Called from inside a callback, it stops at once. */
     stop(options?: RequestOptions): Promise<void>;
     /** @internal */
     begin(): this;
@@ -85,6 +97,15 @@ export declare function sandboxWatches(t: Transport, sandboxId: string): {
         lostBytes: number;
         ended: boolean;
     }>;
+    /** Starts a watch whose changes Runtime sends to the account's webhooks
+     * as `sandbox.files.changed` events, with nothing reading it here:
+     *
+     *   await sbx.files.watches.webhook("/workspace/app", { recursive: true });
+     *
+     * Runs until stopped (timeoutMs 0) unless given a timeout. */
+    webhook: (path: string, input?: WebhookWatchOptions) => Promise<WatchInfo & {
+        cursor: number;
+    }>;
     stop: (id: string, options?: RequestOptions) => Promise<{
         stopped: boolean;
     }>;

package/dist/products/watch.js

@@ -1,3 +1,5 @@
+import { WEBHOOK_WATCH_TIMEOUT_MS } from "../api-defaults.js";
+import { RuntimeError } from "../errors.js";
 /** A running watch. Events arrive through the callbacks until `stop()`. */
 export class WatchHandle {
     t;
@@ -8,6 +10,11 @@ export class WatchHandle {
     onEvent;
     cursor;
     #stopped = false;
+    /** stop() was called: deliver what the watch reports until its end. */
+    #stopping = false;
+    /** Callbacks under way. */
+    #delivering = 0;
+    #exitNotified = false;
     #following;
     #abort = new AbortController();
     constructor(t, base, id, path, cursor, options, onEvent) {
@@ -25,22 +32,42 @@ export class WatchHandle {
     }
     /** Start delivering again from where it left off, after a pause. */
     resume() {
-        if (this.#stopped)
+        if (this.#stopped || this.#stopping)
             throw new Error("This watch was stopped");
         this.#abort = new AbortController();
         this.begin();
     }
-    /** Stop the watch in the sandbox, and stop delivering. */
+    /** Stop the watch in the sandbox. What changed before the stop is still
+     * delivered: the watch reports it and ends, and this returns once that has
+     * arrived (at most 5 s). Called from inside a callback, it stops at once. */
     async stop(options) {
-        if (this.#stopped)
+        if (this.#stopped || this.#stopping)
             return;
-        this.#stopped = true;
-        this.#abort.abort();
+        this.#stopping = true;
         await this.t
             .json({ method: "DELETE", path: `${this.base}/${encodeURIComponent(this.id)}`, ...options })
             .catch(() => undefined);
-        await this.#following?.catch(() => undefined);
-        this.options.onExit?.("stopped");
+        // Inside a callback, #following is awaiting the caller: waiting for it
+        // here would make that callback await itself.
+        if (this.#following && this.#delivering === 0) {
+            let timer;
+            await Promise.race([
+                this.#following.catch(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, 5_000);
+                }),
+            ]);
+            clearTimeout(timer);
+        }
+        this.#stopped = true;
+        this.#abort.abort();
+        this.#notifyExit("stopped");
+    }
+    #notifyExit(reason) {
+        if (this.#exitNotified)
+            return;
+        this.#exitNotified = true;
+        this.options.onExit?.(reason);
     }
     async #follow() {
         for (;;) {
@@ -55,21 +82,38 @@ export class WatchHandle {
                 })) {
                     this.cursor = event.cursor ?? this.cursor;
                     if (event.k === "events") {
-                        if (this.options.onBatch)
-                            await this.options.onBatch(event.events);
-                        if (this.onEvent)
-                            for (const item of event.events)
-                                await this.onEvent(item);
+                        this.#delivering++;
+                        try {
+                            if (this.options.onBatch)
+                                await this.options.onBatch(event.events);
+                            if (this.#stopped)
+                                return;
+                            if (this.onEvent)
+                                for (const item of event.events) {
+                                    await this.onEvent(item);
+                                    if (this.#stopped)
+                                        return;
+                                }
+                        }
+                        finally {
+                            this.#delivering--;
+                        }
                     }
                     else if (event.k === "continue")
                         next = "continue";
                     else if (event.k === "end" || event.k === "paused") {
                         if (!this.#stopped)
-                            this.options.onExit?.(event.k === "paused" ? "paused" : event.reason);
+                            this.#notifyExit(event.k === "paused" ? "paused" : event.reason);
                         return;
                     }
                     else if (event.k === "failure")
-                        throw new Error(`${event.code}: ${event.message}`);
+                        throw new RuntimeError({
+                            code: event.code,
+                            status: event.status ?? 0,
+                            message: event.message,
+                            ...(event.hint ? { hint: event.hint } : {}),
+                            ...(event.requestId ? { requestId: event.requestId } : {}),
+                        });
                     else
                         this.options.onNotice?.(event);
                 }
@@ -85,6 +129,7 @@ export class WatchHandle {
     }
     /** @internal */
     begin() {
+        this.#exitNotified = false;
         this.#following = this.#follow();
         // An error surfaces through `done`; nothing is left unhandled meanwhile.
         this.#following.catch(() => undefined);
@@ -126,6 +171,22 @@ export function sandboxWatches(t, sandboxId) {
             query: { cursor, ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}) },
             ...options,
         }),
+        /** Starts a watch whose changes Runtime sends to the account's webhooks
+         * as `sandbox.files.changed` events, with nothing reading it here:
+         *
+         *   await sbx.files.watches.webhook("/workspace/app", { recursive: true });
+         *
+         * Runs until stopped (timeoutMs 0) unless given a timeout. */
+        webhook: (path, input = {}) => {
+            const { idempotencyKey, signal, timeoutMs, ...rest } = input;
+            return t.json({
+                method: "POST",
+                path: base,
+                body: { path, ...rest, timeoutMs: timeoutMs ?? WEBHOOK_WATCH_TIMEOUT_MS, webhook: true },
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+                ...(signal ? { signal } : {}),
+            });
+        },
         stop: (id, options) => t.json({
             method: "DELETE",
             path: `${base}/${encodeURIComponent(id)}`,