withruntime 0.11.0 → 0.11.2

package/dist/compat/lease.js

@@ -1,9 +1,11 @@
 import { RuntimeError } from "../errors.js";
-/* A rival's sandbox may be asked to live longer than one Runtime lease (an
-   hour at most, ARCHITECTURE.md section 10): Vercel's `timeout` over an hour,
-   Daytona's `autoStopInterval` over an hour or 0. The drop-ins keep the lease
-   reaching toward the time asked for while their sandbox object lives, one
-   extension at a time, never past that time. */
+/* A rival's sandbox may be asked to live longer than one Runtime time limit
+   (an hour at most, ARCHITECTURE.md section 10): Vercel's `timeout` over an
+   hour, Daytona's `autoStopInterval` over an hour. The drop-ins keep the
+   limit reaching toward the time asked for while their sandbox object lives,
+   one extension at a time, never past that time. A sandbox created with no
+   time limit renews itself on the server (0300; `endsAt` null) and is left
+   alone. */
 /** The most one lease runs ahead of now. */
 export const LEASE_MAX_SECONDS = 3600;
 /** Whole seconds to add to a lease ending at `expiresAt` (epoch ms) so it
@@ -39,7 +41,10 @@ export class LeaseKeeper {
     #schedule() {
         if (this.#ended || this.#timer)
             return;
-        const expiresAt = Date.parse(this.#sandbox().info.expiresAt);
+        const info = this.#sandbox().info;
+        if (info.endsAt === null)
+            return;
+        const expiresAt = Date.parse(info.endsAt ?? info.expiresAt);
         if (!Number.isFinite(expiresAt) || this.#until() <= expiresAt)
             return;
         this.#timer = setTimeout(() => {
@@ -61,9 +66,10 @@ export class LeaseKeeper {
     }
     async #extend(now) {
         const sandbox = this.#sandbox();
-        if (sandbox.state !== "running")
+        // No time limit: the server renews it, and an extension would change nothing.
+        if (sandbox.state !== "running" || sandbox.info.endsAt === null)
             return;
-        const seconds = extensionSeconds(Date.parse(sandbox.info.expiresAt), this.#until(), Date.now(), now ? Infinity : this.#marginMs());
+        const seconds = extensionSeconds(Date.parse(sandbox.info.endsAt ?? sandbox.info.expiresAt), this.#until(), Date.now(), now ? Infinity : this.#marginMs());
         if (seconds < 1)
             return;
         try {

package/dist/credentials.d.ts

@@ -10,6 +10,15 @@ export type SavedConnection = {
     /** The account's name when it was saved, for `runtime account`. */
     orgName?: string;
 };
+/** Saved accounts could not be updated because another command holds their
+ * lock: still `busy` after the whole wait, or `interrupted`, left by a command
+ * that died holding it. The message names the lock file to remove. */
+export declare class CredentialsLockedError extends Error {
+    readonly lockFile: string;
+    readonly reason: "busy" | "interrupted";
+    readonly name = "CredentialsLockedError";
+    constructor(message: string, lockFile: string, reason: "busy" | "interrupted");
+}
 export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
     api: string;
     auth: string;

package/dist/credentials.js

