withruntime 0.11.1 → 0.12.0

package/dist/domains/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/domains`: Domains alone. Your own hostname for a sandbox's port, with HTTPS.
+ *
+ *   import { domains } from "withruntime/domains";
+ *   const client = domains(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type { Domain, CheckedDomain, DnsRecord } from "../products/network-products.js";
+/** `runtime.domains` of a client made with `options`. */
+export declare function domains(options?: RuntimeOptions): Runtime["domains"];

package/dist/domains/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/domains`: Domains alone. Your own hostname for a sandbox's port, with HTTPS.
+ *
+ *   import { domains } from "withruntime/domains";
+ *   const client = domains(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.domains` of a client made with `options`. */
+export function domains(options) {
+    return new Runtime(options).domains;
+}

package/dist/e2b/client.d.ts

@@ -43,15 +43,28 @@ export interface RuntimeOpts {
 /** Refuses the E2B-only connection options: they point at E2B, and quietly
  * dropping one would send the call somewhere its author did not mean. */
 export declare function refuseE2BConnection(opts?: ConnectionOpts): void;
+/** Connections the adapter's own client may hold at once: E2B's SDK has no
+ * cap of its own, so an orchestrator that drives a thousand sandboxes from one
+ * process runs every command at once. 4,096 is the widest room Runtime's edge
+ * gives an address that has used a valid key (api.md, "Limits"); the edge and
+ * the API answer anything past an account's room with a retry, which the
+ * client waits out. Runtime's own SDK keeps 48. */
+export declare const E2B_MAX_CONNECTIONS = 4096;
+/** Said once per process, the first time a call has to wait for a
+ * connection: E2B never holds a call back, so a caller should hear it. */
+export declare function warnQueued(maxConnections: number): void;
 /** The Runtime client for these options: an explicit client, else one per key,
  * made once and reused so its connections stay open. */
 export declare function clientFor(opts?: ConnectionOpts & {
     runtime?: RuntimeOpts;
 }): Runtime;
 /** Explicit key, then RUNTIME_API_KEY, then E2B_API_KEY when it holds a
- * Runtime key; undefined lets the Runtime SDK find the saved login. */
+ * Runtime key; undefined, when none is set, lets the Runtime SDK find the
+ * saved login. An E2B key is refused, never sent. */
 export declare function pickKey(explicit?: string): string | undefined;
-/** Test hook: forget the cached clients. */
+/** Where the key in use came from, as an error names it. */
+export declare function keySource(explicit?: string): string;
+/** Test hook: forget the cached clients and the warnings. */
 export declare function resetClients(): void;
 /** Request options for a Runtime call from E2B's. */
 export declare function request(opts?: {

package/dist/e2b/client.js

@@ -26,6 +26,23 @@ export function refuseE2BConnection(opts = {}) {
         throw new NotSupportedError("E2B's debug mode (a local envd)", "Remove debug: true; there is no local Runtime guest to connect to.");
 }
 const clients = new Map();
+/** Connections the adapter's own client may hold at once: E2B's SDK has no
+ * cap of its own, so an orchestrator that drives a thousand sandboxes from one
+ * process runs every command at once. 4,096 is the widest room Runtime's edge
+ * gives an address that has used a valid key (api.md, "Limits"); the edge and
+ * the API answer anything past an account's room with a retry, which the
+ * client waits out. Runtime's own SDK keeps 48. */
+export const E2B_MAX_CONNECTIONS = 4096;
+let warnedQueued = false;
+/** Said once per process, the first time a call has to wait for a
+ * connection: E2B never holds a call back, so a caller should hear it. */
+export function warnQueued(maxConnections) {
+    if (warnedQueued || typeof process === "undefined" || !process.emitWarning)
+        return;
+    warnedQueued = true;
+    process.emitWarning(`More than ${maxConnections} calls and command streams are open at once from this process, so the rest wait their turn. ` +
+        "Pass runtime: { client: new Runtime({ maxConnections }) } for more.", { code: "RUNTIME_E2B_QUEUED" });
+}
 /** The Runtime client for these options: an explicit client, else one per key,
  * made once and reused so its connections stay open. */
 export function clientFor(opts = {}) {
@@ -36,30 +53,67 @@ export function clientFor(opts = {}) {
     const cacheKey = key ?? "";
     let client = clients.get(cacheKey);
     if (!client) {
-        client = new Runtime(key ? { apiKey: key } : {});
+        client = new Runtime({
+            ...(key ? { apiKey: key } : {}),
+            maxConnections: E2B_MAX_CONNECTIONS,
+            onQueued: warnQueued,
+        });
         clients.set(cacheKey, client);
     }
     return client;
 }
 /** Explicit key, then RUNTIME_API_KEY, then E2B_API_KEY when it holds a
- * Runtime key; undefined lets the Runtime SDK find the saved login. */
+ * Runtime key; undefined, when none is set, lets the Runtime SDK find the
+ * saved login. An E2B key is refused, never sent. */
 export function pickKey(explicit) {
     const runtimeKey = env("RUNTIME_API_KEY");
     if (explicit !== undefined && !isE2BKey(explicit))
         return explicit;
-    if (runtimeKey)
+    if (runtimeKey) {
+        warnTwoKeys(runtimeKey, env("E2B_API_KEY"));
         return runtimeKey;
+    }
     if (explicit !== undefined)
         throw new AuthenticationError("The apiKey passed is an E2B API key (e2b_...), and it was not sent. Set RUNTIME_API_KEY to a Runtime key " +
             "(https://withruntime.com/account/keys, or run `npx withruntime login`), or pass the Runtime key as apiKey.");
-    // An E2B key left in E2B_API_KEY is skipped, never sent: the Runtime SDK
-    // then uses the key `npx withruntime login` saved, or says none was found.
+    // An E2B key left in E2B_API_KEY is never sent, and never quietly passed
+    // over for the key `npx withruntime login` saved, which may be another
+    // account's.
     const e2bVariable = env("E2B_API_KEY");
-    return e2bVariable && !isE2BKey(e2bVariable) ? e2bVariable : undefined;
+    if (e2bVariable && isE2BKey(e2bVariable))
+        throw new AuthenticationError("E2B_API_KEY holds an E2B API key (e2b_...), and it was not sent. Set RUNTIME_API_KEY to a Runtime key " +
+            "(https://withruntime.com/account/keys, or run `npx withruntime login`), or put the Runtime key in E2B_API_KEY.");
+    return e2bVariable || undefined;
+}
+/** Where the key in use came from, as an error names it. */
+export function keySource(explicit) {
+    if (explicit !== undefined && !isE2BKey(explicit))
+        return "apiKey";
+    if (env("RUNTIME_API_KEY"))
+        return "RUNTIME_API_KEY";
+    if (env("E2B_API_KEY"))
+        return "E2B_API_KEY";
+    return "the saved login";
+}
+let warnedTwoKeys = false;
+/** Said once per process: RUNTIME_API_KEY wins, as in Runtime's own SDK, but
+ * code written for E2B means E2B_API_KEY, so two different Runtime keys are
+ * likely two accounts, and the wrong one fails later as a missing image
+ * (5 October 2026). */
+function warnTwoKeys(runtimeKey, e2bVariable) {
+    if (!e2bVariable || isE2BKey(e2bVariable) || e2bVariable === runtimeKey)
+        return;
+    if (warnedTwoKeys || typeof process === "undefined" || !process.emitWarning)
+        return;
+    warnedTwoKeys = true;
+    process.emitWarning("RUNTIME_API_KEY and E2B_API_KEY hold different Runtime keys, which may be different accounts; this package uses " +
+        "RUNTIME_API_KEY. Unset one, or set both to the same key.", { code: "RUNTIME_E2B_TWO_KEYS" });
 }
-/** Test hook: forget the cached clients. */
+/** Test hook: forget the cached clients and the warnings. */
 export function resetClients() {
     clients.clear();
+    warnedQueued = false;
+    warnedTwoKeys = false;
 }
 /** Request options for a Runtime call from E2B's. */
 export function request(opts = {}) {

package/dist/e2b/commands.d.ts

@@ -1,6 +1,6 @@
 import type { Process } from "../sandbox.js";
 import type { OutputEvent, ProcessInfo as RuntimeProcessInfo } from "../types.js";
-import type { RequestOptions } from "../transport.js";
+import { type RequestOptions } from "../transport.js";
 import type { RuntimeSandbox } from "./client.js";
 import { TimeoutError, type CommandResult } from "./errors.js";
 export type { CommandResult };
@@ -43,6 +43,9 @@ export interface SandboxContext {
     /** Makes /home/user (E2B's home) lead to /workspace (Runtime's), once, when
      * something names it. */
     ensureHome(text: string | undefined, options?: RequestOptions): Promise<void>;
+    /** Whether /home/user leads to /workspace, linking it first if nothing is
+     * there; false when that cannot be told. Never fails. */
+    homeIsWorkspace(): Promise<boolean>;
 }
 /** 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. */

package/dist/e2b/commands.js

@@ -1,5 +1,6 @@
-import { CommandExitError, guard, InvalidArgumentError, SandboxError, TimeoutError, translate, } from "./errors.js";
-import { commandAs, runAs } from "./users.js";
+import { timeoutSignal } from "../transport.js";
+import { CommandExitError, guard, InvalidArgumentError, SandboxError, SandboxNotFoundError, SandboxNotRunningError, TimeoutError, translate, } from "./errors.js";
+import { commandAs, listedAs, runAs } from "./users.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
 /** How long a command may run on Runtime: a day, E2B's longest sandbox. E2B's
  * own `timeoutMs` bounds only the connection, so the process gets this. */
@@ -25,7 +26,7 @@ export function timeoutFor(timeoutMs) {
 export function commandRequest(opts, defaultTimeoutMs = 60_000) {
     opts.signal?.throwIfAborted();
     const timeoutMs = timeoutFor(opts.requestTimeoutMs ?? defaultTimeoutMs);
-    const deadline = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const deadline = timeoutMs > 0 ? timeoutSignal(timeoutMs) : undefined;
     const signal = opts.signal && deadline ? AbortSignal.any([opts.signal, deadline]) : (opts.signal ?? deadline);
     return { timeoutMs: 0, ...(signal ? { signal } : {}) };
 }
@@ -85,7 +86,7 @@ function toResult(result) {
 export function connectionRequest(opts, defaultTimeoutMs) {
     const timeoutMs = timeoutFor(opts.timeoutMs);
     const deadline = timeoutMs > 0 ? performance.now() + timeoutMs : undefined;
-    const connectionTimeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const connectionTimeout = timeoutMs > 0 ? timeoutSignal(timeoutMs) : undefined;
     const signal = connectionTimeout && opts.signal
         ? AbortSignal.any([connectionTimeout, opts.signal])
         : (connectionTimeout ?? opts.signal);
@@ -238,12 +239,17 @@ export class Commands {
 function describe(info) {
     return {
         pid: pidOf(info.id),
-        cmd: "/bin/bash",
-        args: ["-c", info.command],
+        ...listedAs(info.command),
         envs: {},
         cwd: info.cwd,
     };
 }
+/** E2B 2.53's confirmed sandbox loss remains catchable as TimeoutError. */
+function sandboxEnded(cause) {
+    const error = new SandboxNotRunningError("The command ended before the stream completed: the sandbox was killed or reached its end of life.");
+    error.cause = cause;
+    return error;
+}
 /** Reader cancellation also releases a callback whose promise never settles. */
 async function deliver(signal, callback) {
     signal.throwIfAborted();
@@ -349,7 +355,11 @@ export class CommandHandle {
             if (!this.#disconnected && !this.#failure) {
                 const translated = translate(error, "sandbox");
                 this.#failure =
-                    translated instanceof Error ? translated : new SandboxError(String(translated));
+                    translated instanceof SandboxNotFoundError
+                        ? sandboxEnded(translated)
+                        : translated instanceof Error
+                            ? translated
+                            : new SandboxError(String(translated));
             }
         }
         finally {

package/dist/e2b/errors.d.ts

@@ -8,6 +8,14 @@ export declare class SandboxError extends Error {
 }
 export declare class TimeoutError extends SandboxError {
 }
+/** The sandbox is confirmed stopped or paused; create or resume one. */
+export declare class SandboxNotRunningError extends TimeoutError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The sandbox cannot be reached, without confirmation that it stopped. */
+export declare class SandboxUnreachableError extends TimeoutError {
+    constructor(message: string, options?: ErrorOptions);
+}
 export declare class InvalidArgumentError extends SandboxError {
 }
 export declare class NotEnoughSpaceError extends SandboxError {
@@ -37,6 +45,40 @@ export declare class ServiceBusyError extends Error {
     requestId?: string;
     constructor(message: string);
 }
+/** E2B's other error classes, by the same names and parents, so a module
+ * that imports or catches them loads and works: nothing in this package
+ * throws them, since the features behind them (template builds, git,
+ * volumes, secrets) answer NotSupportedError here. */
+export declare class GitAuthError extends AuthenticationError {
+}
+export declare class GitUpstreamError extends SandboxError {
+}
+export declare class BuildError extends Error {
+    constructor(message?: string);
+}
+export declare class FileUploadError extends BuildError {
+}
+export declare class VolumeError extends Error {
+    constructor(message?: string);
+}
+export declare class VolumeNotFoundError extends VolumeError {
+}
+export declare class VolumePathNotFoundError extends VolumeError {
+}
+export declare class SecretError extends Error {
+    constructor(message?: string);
+}
+export declare class SecretNotFoundError extends SecretError {
+}
+/** E2B 2.55's Dockerfile parse error, from `@e2b/dockerfile-utils`: a plain
+ * Error, not a SandboxError, with the line it names. Runtime parses no
+ * Dockerfile here (templates are Runtime images, built by
+ * `npx withruntime images build`), so nothing throws it; it exists so that
+ * code importing it or catching it still loads. */
+export declare class DockerfileSyntaxError extends Error {
+    readonly line: number | undefined;
+    constructor(message: string, line?: number);
+}
 /** A call that E2B supports and Runtime does not, or not in the same way.
  * Thrown before anything is done, never after doing something different.
  * `feature` names what was asked for; `alternative` says what to use on
@@ -46,8 +88,7 @@ export declare class NotSupportedError extends SandboxError {
     readonly alternative: string;
     constructor(feature: string, alternative: string, message?: string);
 }
-/** Runtime's addition, for `getHost` and `getPublicHost`: a free-trial
- * sandbox shares a port only privately, so a request needs the port's token,
+/** Runtime's addition, for `getHost` and `getPublicHost`: a sandbox without credit shares a port only privately, so a request needs the port's token,
  * and a host name alone cannot carry one. The message says what works. A
  * NotSupportedError, so code that catches those catches this too. */
 export declare class PublicPreviewNotAllowedError extends NotSupportedError {

package/dist/e2b/errors.js

@@ -23,6 +23,24 @@ export class SandboxError extends Error {
 }
 export class TimeoutError extends SandboxError {
 }
+/** The sandbox is confirmed stopped or paused; create or resume one. */
+export class SandboxNotRunningError extends TimeoutError {
+    constructor(message, options) {
+        super(message);
+        this.name = "SandboxNotRunningError";
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
+/** The sandbox cannot be reached, without confirmation that it stopped. */
+export class SandboxUnreachableError extends TimeoutError {
+    constructor(message, options) {
+        super(message);
+        this.name = "SandboxUnreachableError";
+        if (options?.cause !== undefined)
+            this.cause = options.cause;
+    }
+}
 export class InvalidArgumentError extends SandboxError {
 }
 export class NotEnoughSpaceError extends SandboxError {
@@ -58,6 +76,55 @@ export class ServiceBusyError extends Error {
         this.name = new.target.name;
     }
 }
+/** E2B's other error classes, by the same names and parents, so a module
+ * that imports or catches them loads and works: nothing in this package
+ * throws them, since the features behind them (template builds, git,
+ * volumes, secrets) answer NotSupportedError here. */
+export class GitAuthError extends AuthenticationError {
+}
+export class GitUpstreamError extends SandboxError {
+}
+export class BuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class FileUploadError extends BuildError {
+}
+export class VolumeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class VolumeNotFoundError extends VolumeError {
+}
+export class VolumePathNotFoundError extends VolumeError {
+}
+export class SecretError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class SecretNotFoundError extends SecretError {
+}
+/** E2B 2.55's Dockerfile parse error, from `@e2b/dockerfile-utils`: a plain
+ * Error, not a SandboxError, with the line it names. Runtime parses no
+ * Dockerfile here (templates are Runtime images, built by
+ * `npx withruntime images build`), so nothing throws it; it exists so that
+ * code importing it or catching it still loads. */
+export class DockerfileSyntaxError extends Error {
+    line;
+    constructor(message, line) {
+        super(line === undefined
+            ? `Dockerfile parse error: ${message}`
+            : `Dockerfile parse error on line ${line}: ${message}`);
+        this.line = line;
+        this.name = "DockerfileSyntaxError";
+    }
+}
 /** A call that E2B supports and Runtime does not, or not in the same way.
  * Thrown before anything is done, never after doing something different.
  * `feature` names what was asked for; `alternative` says what to use on
@@ -72,19 +139,18 @@ export class NotSupportedError extends SandboxError {
         this.code = "not_supported";
     }
 }
-/** Runtime's addition, for `getHost` and `getPublicHost`: a free-trial
- * sandbox shares a port only privately, so a request needs the port's token,
+/** Runtime's addition, for `getHost` and `getPublicHost`: a sandbox without credit shares a port only privately, so a request needs the port's token,
  * and a host name alone cannot carry one. The message says what works. A
  * NotSupportedError, so code that catches those catches this too. */
 export class PublicPreviewNotAllowedError extends NotSupportedError {
     constructor(sandboxId, port, message) {
         const where = port === undefined ? "<port>" : String(port);
-        const alternative = `For an address that works on the trial, use (await sandbox.runtime.previews.create(${where})).urlWithToken: ` +
+        const alternative = `For an address that works without credit, use (await sandbox.runtime.previews.create(${where})).urlWithToken: ` +
             "it carries the token, in a browser, fetch or curl. For other paths on it, send the token as the " +
             "x-runtime-preview-token header or the runtime_preview_token query parameter. A public host needs a paid " +
             "sandbox, which is the account owner's decision.";
-        super("A public address on a free-trial sandbox", alternative, message ??
-            `Sandbox ${sandboxId} runs on the free trial, where a shared port is private: every request needs the ` +
+        super("A public address on a sandbox without credit", alternative, message ??
+            `Sandbox ${sandboxId} runs without credit, where a shared port is private: every request needs the ` +
                 `port's token, and a host name alone cannot carry one. ${alternative}`);
         this.code = "public_preview_not_allowed";
     }
