withruntime 0.8.4 → 0.9.0

package/dist/e2b/code-interpreter.d.ts

@@ -3,8 +3,7 @@
  *   import { Sandbox } from "withruntime/e2b/code-interpreter";
  *
  * runCode runs in Runtime's interpreter (sandbox.runtime.interpreter):
- * stateful Python and JavaScript contexts, as in E2B. Other languages throw
- * NotSupportedError. */
+ * stateful contexts in every E2B interpreter language. */
 import type { Runtime } from "../client.js";
 import type { ConnectionOpts } from "./client.js";
 import { Sandbox as BaseSandbox } from "./sandbox.js";
@@ -13,11 +12,11 @@ export type RunCodeLanguage = "python" | "javascript" | "typescript" | "r" | "ja
 /** A line of output, as E2B's callbacks receive it. */
 export declare class OutputMessage {
     readonly line: string;
-    /** Unix epoch in nanoseconds (from the client's clock). */
+    /** Unix epoch in microseconds (from the client's clock), as in E2B. */
     readonly timestamp: number;
     readonly error: boolean;
     constructor(line: string, 
-    /** Unix epoch in nanoseconds (from the client's clock). */
+    /** Unix epoch in microseconds (from the client's clock), as in E2B. */
     timestamp: number, error: boolean);
     toString(): string;
 }