@@ -4,6 +4,23 @@ import { lstat, mkdir, open, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { apiOrigin, missingKey } from "./transport.js";
+/** Saved accounts could not be updated because another command holds their
+ * lock: still `busy` after the whole wait, or `interrupted`, left by a command
+ * that died holding it. The message names the lock file to remove. */
+export class CredentialsLockedError extends Error {
+    lockFile;
+    reason;
+    name = "CredentialsLockedError";
+    constructor(message, lockFile, reason) {
+        super(message);
+        this.lockFile = lockFile;
+        this.reason = reason;
+    }
+}
+/** How long a save waits for another command's update to finish. An update
+ * is one read, modify and write of small files, so only a heavily loaded
+ * machine comes near it. */
+const LOCK_WAIT_MS = 30_000;
 /** How many other accounts' connections one machine keeps beside the one in use. */
 const SAVED_ACCOUNTS = 20;
 export function connectionOrigins(env) {
@@ -107,7 +124,7 @@ export function connectionStore(env, directory = defaultDirectory(env)) {
      * Never steal a lock: stale cleanup can otherwise delete a new live lock. */
     async function updateAccounts(update) {
         await privateDirectory(true);
-        const until = performance.now() + 10_000;
+        const until = performance.now() + LOCK_WAIT_MS;
         let handle;
         for (;;) {
             try {
@@ -127,16 +144,21 @@ export function connectionStore(env, directory = defaultDirectory(env)) {
                 // The holder may not have finished writing its process id yet.
             }
             if (typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0) {
+                let gone = false;
                 try {
                     process.kill(pid, 0);
                 }
                 catch (error) {
-                    if (error.code === "ESRCH")
-                        throw new Error(`A previous Runtime credential update was interrupted. Remove ${lockFile} and retry.`);
+                    gone = error.code === "ESRCH";
                 }
+                // A holder that finished between our read and our check has exited
+                // too, and its lock is gone or another's: wait for the lock again.
+                // Only a lock still naming the dead process was left by one that died.
+                if (gone && (await readPrivate(lockFile, 1024, "credential update lock")) === text)
+                    throw new CredentialsLockedError(`A previous Runtime credential update was interrupted. Remove ${lockFile} and retry.`, lockFile, "interrupted");
             }
             if (performance.now() >= until)
-                throw new Error(`Another Runtime command is updating saved accounts. Retry when it finishes. If no command is running, remove ${lockFile} and retry.`);
+                throw new CredentialsLockedError(`Another Runtime command is updating saved accounts. Retry when it finishes. If no command is running, remove ${lockFile} and retry.`, lockFile, "busy");
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
         try {

package/dist/daytona/daytona.d.ts

@@ -177,8 +177,7 @@ export declare class Daytona implements AsyncDisposable {
     [Symbol.asyncDispose](): Promise<void>;
     /** Creates a sandbox and waits until it runs, with Daytona's defaults: 1
      * vCPU, 1 GiB, 3 GiB disk, pausing after 15 minutes without calls. Funding
-     * is left to Runtime: the free trial while the account has trial time, then
-     * prepaid credit, exactly as withruntime's own create. */
+     * is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     create(params?: CreateSandboxFromSnapshotParams | CreateSandboxFromImageParams, options?: {
         timeout?: number;
         onSnapshotCreateLogs?: (chunk: string) => void;

package/dist/daytona/daytona.js

@@ -1,6 +1,7 @@
 import { clientFor, } from "./client.js";
 import { DaytonaError, DaytonaNotFoundError, guard, NotSupportedError } from "./errors.js";
-import { idleSeconds, networkRules, notFound, retentionDays, Sandbox, windowSeconds, } from "./sandbox.js";
+import { LEASE_MAX_SECONDS } from "../compat/lease.js";
+import { idlePauseOf, idleSeconds, networkRules, notFound, retentionDays, Sandbox, windowSeconds, } from "./sandbox.js";
 /* Daytona's client over Runtime's. `new Daytona()` then `daytona.create()`
    makes a Runtime sandbox with Daytona's defaults. */
 /** Daytona's default machine: 1 vCPU, 1 GiB memory, 3 GiB disk (checked
@@ -182,8 +183,7 @@ export class Daytona {
     async [Symbol.asyncDispose]() { }
     /** Creates a sandbox and waits until it runs, with Daytona's defaults: 1
      * vCPU, 1 GiB, 3 GiB disk, pausing after 15 minutes without calls. Funding
-     * is left to Runtime: the free trial while the account has trial time, then
-     * prepaid credit, exactly as withruntime's own create. */
+     * is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
     async create(params = {}, options = {}) {
         refuseCreate(params);
         const client = params.withruntime?.client ?? this.#client;
@@ -211,9 +211,15 @@ export class Daytona {
                     memoryMiB: Math.round(resources.memory * 1024),
                     diskMiB: Math.round(resources.disk * 1024),
                 }),
-            timeoutSeconds: lifecycle.deadline
-                ? Math.max(60, Math.min(lifecycle.windowSeconds, Math.floor((lifecycle.deadline - Date.now()) / 1000)))
-                : lifecycle.windowSeconds,
+            // A time to live is a time limit, kept by the lease. Without one there
+            // is none: it runs while it works and autoStopInterval is its idle
+            // pause, counted by the sandbox itself, so a long command is never
+            // frozen for want of calls from this client (0300).
+            ...(lifecycle.deadline
+                ? {
+                    timeoutSeconds: Math.max(60, Math.min(lifecycle.windowSeconds, Math.floor((lifecycle.deadline - Date.now()) / 1000))),
+                }
+                : { idlePauseSeconds: idlePauseOf(lifecycle.autoStopInterval) }),
             onLeaseEnd: lifecycle.ephemeral || lifecycle.deadline ? "stop" : "pause",
             ...(params.name ? { name: params.name } : {}),
             ...(labels ? { labels } : {}),
@@ -303,14 +309,24 @@ export class Daytona {
             language: runtime.info.labels[LANGUAGE_LABEL] ?? "python",
             public: false,
             ...(user ? { user } : {}),
-            lifecycle: {
-                windowSeconds: runtime.info.timeoutSeconds,
-                idleSeconds: runtime.info.timeoutSeconds,
-                ephemeral: onLeaseEnd === "stop",
-                autoStopInterval: Math.round(runtime.info.timeoutSeconds / 60),
-                autoArchiveInterval: 0,
-                autoDeleteInterval: -1,
-            },
+            lifecycle: runtime.info.timeoutSeconds
+                ? {
+                    windowSeconds: runtime.info.timeoutSeconds,
+                    idleSeconds: runtime.info.timeoutSeconds,
+                    ephemeral: onLeaseEnd === "stop",
+                    autoStopInterval: Math.round(runtime.info.timeoutSeconds / 60),
+                    autoArchiveInterval: 0,
+                    autoDeleteInterval: -1,
+                }
+                : {
+                    // No time limit: its idle pause is its autoStopInterval.
+                    windowSeconds: LEASE_MAX_SECONDS,
+                    idleSeconds: Infinity,
+                    ephemeral: onLeaseEnd === "stop",
+                    autoStopInterval: Math.round((runtime.info.idlePauseSeconds ?? 0) / 60),
+                    autoArchiveInterval: 0,
+                    autoDeleteInterval: -1,
+                },
         });
     }
     /** Live and stopped (paused) sandboxes, oldest first. Await it for the old

package/dist/daytona/sandbox.d.ts

@@ -125,7 +125,7 @@ export declare class Sandbox {
     /** Pauses the sandbox with its memory. */
     pause(_timeout?: number): Promise<void>;
     /** Runtime has no archive tier: a stopped sandbox stays paused, kept for
-     * its retention (30 days paid, 7 on the trial, or autoDeleteInterval). */
+     * its retention (30 days paid, 7 without credit, or autoDeleteInterval). */
     archive(): Promise<void>;
     /** Ends the sandbox for good. */
     delete(_timeout?: number): Promise<void>;
@@ -134,8 +134,9 @@ export declare class Sandbox {
     refreshData(): Promise<void>;
     /** Counts as activity: moves the lease a full autoStop window on. */
     refreshActivity(): Promise<void>;
-    /** The sandbox pauses after `interval` minutes without a call from this
-     * client; 0 never. Past an hour, while this object lives. */
+    /** The sandbox pauses after `interval` minutes with nothing happening in
+     * it; 0 never. With a time to live, after that long without a call from
+     * this client, and past an hour only while this object lives. */
     setAutostopInterval(interval: number): Promise<void>;
     setAutoPauseInterval(interval: number): Promise<void>;
     /** Runtime has no archive tier; recorded only. */
@@ -192,8 +193,12 @@ export declare class Sandbox {
 }
 /** Daytona's autoStopInterval (minutes; 0 is off) as the lease window. */
 export declare function windowSeconds(autoStopMinutes: number): number;
+/** Daytona's autoStopInterval (minutes; 0 is never) as the idle pause of a
+ * sandbox with no time limit: seconds with nothing happening in it, counted
+ * by the sandbox itself (`idlePauseSeconds`, 0 never, at most a day). */
+export declare function idlePauseOf(autoStopMinutes: number): number;
 /** Daytona's autoStopInterval (minutes; 0 is never) as seconds without a
- * call before the sandbox pauses. */
+ * call before a sandbox with a time to live pauses. */
 export declare function idleSeconds(autoStopMinutes: number): number;
 /** Minutes as Runtime's retention: whole days, 1 to 365. */
 export declare function retentionDays(minutes: number): number;

package/dist/daytona/sandbox.js

@@ -238,7 +238,11 @@ export class Sandbox {
         if (state === "stopped" || state === "stopping")
             throw new DaytonaError(`Sandbox ${this.id} was deleted and cannot start.`, 410);
         if (state === "paused" || state === "pausing")
-            await guard("sandbox", () => this.#rt.wake({ timeoutSeconds: this.#options.lifecycle.windowSeconds }));
+            await guard("sandbox", () => 
+            // One with no time limit (timeoutSeconds 0) wakes with none.
+            this.#rt.wake(this.#rt.info.timeoutSeconds
+                ? { timeoutSeconds: this.#options.lifecycle.windowSeconds }
+                : {}));
         this.#pausedByPause = false;
     }
     /** Stops the sandbox: Runtime pauses it, keeping its files and memory, so
@@ -265,7 +269,7 @@ export class Sandbox {
         this.#pausedByPause = true;
     }
     /** Runtime has no archive tier: a stopped sandbox stays paused, kept for
-     * its retention (30 days paid, 7 on the trial, or autoDeleteInterval). */
+     * its retention (30 days paid, 7 without credit, or autoDeleteInterval). */
     async archive() {
         await this.stop();
     }
@@ -291,11 +295,16 @@ export class Sandbox {
     async refreshActivity() {
         await guard("sandbox", () => this.#live(true));
     }
-    /** The sandbox pauses after `interval` minutes without a call from this
-     * client; 0 never. Past an hour, while this object lives. */
+    /** The sandbox pauses after `interval` minutes with nothing happening in
+     * it; 0 never. With a time to live, after that long without a call from
+     * this client, and past an hour only while this object lives. */
     async setAutostopInterval(interval) {
         const lifecycle = this.#options.lifecycle;
         lifecycle.autoStopInterval = interval;
+        if (!this.#rt.info.timeoutSeconds) {
+            await guard("sandbox", () => this.#rt.update({ idlePauseSeconds: idlePauseOf(interval) }));
+            return;
+        }
         lifecycle.windowSeconds = windowSeconds(interval);
         lifecycle.idleSeconds = idleSeconds(interval);
         await guard("sandbox", () => this.#live());
@@ -321,6 +330,8 @@ export class Sandbox {
             delete this.#options.lifecycle.deadline;
             return;
         }
+        if (!this.#rt.info.timeoutSeconds)
+            throw new NotSupportedError("A time to live on a sandbox made without one", "It has no time limit and pauses when idle; pass ttlMinutes to create(), or call stop() or delete() when the work is done.");
         const deadline = Date.parse(this.#rt.info.createdAt) + ttlMinutes * 60_000;
         if (Date.parse(this.#rt.info.expiresAt) > deadline)
             throw new NotSupportedError("A time to live shorter than the current lease", "Runtime leases only move later; call stop() or delete() when the work is done.");
@@ -444,8 +455,16 @@ export function windowSeconds(autoStopMinutes) {
         return 3600;
     return Math.min(3600, Math.max(60, Math.round(autoStopMinutes * 60)));
 }
+/** Daytona's autoStopInterval (minutes; 0 is never) as the idle pause of a
+ * sandbox with no time limit: seconds with nothing happening in it, counted
+ * by the sandbox itself (`idlePauseSeconds`, 0 never, at most a day). */
+export function idlePauseOf(autoStopMinutes) {
+    if (autoStopMinutes <= 0)
+        return 0;
+    return Math.min(86_400, Math.max(60, Math.round(autoStopMinutes * 60)));
+}
 /** Daytona's autoStopInterval (minutes; 0 is never) as seconds without a
- * call before the sandbox pauses. */
+ * call before a sandbox with a time to live pauses. */
 export function idleSeconds(autoStopMinutes) {
     if (autoStopMinutes <= 0)
         return Infinity;

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

@@ -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,5 @@
-import { CommandExitError, guard, InvalidArgumentError, SandboxError, TimeoutError, translate, } from "./errors.js";
-import { commandAs, runAs } from "./users.js";
+import { CommandExitError, guard, InvalidArgumentError, SandboxError, SandboxNotFoundError, 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. */
@@ -238,12 +238,19 @@ 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,
     };
 }
+/** A command whose sandbox went away under it, as E2B says it: a
+ * TimeoutError, which code written for E2B catches (5 October 2026: it was a
+ * SandboxNotFoundError). */
+function sandboxEnded(cause) {
+    const error = new TimeoutError("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 +356,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

@@ -37,6 +37,31 @@ 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 {
+}
 /** 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 +71,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

@@ -58,6 +58,40 @@ 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 {
+}
 /** 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 +106,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";
     }

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);