@@ -126,7 +192,13 @@ export function translate(error, subject = "other") {
         .filter(Boolean)
         .join("\n");
     let out;
-    if (error.status === 503 && error.code.endsWith("_unavailable"))
+    // Runtime reports the sandbox state explicitly. A generic connection failure
+    // does not prove it stopped; never replay a command or write to classify it.
+    if (["sandbox_stopped", "sandbox_paused", "sandbox_not_running"].includes(error.code))
+        out = new SandboxNotRunningError(message);
+    else if (error.code === "sandbox_not_ready" || error.code === "host_unavailable")
+        out = new SandboxUnreachableError(message);
+    else if (error.status === 503 && error.code.endsWith("_unavailable"))
         // A product switched off on purpose (forks, previews): Runtime's own words
         // say what is off and what to use meanwhile.
         out = new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", message);

package/dist/e2b/filesystem.d.ts

@@ -72,7 +72,7 @@ export interface FilesystemListOpts extends FilesystemRequestOpts {
 }
 /** `sandbox.files`: E2B's filesystem module over Runtime's files API. Relative
  * paths resolve against the home directory, as in E2B (Runtime's is
- * /workspace). */
+ * /workspace), and come back under /home/user, as E2B gives them. */
 export declare class Filesystem {
     #private;
     constructor(ctx: SandboxContext);

package/dist/e2b/filesystem.js

@@ -20,17 +20,51 @@ const HOME = "/workspace";
 function absolute(path) {
     return path.startsWith("/") ? path : `${HOME}/${path.replace(/^\.\//, "")}`;
 }
+/** E2B's home, which E2B code expects in the paths it gets back. */
+const E2B_HOME = "/home/user";
+/** A path as E2B gives it back: one the caller asked for relative to the home
+ * is shown under /home/user, as E2B shows it, when /home/user leads to
+ * /workspace (`linked`), so it names the same file. A path the caller gave in
+ * full comes back as given. */
+function shown(path, asked, linked) {
+    if (asked.startsWith("/") || !linked)
+        return path;
+    if (path === HOME)
+        return E2B_HOME;
+    return path.startsWith(`${HOME}/`) ? E2B_HOME + path.slice(HOME.length) : path;
+}
 function refuse(opts) {
     if (opts.metadata && Object.keys(opts.metadata).length)
         throw new NotSupportedError("File metadata (user.e2b.* extended attributes)", "Keep the metadata beside the file, for example in a JSON file.");
 }
 const PERMISSIONS = ["---", "--x", "-w-", "-wx", "r--", "r-x", "rw-", "rwx"];
-function entryInfo(entry) {
+/** The first letter of envd's permissions, Go's FileMode string. */
+const KIND_LETTER = { directory: "d", symlink: "L" };
+/** The sandbox user as E2B names it: Runtime's is `runtime`, E2B's `user`. */
+function e2bUser(name) {
+    return name === "runtime" ? "user" : (name ?? "");
+}
+/** A link's target as envd gives it: absolute, a relative one taken from the
+ * link's own directory. */
+function linkTarget(path, target) {
+    if (target.startsWith("/"))
+        return target;
+    const parts = path.split("/").slice(0, -1);
+    for (const part of target.split("/")) {
+        if (part === "..")
+            parts.pop();
+        else if (part && part !== ".")
+            parts.push(part);
+    }
+    return `/${parts.filter(Boolean).join("/")}`;
+}
+function entryInfo(entry, asked, linked) {
     const mode = parseInt(entry.mode, 8) || 0;
     const bits = mode & 0o777;
+    const path = shown(entry.path, asked, linked);
     return {
         name: entry.name,
-        path: entry.path,
+        path,
         ...(entry.type === "file"
             ? { type: FileType.FILE }
             : entry.type === "directory"
@@ -40,10 +74,15 @@ function entryInfo(entry) {
                     : {}),
         size: entry.size,
         mode,
-        permissions: PERMISSIONS[(bits >> 6) & 7] + PERMISSIONS[(bits >> 3) & 7] + PERMISSIONS[bits & 7],
-        owner: entry.owner ?? "",
-        group: entry.group ?? "",
-        ...(entry.symlinkTarget ? { symlinkTarget: entry.symlinkTarget } : {}),
+        permissions: (KIND_LETTER[entry.type] ?? "-") +
+            PERMISSIONS[(bits >> 6) & 7] +
+            PERMISSIONS[(bits >> 3) & 7] +
+            PERMISSIONS[bits & 7],
+        owner: e2bUser(entry.owner),
+        group: e2bUser(entry.group),
+        ...(entry.symlinkTarget
+            ? { symlinkTarget: shown(linkTarget(entry.path, entry.symlinkTarget), asked, linked) }
+            : {}),
         modifiedTime: new Date(entry.modifiedAt),
     };
 }
@@ -63,7 +102,7 @@ async function bytesOf(data) {
 const basename = (path) => path.split("/").filter(Boolean).pop() ?? path;
 /** `sandbox.files`: E2B's filesystem module over Runtime's files API. Relative
  * paths resolve against the home directory, as in E2B (Runtime's is
- * /workspace). */
+ * /workspace), and come back under /home/user, as E2B gives them. */
 export class Filesystem {
     #ctx;
     constructor(ctx) {
@@ -79,6 +118,11 @@ export class Filesystem {
         opts.signal?.throwIfAborted();
         return absolute(path);
     }
+    /** Whether a path asked relative to the home may be shown under /home/user.
+     * Asked at the start of a call, it is learned beside the call itself. */
+    #linked(path) {
+        return path.startsWith("/") ? Promise.resolve(false) : this.#ctx.homeIsWorkspace();
+    }
     /** The calls as another Linux user, or undefined for the sandbox's own. */
     async #as(opts) {
         if (opts.user === undefined || opts.user === "user")
@@ -121,22 +165,27 @@ export class Filesystem {
     }
     async #writeOne(path, data, opts) {
         const file = await this.#path(path, opts);
+        const linked = this.#linked(path);
         const as = await this.#as(opts);
         const bytes = await bytesOf(data);
         if (as)
             await as.write(file, bytes);
         else
             await guard("file", () => this.#files.write(file, bytes, request(opts)));
-        return { name: basename(file), type: FileType.FILE, path: file };
+        return { name: basename(file), type: FileType.FILE, path: shown(file, path, await linked) };
     }
     /** A directory's entries, hidden ones included; `depth` goes deeper. */
     async list(path, opts = {}) {
+        if (opts.depth !== undefined && opts.depth < 1)
+            throw new InvalidArgumentError("depth should be at least one");
         const dir = await this.#path(path, opts);
+        const linked = this.#linked(path);
         const as = await this.#as(opts);
-        if (as)
-            return (await as.list(dir, opts.depth ?? 1)).map(entryInfo);
-        const entries = await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true, ...request(opts) }));
-        return entries.map(entryInfo);
+        const entries = as
+            ? await as.list(dir, opts.depth ?? 1)
+            : await guard("file", () => this.#files.list(dir, { depth: opts.depth ?? 1, hidden: true, ...request(opts) }));
+        const home = await linked;
+        return entries.map((entry) => entryInfo(entry, path, home));
     }
     /** Makes a directory and its parents. False when it already existed. */
     async makeDir(path, opts = {}) {
@@ -158,7 +207,7 @@ export class Filesystem {
             await as.rename(from, to);
         else
             await guard("file", () => this.#files.rename(from, to, { overwrite: true, ...request(opts) }));
-        return this.getInfo(to, opts);
+        return this.getInfo(newPath, opts);
     }
     /** Removes a file, or a directory with everything in it. */
     async remove(path, opts = {}) {
@@ -177,13 +226,14 @@ export class Filesystem {
     }
     async getInfo(path, opts = {}) {
         const target = await this.#path(path, opts);
+        const linked = this.#linked(path);
         const as = await this.#as(opts);
         if (as)
-            return entryInfo(await as.stat(target));
+            return entryInfo(await as.stat(target), path, await linked);
         const stat = await guard("file", () => this.#files.stat(target, request(opts)));
         if (!stat.exists)
             throw new FileNotFoundError(`${target} does not exist.`);
-        return entryInfo(stat);
+        return entryInfo(stat, path, await linked);
     }
     /** E2B's watchDir on Runtime's file watch. A local deadline preserves
      * subsecond subscriptions; 0 runs until stopped or the sandbox ends. */
@@ -197,6 +247,10 @@ export class Filesystem {
         if (!Number.isFinite(lifetime) || lifetime < 0)
             throw new InvalidArgumentError("timeoutMs must be a nonnegative finite number.");
         const target = await this.#path(path, opts);
+        // envd watches only a directory; Runtime's watch also takes a file.
+        const stat = await guard("file", () => this.#files.stat(target, request(opts)));
+        if (stat.exists && stat.type !== "directory")
+            throw new InvalidArgumentError(`${target} is not a directory; watchDir watches a directory.`);
         const prefix = target.endsWith("/") ? target : `${target}/`;
         let exited = false;
         let native;
@@ -277,12 +331,24 @@ export class Filesystem {
                             throw error;
                     }
                 }
+                const name = event.path.startsWith(prefix)
+                    ? event.path.slice(prefix.length)
+                    : event.path;
                 if (!exited)
                     await onEvent({
-                        name: event.path.startsWith(prefix) ? event.path.slice(prefix.length) : event.path,
+                        name,
                         type: event.type,
                         ...(entry ? { entry } : {}),
                     });
+                // Runtime writes a file whole, by a rename into place, which the
+                // watch sees as a create; envd writes in place, which is a write.
+                // Code written for E2B waits for the write (5 October 2026).
+                if (!exited && event.type === "create" && !event.isDir)
+                    await onEvent({
+                        name,
+                        type: FilesystemEventType.WRITE,
+                        ...(entry ? { entry } : {}),
+                    });
             }, {
                 recursive: opts.recursive === true,
                 timeoutMs: 0,

package/dist/e2b/index.d.ts

@@ -7,13 +7,13 @@
 import type { Runtime } from "../client.js";
 import { type ConnectionOpts } from "./client.js";
 import { Sandbox } from "./sandbox.js";
-export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SnapshotInfo, } from "./sandbox.js";
+export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, type SandboxOpts, type SandboxConnectOpts, type SandboxApiOpts, type SandboxInfo, type SandboxListOpts, type SandboxState, type SandboxLifecycle, type SandboxOnTimeout, type SandboxPauseOpts, type CreateSnapshotOpts, type SnapshotMode, type SnapshotInfo, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, type CommandStartOpts, type CommandConnectOpts, type CommandRequestOpts, type ProcessInfo, type Username, } from "./commands.js";
 export { Filesystem, FileType, type EntryInfo, type WriteInfo, type WriteEntry, type FilesystemRequestOpts, type FilesystemReadOpts, type FilesystemWriteOpts, type FilesystemListOpts, FilesystemEventType, type FilesystemEvent, type WatchOpts, type E2BWatchHandle as WatchHandle, } from "./filesystem.js";
-export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, type CommandResult, } from "./errors.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, SandboxNotRunningError, SandboxUnreachableError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, GitAuthError, GitUpstreamError, BuildError, FileUploadError, VolumeError, VolumeNotFoundError, VolumePathNotFoundError, SecretError, SecretNotFoundError, DockerfileSyntaxError, type CommandResult, } from "./errors.js";
 export type { ConnectionOpts, HttpVersion, RuntimeOpts } from "./client.js";
 export { Pty, type PtyCreateOpts, type PtyConnectOpts } from "./pty.js";
-export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
+export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, SecretPaginator, Git, ReadyCmd, LogEntry, LogEntryStart, LogEntryEnd, defaultBuildLogger, ConnectionConfig, ApiClient, getSignature, ALL_TRAFFIC, VolumeFileType, } from "./unsupported.js";
 export default Sandbox;
 /** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
 export declare class E2B {

package/dist/e2b/index.js

@@ -3,9 +3,9 @@ import { Sandbox } from "./sandbox.js";
 export { Sandbox, SandboxPaginator, DEFAULT_SHAPE, DEFAULT_TIMEOUT_MS, } from "./sandbox.js";
 export { Commands, CommandHandle, pidOf, } from "./commands.js";
 export { Filesystem, FileType, FilesystemEventType, } from "./filesystem.js";
-export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, } from "./errors.js";
+export { SandboxError, TimeoutError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, FileNotFoundError, SandboxNotFoundError, SandboxNotRunningError, SandboxUnreachableError, TemplateError, RateLimitError, AuthenticationError, ServiceBusyError, CommandExitError, NotSupportedError, PublicPreviewNotAllowedError, GitAuthError, GitUpstreamError, BuildError, FileUploadError, VolumeError, VolumeNotFoundError, VolumePathNotFoundError, SecretError, SecretNotFoundError, DockerfileSyntaxError, } from "./errors.js";
 export { Pty } from "./pty.js";
-export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, } from "./unsupported.js";
+export { Template, TemplateBase, Volume, Secret, waitForPort, waitForURL, waitForProcess, waitForFile, waitForTimeout, SecretPaginator, Git, ReadyCmd, LogEntry, LogEntryStart, LogEntryEnd, defaultBuildLogger, ConnectionConfig, ApiClient, getSignature, ALL_TRAFFIC, VolumeFileType, } from "./unsupported.js";
 export default Sandbox;
 /** E2B's client with bound options: `new E2B({ apiKey }).Sandbox.create()`. */
 export class E2B {