@@ -110,7 +109,7 @@ export interface RunCodeOpts {
     envs?: Record<string, string>;
     /** Default 60 000, as in E2B. */
     timeoutMs?: number;
-    /** Accepted and ignored: Runtime's SDK allows the run its timeout plus a minute. */
+    /** Deadline for receiving response headers; 0 disables it. */
     requestTimeoutMs?: number;
 }
 export interface CreateCodeContextOpts {

package/dist/e2b/code-interpreter.js

@@ -8,7 +8,7 @@ export class OutputMessage {
     timestamp;
     error;
     constructor(line, 
-    /** Unix epoch in nanoseconds (from the client's clock). */
+    /** Unix epoch in microseconds (from the client's clock), as in E2B. */
     timestamp, error) {
         this.line = line;
         this.timestamp = timestamp;
@@ -122,50 +122,18 @@ function lines(text) {
     return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
 }
 function language(requested) {
-    if (requested === undefined || requested === "python")
-        return "python";
-    if (requested === "javascript" || requested === "js")
-        return "javascript";
-    throw new NotSupportedError(`Running ${requested} code in the interpreter`, requested === "bash"
-        ? "Use sandbox.commands.run(code)."
-        : "Runtime's interpreter runs Python and JavaScript; install the language and run it with sandbox.commands.run(...).");
+    const selected = requested === "js" ? "javascript" : (requested ?? "python");
+    if (["python", "javascript", "typescript", "r", "java", "bash", "go"].includes(selected))
+        return selected;
+    throw new NotSupportedError(`Running ${requested} code in the interpreter`, "Use Python, JavaScript, TypeScript, R, Java, Bash or Go.");
 }
 /** The code interpreter sandbox: everything the base Sandbox has, plus runCode
  * and code contexts. */
 export class Sandbox extends BaseSandbox {
     static defaultTemplate = "code-interpreter-v1";
-    /** Contexts made to carry the sandbox's envs, one per language. */
-    #envContexts = new Map();
     get #interpreter() {
         return this.runtime.interpreter;
     }
-    /** The context a run goes to: the one asked for; else, when the sandbox has
-     * envs, a context made once with them; else Runtime's default one. */
-    async #contextFor(lang, context) {
-        if (context)
-            return context.id;
-        if (!Object.keys(this.envs).length)
-            return undefined;
-        let id = this.#envContexts.get(lang);
-        if (!id) {
-            id = guard("sandbox", async () => {
-                const made = await this.#interpreter.contexts.create({
-                    id: `e2b-${lang}`,
-                    language: lang,
-                    env: this.envs,
-                });
-                return made.id;
-            }).catch(async (error) => {
-                // Made already, by another object connected to this sandbox.
-                const existing = (await this.#interpreter.contexts.list()).find((one) => one.id === `e2b-${lang}`);
-                if (existing)
-                    return existing.id;
-                throw error;
-            });
-            this.#envContexts.set(lang, id);
-        }
-        return id;
-    }
     async #inline(result) {
         const data = { ...result.data };
         for (const [mime, ref] of Object.entries(result.refs ?? {})) {
@@ -186,28 +154,59 @@ export class Sandbox extends BaseSandbox {
         if (opts.envs && Object.keys(opts.envs).length)
             throw new NotSupportedError("Environment variables for one run (runCode envs)", "Make a context with them: sandbox.runtime.interpreter.contexts.create({ env }), then runCode(code, { context: { id } }).");
         const lang = language(opts.context?.language ?? opts.language);
-        const context = await this.#contextFor(lang, opts.context);
-        const now = () => Date.now() * 1_000_000;
-        const streaming = opts.onStdout || opts.onStderr || opts.onResult || opts.onError;
-        const execution = await guard("sandbox", () => this.#interpreter.run(code, {
-            ...(context ? { context } : { language: lang }),
-            timeoutMs: opts.timeoutMs ?? 60_000,
-            ...(streaming
-                ? {
-                    onStdout: (text) => void opts.onStdout?.(new OutputMessage(text, now(), false)),
-                    onStderr: (text) => void opts.onStderr?.(new OutputMessage(text, now(), true)),
-                    onError: (error) => void opts.onError?.(new ExecutionError(error.name, error.value, error.traceback)),
-                }
-                : {}),
-        }));
+        const context = opts.context?.id;
+        const now = () => Date.now() * 1_000;
+        const streamedResults = [];
+        const controller = new AbortController();
+        const requestTimeout = opts.requestTimeoutMs ?? this.requestTimeoutMs;
+        const timeout = opts.timeoutMs ?? 60_000;
+        let stage = "Request";
+        let timer;
+        const arm = (milliseconds) => {
+            clearTimeout(timer);
+            if (milliseconds)
+                timer = setTimeout(() => controller.abort(), milliseconds);
+        };
+        arm(requestTimeout);
+        let execution;
+        try {
+            execution = await guard("sandbox", () => this.#interpreter.run(code, {
+                ...(context ? { context } : { language: lang }),
+                // E2B times out its reader; it does not send a kernel deadline.
+                timeoutMs: 0,
+                requestTimeoutMs: 0,
+                interruptOnDisconnect: false,
+                signal: controller.signal,
+                onResponse: () => {
+                    stage = "Execution";
+                    arm(timeout);
+                },
+                // Stream even without callbacks: the header/body deadlines are separate.
+                onStdout: (text) => opts.onStdout?.(new OutputMessage(text, now(), false)),
+                onStderr: (text) => opts.onStderr?.(new OutputMessage(text, now(), true)),
+                onError: (error) => opts.onError?.(new ExecutionError(error.name, error.value, error.traceback)),
+                onResult: async (result) => {
+                    const mapped = new Result(await this.#inline(result), result.main);
+                    streamedResults.push(mapped);
+                    await opts.onResult?.(mapped);
+                },
+            }));
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw new TimeoutError(`${stage} timed out — the '${stage === "Request" ? "requestTimeoutMs" : "timeoutMs"}' option can be used to increase this timeout`);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
         if (execution.status === "timeout")
             throw new TimeoutError(`Execution timed out after ${opts.timeoutMs ?? 60_000} ms: pass a larger 'timeoutMs'.`);
         if (execution.status === "lost")
             throw new SandboxError("The interpreter lost this run (its context stopped); run it again.");
-        const results = await Promise.all(execution.results.map(async (result) => new Result(await this.#inline(result), result.main)));
-        if (opts.onResult)
-            for (const result of results)
-                await opts.onResult(result);
+        const results = streamedResults.length === execution.results.length
+            ? streamedResults
+            : await Promise.all(execution.results.map(async (result) => new Result(await this.#inline(result), result.main)));
         return new Execution(results, { stdout: lines(execution.stdout), stderr: lines(execution.stderr) }, execution.error
             ? new ExecutionError(execution.error.name, execution.error.value, execution.error.traceback)
             : undefined, execution.executionCount ?? undefined);
@@ -217,7 +216,6 @@ export class Sandbox extends BaseSandbox {
         const made = await guard("sandbox", () => this.#interpreter.contexts.create({
             language: lang,
             ...(opts.cwd ? { cwd: opts.cwd } : {}),
-            ...(Object.keys(this.envs).length ? { env: this.envs } : {}),
         }));
         return { id: made.id, language: made.language, cwd: made.cwd };
     }

package/dist/e2b/commands.d.ts

@@ -18,7 +18,7 @@ export interface CommandStartOpts extends CommandRequestOpts {
     onStdout?: (data: string) => void | Promise<void>;
     onStderr?: (data: string) => void | Promise<void>;
     stdin?: boolean;
-    /** Default 60 000, as in E2B. 0 is no limit (Runtime's longest, 24 hours). */
+    /** Stream connection deadline, 60 000 by default. Zero waits without a deadline. */
     timeoutMs?: number;
 }
 export type CommandConnectOpts = Pick<CommandStartOpts, "onStderr" | "onStdout" | "timeoutMs"> & CommandRequestOpts;
@@ -32,11 +32,11 @@ export interface ProcessInfo {
     envs: Record<string, string>;
     cwd?: string;
 }
-/** The shared state a sandbox's modules need: the Runtime sandbox, the
- * environment given at create, and the one-time /home/user link. */
+/** The shared state a sandbox's modules need: the Runtime sandbox and the
+ * one-time /home/user link. The environment given at create is Runtime's to
+ * keep: it is the sandbox's own `env`, added to every command there. */
 export interface SandboxContext {
     readonly runtime: RuntimeSandbox;
-    readonly envs: Record<string, string>;
     /** Makes /home/user (E2B's home) lead to /workspace (Runtime's), once, when
      * something names it. */
     ensureHome(text: string | undefined): Promise<void>;
@@ -80,6 +80,7 @@ export declare class CommandHandle {
         stdin: boolean;
         timeoutMs: number;
         cursor?: number;
+        signal?: AbortSignal;
         onStdout?: (data: string) => void | Promise<void>;
         onStderr?: (data: string) => void | Promise<void>;
     });

package/dist/e2b/commands.js

@@ -1,7 +1,5 @@
-import { request } from "./client.js";
 import { CommandExitError, guard, InvalidArgumentError, NotSupportedError, SandboxError, TimeoutError, translate, } from "./errors.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
-const LONGEST_MS = 86_400_000;
 /** E2B's pids are numbers; Runtime's process ids are strings. The number is a
  * 31-bit FNV-1a hash of the id, so every client derives the same one. */
 export function pidOf(processId) {
@@ -19,9 +17,9 @@ function refuseUser(user) {
 function timeoutFor(timeoutMs) {
     if (timeoutMs === undefined)
         return DEFAULT_TIMEOUT_MS;
-    if (timeoutMs === 0)
-        return LONGEST_MS;
-    return Math.min(timeoutMs, LONGEST_MS);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0)
+        throw new InvalidArgumentError("timeoutMs must be a nonnegative whole number.");
+    return timeoutMs;
 }
 function timedOut(timeoutMs) {
     return new TimeoutError(`Command timed out after ${timeoutMs} ms: this error is likely due to exceeding 'timeoutMs'. ` +
@@ -37,7 +35,7 @@ function toResult(result) {
         stdout: result.stdout,
         stderr: result.stderr,
         ...(exitCode === 0
-            ? {}
+            ? { error: "" }
             : {
                 error: result.exitCode === null ? "terminated by a signal" : `exit status ${exitCode}`,
             }),
@@ -61,42 +59,32 @@ export class Commands {
         this.#ctx = ctx;
     }
     #env(envs) {
-        const merged = { ...this.#ctx.envs, ...envs };
-        return Object.keys(merged).length ? { env: merged } : {};
+        return envs && Object.keys(envs).length ? { env: envs } : {};
     }
     async run(cmd, opts = {}) {
+        opts.signal?.throwIfAborted();
         refuseUser(opts.user);
         await this.#ctx.ensureHome(`${cmd}\n${opts.cwd ?? ""}`);
         const timeoutMs = timeoutFor(opts.timeoutMs);
-        if (opts.background || opts.stdin) {
-            const handle = await this.#start(cmd, opts, timeoutMs);
-            return opts.background ? handle : handle.wait();
-        }
-        /* Always streamed, so the result holds the whole output as E2B's does: an
-           exec with no output callback returns at most 64 KiB of each stream. */
-        const onStdout = opts.onStdout;
-        const onStderr = opts.onStderr;
-        const result = await guard("sandbox", () => this.#ctx.runtime.exec(cmd, {
-            ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
-            ...this.#env(opts.envs),
-            timeoutMs,
-            onStdout: (text) => void onStdout?.(text),
-            ...(onStderr ? { onStderr: (text) => void onStderr(text) } : {}),
-            ...(opts.signal ? { signal: opts.signal } : {}),
-        }));
-        return settle({ ...result, truncated: result.stdoutTruncated === true || result.stderrTruncated === true }, timeoutMs);
+        const handle = await this.#start(cmd, opts, timeoutMs);
+        return opts.background ? handle : handle.wait();
     }
     async #start(cmd, opts, timeoutMs) {
+        opts.signal?.throwIfAborted();
+        const requestDeadline = opts.requestTimeoutMs
+            ? AbortSignal.timeout(opts.requestTimeoutMs)
+            : undefined;
+        const signals = [opts.signal, requestDeadline].filter((signal) => signal !== undefined);
         const process = await guard("sandbox", () => this.#ctx.runtime.spawn(cmd, {
             ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
             ...this.#env(opts.envs),
-            timeoutMs,
             ...(opts.stdin ? { stdin: "pipe" } : {}),
-            ...request(opts),
+            ...(signals.length ? { signal: AbortSignal.any(signals) } : {}),
         }));
         return new CommandHandle(process, {
             stdin: opts.stdin === true,
             timeoutMs,
+            signal: opts.signal,
             ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
             ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
         });
@@ -142,6 +130,7 @@ export class Commands {
         return new CommandHandle(process, {
             stdin: process.info.stdinOpen,
             timeoutMs: timeoutFor(opts.timeoutMs),
+            signal: opts.signal,
             cursor: process.info.outputBytes,
             ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
             ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
@@ -173,19 +162,34 @@ export class CommandHandle {
     #truncated = false;
     #failure;
     #disconnected = false;
+    #deadline;
     constructor(process, options) {
         this.#process = process;
         this.pid = pidOf(process.id);
         this.#stdin = options.stdin;
         this.#timeoutMs = options.timeoutMs;
+        // E2B's timeout limits the subscription. It never asks us to kill the
+        // process: the sandbox lease still bounds the workload after disconnect.
+        if (options.timeoutMs > 0) {
+            this.#deadline = setTimeout(() => {
+                this.#failure = timedOut(options.timeoutMs);
+                this.#abort.abort();
+            }, options.timeoutMs);
+            this.#deadline.unref?.();
+        }
         this.#done = this.#follow(options);
     }
     async #follow(options) {
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, this.#abort.signal])
+            : this.#abort.signal;
         try {
             for await (const event of this.#process.output({
                 ...(options.cursor ? { cursor: options.cursor } : {}),
-                signal: this.#abort.signal,
+                signal,
             })) {
+                if (this.#disconnected || signal.aborted)
+                    break;
                 if (event.type === "stdout") {
                     this.#stdout += event.data;
                     await options.onStdout?.(event.data);
@@ -203,12 +207,16 @@ export class CommandHandle {
             }
         }
         catch (error) {
-            if (!this.#disconnected) {
+            if (!this.#disconnected && !this.#failure) {
                 const translated = translate(error, "sandbox");
                 this.#failure =
                     translated instanceof Error ? translated : new SandboxError(String(translated));
             }
         }
+        finally {
+            if (this.#deadline !== undefined)
+                clearTimeout(this.#deadline);
+        }
     }
     /** The exit code, or undefined while the command runs. */
     get exitCode() {

package/dist/e2b/errors.js

@@ -77,7 +77,7 @@ export class NotSupportedError extends SandboxError {
 export class CommandExitError extends SandboxError {
     #result;
     constructor(result) {
-        super(`Command exited with code ${result.exitCode} and error:\n${result.stderr}`);
+        super(result.error);
         this.#result = result;
     }
     get exitCode() {

package/dist/e2b/filesystem.d.ts

@@ -14,9 +14,9 @@ export interface EntryInfo extends WriteInfo {
     size: number;
     mode: number;
     permissions: string;
-    /** Runtime's listing does not say who owns a file: always "". */
+    /** File owner when returned by the native guest. */
     owner: string;
-    /** Runtime's listing does not say a file's group: always "". */
+    /** File group when returned by the native guest. */
     group: string;
     modifiedTime?: Date;
     symlinkTarget?: string;
@@ -32,11 +32,14 @@ export interface FilesystemEvent {
     /** Relative to the watched directory. */
     name: string;
     type: FilesystemEventType;
+    entry?: EntryInfo;
 }
 export interface WatchOpts extends FilesystemRequestOpts {
-    /** How long the watch runs; 0 is Runtime's maximum, 24 hours. Default 60000. */
+    /** How long the subscription runs; 0 has no subscription deadline. Default 60000. */
     timeoutMs?: number;
     recursive?: boolean;
+    includeEntry?: boolean;
+    allowNetworkMounts?: boolean;
 }
 export interface E2BWatchHandle {
     stop(): Promise<void>;
@@ -98,9 +101,8 @@ export declare class Filesystem {
     remove(path: string, opts?: FilesystemRequestOpts): Promise<void>;
     exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>;
     getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>;
-    /** E2B's watchDir on Runtime's file watch: the same events (CREATE, WRITE,
-     * REMOVE, RENAME, CHMOD) with names relative to the directory, stopped
-     * with `handle.stop()`. `timeoutMs` 0 is Runtime's 24-hour maximum. */
+    /** E2B's watchDir on Runtime's file watch. A local deadline preserves
+     * subsecond subscriptions; 0 runs until stopped or the sandbox ends. */
     watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts & {
         onExit?: (err?: Error) => void | Promise<void>;
     }): Promise<E2BWatchHandle>;

package/dist/e2b/filesystem.js

@@ -1,5 +1,5 @@
 import { request } from "./client.js";
-import { FileNotFoundError, guard, NotSupportedError } from "./errors.js";
+import { FileNotFoundError, guard, InvalidArgumentError, NotSupportedError, TimeoutError, } from "./errors.js";
 export var FileType;
 (function (FileType) {
     FileType["FILE"] = "file";
@@ -42,8 +42,9 @@ function entryInfo(entry) {
         size: entry.size,
         mode,
         permissions: PERMISSIONS[(bits >> 6) & 7] + PERMISSIONS[(bits >> 3) & 7] + PERMISSIONS[bits & 7],
-        owner: "",
-        group: "",
+        owner: entry.owner ?? "",
+        group: entry.group ?? "",
+        ...(entry.symlinkTarget ? { symlinkTarget: entry.symlinkTarget } : {}),
         modifiedTime: new Date(entry.modifiedAt),
     };
 }
@@ -73,8 +74,10 @@ export class Filesystem {
         return this.#ctx.runtime.files;
     }
     async #path(path, opts) {
+        opts.signal?.throwIfAborted();
         refuse(opts);
         await this.#ctx.ensureHome(path);
+        opts.signal?.throwIfAborted();
         return absolute(path);
     }
     async read(path, opts = {}) {
@@ -98,6 +101,7 @@ export class Filesystem {
         return this.#writeOne(pathOrFiles, dataOrOpts, maybeOpts ?? {});
     }
     async writeFiles(files, opts = {}) {
+        opts.signal?.throwIfAborted();
         const written = [];
         for (const file of files)
             written.push(await this.#writeOne(file.path, file.data, opts));
@@ -112,61 +116,156 @@ export class Filesystem {
     /** A directory's entries, hidden ones included; `depth` goes deeper. */
     async list(path, opts = {}) {
         const dir = await this.#path(path, opts);
-        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true }));
+        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true, ...request(opts) }));
         return entries.map(entryInfo);
     }
     /** Makes a directory and its parents. False when it already existed. */
     async makeDir(path, opts = {}) {
         const dir = await this.#path(path, opts);
-        if (await guard("file", () => this.#files.exists(dir)))
+        if (await guard("file", () => this.#files.exists(dir, request(opts))))
             return false;
-        await guard("file", () => this.#files.mkdir(dir, { parents: true }));
+        await guard("file", () => this.#files.mkdir(dir, { parents: true, ...request(opts) }));
         return true;
     }
     /** Moves a file or directory, replacing a file at the new path, as E2B does. */
     async rename(oldPath, newPath, opts = {}) {
         const from = await this.#path(oldPath, opts);
         const to = await this.#path(newPath, opts);
-        await guard("file", () => this.#files.rename(from, to, { overwrite: true }));
+        await guard("file", () => this.#files.rename(from, to, { overwrite: true, ...request(opts) }));
         return this.getInfo(to, opts);
     }
     /** Removes a file, or a directory with everything in it. */
     async remove(path, opts = {}) {
         const target = await this.#path(path, opts);
-        await guard("file", () => this.#files.remove(target, { recursive: true }));
+        await guard("file", () => this.#files.remove(target, { recursive: true, ...request(opts) }));
     }
     async exists(path, opts = {}) {
         const target = await this.#path(path, opts);
-        return guard("file", () => this.#files.exists(target));
+        return guard("file", () => this.#files.exists(target, request(opts)));
     }
     async getInfo(path, opts = {}) {
         const target = await this.#path(path, opts);
-        const stat = await guard("file", () => this.#files.stat(target));
+        const stat = await guard("file", () => this.#files.stat(target, request(opts)));
         if (!stat.exists)
             throw new FileNotFoundError(`${target} does not exist.`);
         return entryInfo(stat);
     }
-    /** E2B's watchDir on Runtime's file watch: the same events (CREATE, WRITE,
-     * REMOVE, RENAME, CHMOD) with names relative to the directory, stopped
-     * with `handle.stop()`. `timeoutMs` 0 is Runtime's 24-hour maximum. */
+    /** E2B's watchDir on Runtime's file watch. A local deadline preserves
+     * subsecond subscriptions; 0 runs until stopped or the sandbox ends. */
     async watchDir(path, onEvent, opts = {}) {
+        opts.signal?.throwIfAborted();
+        if (opts.allowNetworkMounts)
+            throw new NotSupportedError("Watching network mounts", "Watch a local sandbox directory instead.");
+        const lifetime = opts.timeoutMs ?? 60000;
+        if (!Number.isFinite(lifetime) || lifetime < 0)
+            throw new InvalidArgumentError("timeoutMs must be a nonnegative finite number.");
         const target = await this.#path(path, opts);
         const prefix = target.endsWith("/") ? target : `${target}/`;
-        const lifetime = opts.timeoutMs === 0 ? 86_400_000 : (opts.timeoutMs ?? 60_000);
-        const watch = await guard("file", () => this.#files.watch(target, (event) => onEvent({
-            name: event.path.startsWith(prefix) ? event.path.slice(prefix.length) : event.path,
-            type: event.type,
-        }), {
-            recursive: opts.recursive === true,
-            timeoutMs: Math.max(1_000, Math.min(86_400_000, lifetime)),
-            onExit: (reason) => {
-                if (reason === "stopped")
+        let exited = false;
+        let native;
+        let stopping;
+        let timer;
+        const lifetimeAbort = new AbortController();
+        const signal = opts.signal
+            ? AbortSignal.any([opts.signal, lifetimeAbort.signal])
+            : lifetimeAbort.signal;
+        const exit = async (error) => {
+            if (exited)
+                return;
+            exited = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            opts.signal?.removeEventListener("abort", onAbort);
+            try {
+                await opts.onExit?.(error);
+            }
+            catch {
+                /* Upstream treats a throwing terminal callback as handled. */
+            }
+        };
+        const stopRemote = () => {
+            if (!native)
+                return Promise.resolve();
+            return (stopping ??= native.stop());
+        };
+        const close = async (error) => {
+            const callback = exit(error);
+            try {
+                await stopRemote();
+            }
+            finally {
+                await callback;
+            }
+        };
+        const onAbort = () => {
+            const error = opts.signal?.reason instanceof Error
+                ? opts.signal.reason
+                : new Error("The watch was aborted.");
+            void close(error).catch(() => undefined);
+        };
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        if (opts.signal?.aborted)
+            onAbort();
+        if (lifetime > 0) {
+            const deadline = Date.now() + lifetime;
+            const schedule = () => {
+                timer = setTimeout(() => {
+                    if (exited)
+                        return;
+                    if (Date.now() < deadline) {
+                        schedule();
+                        return;
+                    }
+                    const error = new TimeoutError("Filesystem watch timed out.");
+                    // Mark the terminal result before native cancellation can report a
+                    // clean end. The same signal also cancels creation still in flight.
+                    void close(error).catch(() => undefined);
+                    lifetimeAbort.abort(error);
+                }, Math.min(2147483647, Math.max(0, deadline - Date.now())));
+                timer.unref?.();
+            };
+            schedule();
+        }
+        try {
+            const watch = await guard("file", () => this.#files.watch(target, async (event) => {
+                if (exited)
                     return;
-                void opts.onExit?.(reason === "timeout" || reason === "paused"
-                    ? undefined
-                    : new Error(`The watch ended: ${reason}`));
-            },
-        }));
-        return { stop: () => watch.stop() };
+                let entry;
+                if (opts.includeEntry) {
+                    try {
+                        entry = await this.getInfo(event.path, { ...opts, signal });
+                    }
+                    catch (error) {
+                        if (!(error instanceof FileNotFoundError))
+                            throw error;
+                    }
+                }
+                if (!exited)
+                    await onEvent({
+                        name: event.path.startsWith(prefix) ? event.path.slice(prefix.length) : event.path,
+                        type: event.type,
+                        ...(entry ? { entry } : {}),
+                    });
+            }, {
+                recursive: opts.recursive === true,
+                timeoutMs: 0,
+                signal,
+                onExit: (reason) => {
+                    void exit(reason === "timeout" ? new TimeoutError("Filesystem watch timed out.") : undefined);
+                },
+                onNotice: (notice) => {
+                    void close(new Error(`Filesystem events were lost (${notice.k}); rescan the directory and start a new watch.`)).catch(() => undefined);
+                },
+            }));
+            native = watch;
+            if (exited)
+                await stopRemote();
+            void watch.done?.then(() => exit(), (error) => close(error instanceof Error ? error : new Error(String(error))).catch(() => undefined));
+            return { stop: () => close() };
+        }
+        catch (error) {
+            await close(error instanceof Error ? error : new Error(String(error))).catch(() => undefined);
+            throw error;
+        }
     }
 }

package/dist/e2b/sandbox.d.ts

@@ -26,7 +26,8 @@ export interface SandboxOpts extends ConnectionOpts {
     template?: string;
     /** Stored as the sandbox's labels (at most 32, values up to 256 characters). */
     metadata?: Record<string, string>;
-    /** Given to every command and code run through this object. */
+    /** The sandbox's own environment: every command, terminal and code run in it
+     * gets these, whoever connects. Values are never shown again. */
     envs?: Record<string, string>;
     /** Default 300 000. Runtime's leases run 60 s to 1 hour; shorter rounds up
      * to 60 s (with a warning), longer is refused. */
@@ -88,17 +89,17 @@ export type SandboxListOpts = SandboxApiOpts & {
 };
 export declare class Sandbox {
     #private;
+    protected readonly requestTimeoutMs: number;
     protected static readonly defaultTemplate: string;
     readonly files: Filesystem;
     readonly commands: Commands;
     /** Use Sandbox.create or Sandbox.connect. */
-    constructor(runtime: RuntimeSandbox, client: Runtime, envs?: Record<string, string>);
+    constructor(runtime: RuntimeSandbox, client: Runtime, requestTimeoutMs?: number);
     get sandboxId(): string;
     /** The Runtime sandbox underneath: previews, network, desktop, interpreter,
      * processes, terminal and the rest of Runtime's SDK. */
     get runtime(): RuntimeSandbox;
     protected get client(): Runtime;
-    protected get envs(): Record<string, string>;
     /** Creates a sandbox from `template` (default "base", Runtime's stock image)
      * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
      * Funding is left to Runtime: the free trial while the account has trial