withruntime 0.10.0 → 0.11.1

package/dist/daytona/process.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { HOME, LONGEST_MS, quote, resolvePath, WHOLE_OUTPUT, } from "./context.js";
-import { DaytonaCommandAlreadyCompletedError, DaytonaConflictError, DaytonaConnectionError, DaytonaNotFoundError, DaytonaProcessExecutionTimeoutError, DaytonaSessionEndedError, guard, NotSupportedError, } from "./errors.js";
+import { HOME, LONGEST_MS, quote, resolvePath, runAs, WHOLE_OUTPUT, } from "./context.js";
+import { DaytonaCommandAlreadyCompletedError, DaytonaConflictError, DaytonaConnectionError, DaytonaError, DaytonaNotFoundError, DaytonaProcessExecutionTimeoutError, DaytonaSessionEndedError, guard, NotSupportedError, } from "./errors.js";
 export class CodeRunParams {
     argv;
     env;
@@ -57,6 +57,8 @@ class ShellSession {
 export class Process {
     #ctx;
     #sessions = new Map();
+    /** What only this client knows of its PTY sessions: envs and size. */
+    #ptys = new Map();
     constructor(ctx) {
         this.#ctx = ctx;
     }
@@ -64,6 +66,15 @@ export class Process {
         const merged = { ...this.#ctx.env, ...extra };
         return Object.keys(merged).length ? { env: merged } : {};
     }
+    /** A command and its environment option as Runtime runs them: as given
+     * for the sandbox owner, through sudo for create's `user`. */
+    #as(command, extra) {
+        const user = this.#ctx.user;
+        if (!user)
+            return [command, this.#env(extra)];
+        const argv = typeof command === "string" ? ["bash", "-c", command] : command;
+        return [runAs(user, argv, { ...this.#ctx.env, ...extra }).argv, {}];
+    }
     /** Runs a shell command and resolves with its exit code and output. A
      * non-zero exit is a result, not an error. `timeout` is in seconds; past
      * it the command is killed and DaytonaProcessExecutionTimeoutError is
@@ -72,9 +83,10 @@ export class Process {
         await this.#ctx.ensureHome(`${command}\n${cwd ?? ""}`);
         const runtime = await this.#ctx.live();
         const timeoutMs = timeout ? timeout * 1000 : LONGEST_MS;
-        const result = await guard("sandbox", () => runtime.exec(`{ ${command}\n} 2>&1`, {
+        const [run, environment] = this.#as(`{ ${command}\n} 2>&1`, env);
+        const result = await guard("sandbox", () => runtime.exec(run, {
             cwd: cwd === undefined ? HOME : resolvePath(cwd),
-            ...this.#env(env),
+            ...environment,
             timeoutMs,
             ...WHOLE_OUTPUT,
         }));
@@ -96,9 +108,10 @@ export class Process {
                 ? ["bun", "-e", code]
                 : ["node", "-e", code];
         const timeoutMs = timeout ? timeout * 1000 : LONGEST_MS;
-        const result = await guard("sandbox", () => runtime.exec(["sh", "-c", 'exec "$@" 2>&1', "sh", ...interpreter, ...(params.argv ?? [])], {
+        const [run, environment] = this.#as(["sh", "-c", 'exec "$@" 2>&1', "sh", ...interpreter, ...(params.argv ?? [])], params.env);
+        const result = await guard("sandbox", () => runtime.exec(run, {
             cwd: HOME,
-            ...this.#env(params.env),
+            ...environment,
             timeoutMs,
             ...WHOLE_OUTPUT,
         }));
@@ -120,9 +133,16 @@ export class Process {
         if (this.#sessions.has(sessionId) || (await this.#discover(sessionId)))
             throw new DaytonaConflictError(`Session ${sessionId} already exists.`, 409);
         const runtime = await this.#ctx.live();
-        const process = await guard("sandbox", () => runtime.spawn(["bash", "--noprofile", "--norc", "-s", `${TAG}${sessionId}`], {
+        const [run, environment] = this.#as([
+            "bash",
+            "--noprofile",
+            "--norc",
+            "-s",
+            `${TAG}${sessionId}`,
+        ]);
+        const process = await guard("sandbox", () => runtime.spawn(run, {
             cwd: HOME,
-            ...this.#env(),
+            ...environment,
             stdin: "pipe",
             timeoutMs: LONGEST_MS,
         }));
@@ -329,25 +349,209 @@ export class Process {
         return entrypoint();
     }
     // ---- terminals ---------------------------------------------------------
-    createPty() {
-        return pty();
+    /** Starts an interactive shell on a terminal (a PTY) that outlives this
+     * connection: disconnect() leaves it running, connectPty(id) attaches
+     * again, killPtySession(id) ends it. On Runtime it is a process started
+     * with a terminal, found again by its id among the sandbox's processes. */
+    async createPty(options) {
+        const id = options?.id;
+        if (!id)
+            throw new DaytonaError("A PTY session needs an id.", 400);
+        if (await this.#findPty(id))
+            throw new DaytonaConflictError(`PTY session ${id} already exists.`, 409);
+        const cols = options.cols ?? 80;
+        const rows = options.rows ?? 24;
+        await this.#ctx.ensureHome(options.cwd);
+        const cwd = options.cwd === undefined ? HOME : resolvePath(options.cwd);
+        const envs = { ...options.envs };
+        const runtime = await this.#ctx.live();
+        const [run, environment] = this.#as(["bash", "-l", "-i", "-s", ptyTag(id), `${cols}x${rows}`], {
+            TERM: "xterm-256color",
+            ...envs,
+        });
+        const process = await guard("sandbox", () => runtime.spawn(run, { cwd, ...environment, pty: { cols, rows }, timeoutMs: LONGEST_MS }));
+        this.#ptys.set(id, { envs, cols, rows });
+        try {
+            return await this.#attach(id, process.id, options.onData);
+        }
+        catch (error) {
+            await process.kill("SIGKILL").catch(() => undefined);
+            throw error;
+        }
+    }
+    /** Attaches to a running PTY session. Output it printed before arrives
+     * first, then what it prints from now on. */
+    async connectPty(sessionId, options) {
+        const found = await this.#findPty(sessionId);
+        if (!found)
+            throw new DaytonaNotFoundError(`PTY session ${sessionId} was not found.`, 404);
+        return this.#attach(sessionId, found.id, options?.onData);
+    }
+    async listPtySessions() {
+        const latest = new Map();
+        for (const info of await this.#ptyProcesses())
+            latest.set(ptyOf(info.command).id, info);
+        return [...latest.values()].map((info) => this.#ptyInfo(info));
+    }
+    async getPtySessionInfo(sessionId) {
+        const found = (await this.#ptyProcesses())
+            .filter((info) => ptyOf(info.command).id === sessionId)
+            .at(-1);
+        if (!found)
+            throw new DaytonaNotFoundError(`PTY session ${sessionId} was not found.`, 404);
+        return this.#ptyInfo(found);
+    }
+    /** Ends the session's shell and everything it runs. */
+    async killPtySession(sessionId) {
+        const process = await this.#ptyProcess(sessionId);
+        await guard("process", () => process.kill("SIGKILL"));
+    }
+    async resizePtySession(sessionId, cols, rows) {
+        const process = await this.#ptyProcess(sessionId);
+        await guard("process", () => process.resize(cols, rows));
+        const known = this.#ptys.get(sessionId);
+        this.#ptys.set(sessionId, { envs: known?.envs ?? {}, cols, rows });
+        return this.#ptyInfo({ ...process.info, state: "running" });
+    }
+    /** Terminal processes this adapter started, a killed one gone as on
+     * Daytona; an exited one stays, inactive. */
+    async #ptyProcesses() {
+        const runtime = await this.#ctx.live();
+        const list = await guard("sandbox", () => runtime.processes.list());
+        return list.filter((info) => info.state !== "killed" && ptyOf(info.command));
+    }
+    async #findPty(sessionId) {
+        return (await this.#ptyProcesses()).find((info) => info.state === "running" && ptyOf(info.command).id === sessionId);
+    }
+    async #ptyProcess(sessionId) {
+        const found = await this.#findPty(sessionId);
+        if (!found)
+            throw new DaytonaNotFoundError(`PTY session ${sessionId} was not found.`, 404);
+        const runtime = await this.#ctx.live();
+        return guard("process", () => runtime.processes.get(found.id));
+    }
+    #ptyInfo(info) {
+        const tag = ptyOf(info.command);
+        const known = this.#ptys.get(tag.id);
+        return {
+            active: info.state === "running",
+            cols: known?.cols ?? tag.cols,
+            createdAt: info.startedAt,
+            cwd: info.cwd,
+            envs: { ...known?.envs },
+            id: tag.id,
+            lazyStart: false,
+            rows: known?.rows ?? tag.rows,
+        };
+    }
+    async #attach(sessionId, processId, onData) {
+        const runtime = await this.#ctx.live();
+        const terminal = await guard("sandbox", () => runtime.terminal({
+            processId,
+            ...(onData
+                ? {
+                    onData: (data) => void Promise.resolve()
+                        .then(() => onData(data))
+                        .catch(() => undefined),
+                }
+                : {}),
+        }));
+        return new PtyHandle(terminal, sessionId, (cols, rows) => this.resizePtySession(sessionId, cols, rows), () => this.killPtySession(sessionId));
+    }
+}
+/** One connection to a PTY session, Daytona's PtyHandle over Runtime's
+ * terminal WebSocket. */
+export class PtyHandle {
+    sessionId;
+    #terminal;
+    #resize;
+    #kill;
+    #result;
+    #connected = true;
+    #disconnected = false;
+    #exitCode;
+    #error;
+    /** Use process.createPty or process.connectPty. */
+    constructor(terminal, sessionId, resize, kill) {
+        this.sessionId = sessionId;
+        this.#terminal = terminal;
+        this.#resize = resize;
+        this.#kill = kill;
+        this.#result = terminal.exited.then((code) => {
+            this.#connected = false;
+            if (code !== null)
+                this.#exitCode = code;
+            else
+                this.#error = this.#disconnected
+                    ? "Disconnected; the PTY session keeps running. connectPty() attaches again."
+                    : "The PTY session was ended by a signal.";
+            return {
+                ...(this.#exitCode === undefined ? {} : { exitCode: this.#exitCode }),
+                ...(this.#error === undefined ? {} : { error: this.#error }),
+            };
+        });
+    }
+    get exitCode() {
+        return this.#exitCode;
+    }
+    get error() {
+        return this.#error;
     }
-    connectPty() {
-        return pty();
+    isConnected() {
+        return this.#connected;
     }
-    listPtySessions() {
-        return pty();
+    /** Resolves at once: the handle is returned connected. */
+    async waitForConnection() {
+        if (!this.#connected && this.#exitCode === undefined)
+            throw new DaytonaConnectionError(this.#error ?? "Connection closed");
     }
-    getPtySessionInfo() {
-        return pty();
+    async sendInput(data) {
+        if (!this.#connected)
+            throw new DaytonaConnectionError("PTY is not connected");
+        try {
+            this.#terminal.write(data);
+        }
+        catch (error) {
+            throw new DaytonaConnectionError(`Failed to send input to PTY: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    resize(cols, rows) {
+        return this.#resize(cols, rows);
+    }
+    /** Closes this connection; the session keeps running. */
+    async disconnect() {
+        if (!this.#connected)
+            return;
+        this.#disconnected = true;
+        this.#terminal.close();
     }
-    killPtySession() {
-        return pty();
+    /** Resolves when the session ends (or this connection closes) with its
+     * exit code, or `error` saying why there is none. */
+    wait() {
+        return this.#result;
     }
-    resizePtySession() {
-        return pty();
+    kill() {
+        return this.#kill();
     }
 }
+const PTY_TAG = "daytona-pty:";
+/** A session id as one word of the shell's command line, found again by
+ * listPtySessions in any client. */
+function ptyTag(id) {
+    return PTY_TAG + Buffer.from(id).toString("base64url");
+}
+function ptyOf(command) {
+    const words = String(command).split(" ");
+    const at = words.findIndex((word) => word.startsWith(PTY_TAG));
+    if (at < 0)
+        return undefined;
+    const size = /^(\d+)x(\d+)$/.exec(words[at + 1] ?? "");
+    return {
+        id: Buffer.from(words[at].slice(PTY_TAG.length), "base64url").toString(),
+        cols: Number(size?.[1] ?? 80),
+        rows: Number(size?.[2] ?? 24),
+    };
+}
 function describe(command) {
     return {
         id: command.id,
@@ -355,9 +559,6 @@ function describe(command) {
         ...(command.exitCode === undefined ? {} : { exitCode: command.exitCode }),
     };
 }
-function pty() {
-    return Promise.reject(new NotSupportedError("Daytona's PTY sessions", "Use `await sandbox.withruntime.terminal({ cols, rows, onData })` for an interactive terminal, or a session for commands."));
-}
 function entrypoint() {
     return Promise.reject(new NotSupportedError("The image entrypoint session", "A Runtime image does not run an entrypoint; start it with process.createSession and executeSessionCommand."));
 }

package/dist/daytona/sandbox.d.ts

@@ -1,14 +1,20 @@
 import type { Runtime } from "../client.js";
 import type { RuntimeSandbox } from "./client.js";
+import { ComputerUse } from "./computer-use.js";
 import { DaytonaNotFoundError } from "./errors.js";
 import { FileSystem } from "./filesystem.js";
 import { Git } from "./git.js";
 import { Process } from "./process.js";
 /** How the sandbox's lease follows Daytona's lifecycle settings. */
 export interface Lifecycle {
-    /** Seconds without a call from this client before the sandbox pauses
-     * (Daytona's autoStopInterval), 60 to 3600. */
+    /** The lease each call renews, 60 to 3600 seconds: Runtime's longest
+     * lease is an hour. */
     windowSeconds: number;
+    /** Seconds without a call from this client before the sandbox pauses
+     * (Daytona's autoStopInterval); Infinity for 0, never. Past an hour the
+     * lease is renewed an hour at a time while this object lives. When
+     * absent, windowSeconds. */
+    idleSeconds?: number;
     /** Epoch ms past which the lease is never extended (ttlMinutes). */
     deadline?: number;
     /** stop() ends the sandbox instead of pausing it (ephemeral, or
@@ -24,6 +30,8 @@ export interface SandboxOptions {
     public: boolean;
     lifecycle: Lifecycle;
     snapshot?: string;
+    /** create's `user`, when not the sandbox owner. */
+    user?: string;
 }
 export type SandboxState = "started" | "starting" | "stopping" | "stopped" | "paused" | "destroying" | "destroyed";
 export interface PortPreviewUrl {
@@ -90,7 +98,8 @@ export declare class Sandbox {
     get name(): string;
     get organizationId(): string;
     /** Daytona's user name, so `/home/${sandbox.user}` leads to the working
-     * directory. Commands run as Runtime's sandbox owner, with passwordless sudo. */
+     * directory, and commands run as Runtime's sandbox owner, with passwordless
+     * sudo; or the user given at create, whose commands run through sudo. */
     get user(): string;
     get labels(): Record<string, string>;
     get target(): string;
@@ -125,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 (1 to 60; 0 is 60). */
+    /** 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. */
@@ -161,7 +171,9 @@ export declare class Sandbox {
      * named `name`; `daytona.create({ snapshot: name })` starts from it. */
     createSnapshot(name: string, _timeout?: number): Promise<void>;
     _experimental_createSnapshot(name: string, timeout?: number): Promise<void>;
-    get computerUse(): never;
+    /** Daytona's computer use over Runtime's desktop: `await
+     * sandbox.computerUse.start()`, then the mouse, keyboard and screenshots. */
+    get computerUse(): ComputerUse;
     setLabels(labels: Record<string, string>): Promise<Record<string, string>>;
     recover(): Promise<never>;
     resize(): Promise<never>;
@@ -181,6 +193,13 @@ 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 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;
 /** Daytona's network settings as Runtime's rules, or undefined for the

package/dist/daytona/sandbox.js

@@ -1,4 +1,5 @@
-import { RuntimeError } from "../errors.js";
+import { LeaseKeeper } from "../compat/lease.js";
+import { ComputerUse } from "./computer-use.js";
 import { HOME, HOME_LINK } from "./context.js";
 import { DaytonaError, DaytonaNotFoundError, guard, NotSupportedError } from "./errors.js";
 import { FileSystem } from "./filesystem.js";
@@ -96,6 +97,10 @@ export class Sandbox {
     #options;
     #home;
     #pausedByPause = false;
+    #computerUse;
+    /** When this client last made a call: autoStopInterval counts from it. */
+    #lastActive = Date.now();
+    #keeper;
     /** Use daytona.create or daytona.get. */
     constructor(runtime, client, options) {
         this.#rt = runtime;
@@ -104,9 +109,20 @@ export class Sandbox {
         this.env = { ...options.env };
         this.public = options.public;
         this.snapshot = options.snapshot;
+        this.#keeper = new LeaseKeeper({
+            sandbox: () => this.#rt,
+            until: () => {
+                const lifecycle = this.#options.lifecycle;
+                return Math.min(this.#lastActive + (lifecycle.idleSeconds ?? lifecycle.windowSeconds) * 1000, lifecycle.deadline ?? Infinity);
+            },
+            // Renewed when less than half the window is left, so a run of calls
+            // costs one extend per half window.
+            marginMs: () => this.#options.lifecycle.windowSeconds * 500,
+        });
         const ctx = {
             live: () => this.#live(),
             language: options.language,
+            ...(options.user ? { user: options.user } : {}),
             ensureHome: (text) => this.#ensureHome(text),
         };
         // A getter, so the modules see the environment updateEnv sets.
@@ -131,9 +147,10 @@ export class Sandbox {
         return "";
     }
     /** Daytona's user name, so `/home/${sandbox.user}` leads to the working
-     * directory. Commands run as Runtime's sandbox owner, with passwordless sudo. */
+     * directory, and commands run as Runtime's sandbox owner, with passwordless
+     * sudo; or the user given at create, whose commands run through sudo. */
     get user() {
-        return "daytona";
+        return this.#options.user ?? "daytona";
     }
     get labels() {
         return { ...this.#rt.info.labels };
@@ -195,29 +212,13 @@ export class Sandbox {
     }
     /** The sandbox, its lease moved on when less than half of the autoStop
      * window is left: every call through this object counts as activity, as
-     * Daytona's API calls do. */
+     * Daytona's API calls do. An autoStopInterval past an hour, or 0, is kept
+     * by renewing the lease while this object lives. */
     async #live(force = false) {
-        const lifecycle = this.#options.lifecycle;
         if (this.#rt.state !== "running")
             return this.#rt;
-        const left = Date.parse(this.#rt.info.expiresAt) - Date.now();
-        if (!force && left > lifecycle.windowSeconds * 500)
-            return this.#rt;
-        let seconds = Math.ceil(lifecycle.windowSeconds - left / 1000);
-        if (lifecycle.deadline !== undefined)
-            seconds = Math.min(seconds, Math.floor((lifecycle.deadline - Date.now() - left) / 1000));
-        if (seconds < 1)
-            return this.#rt;
-        try {
-            await this.#rt.extend(seconds);
-        }
-        catch (error) {
-            // The lease may have ended since this object last looked; the call
-            // itself then says what state the sandbox is in.
-            if (!(error instanceof RuntimeError && error.status === 409))
-                throw error;
-            await this.#rt.refresh().catch(() => undefined);
-        }
+        this.#lastActive = Date.now();
+        await this.#keeper.check(force);
         return this.#rt;
     }
     #ensureHome(text) {
@@ -237,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
@@ -248,6 +253,7 @@ export class Sandbox {
         if (state === "stopped" || state === "stopping")
             return;
         if (this.#options.lifecycle.ephemeral) {
+            this.#keeper.end();
             await guard("sandbox", () => this.#rt.stop());
             return;
         }
@@ -269,6 +275,7 @@ export class Sandbox {
     }
     /** Ends the sandbox for good. */
     async delete(_timeout) {
+        this.#keeper.end();
         await guard("sandbox", () => this.#rt.refresh());
         if (this.#rt.state !== "stopped")
             await guard("sandbox", () => this.#rt.stop({ wait: false }));
@@ -288,12 +295,18 @@ export class Sandbox {
     async refreshActivity() {
         await guard("sandbox", () => this.#live(true));
     }
-    /** The sandbox pauses after `interval` minutes without a call from this
-     * client (1 to 60; 0 is 60). */
+    /** 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());
     }
     setAutoPauseInterval(interval) {
@@ -317,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.");
@@ -377,8 +392,11 @@ export class Sandbox {
         return this.createSnapshot(name, timeout);
     }
     // ---- what Runtime does differently -----------------------------------------
+    /** Daytona's computer use over Runtime's desktop: `await
+     * sandbox.computerUse.start()`, then the mouse, keyboard and screenshots. */
     get computerUse() {
-        throw new NotSupportedError("Daytona's computer use", "Use Runtime's desktop: `await sandbox.withruntime.desktop.start()` (see the desktop guide).");
+        this.#computerUse ??= new ComputerUse(() => this.#live());
+        return this.#computerUse;
     }
     async setLabels(labels) {
         const internal = Object.fromEntries(Object.entries(this.#rt.info.labels).filter(([key]) => key === "code-toolbox-language" || key.startsWith("compat.")));
@@ -437,6 +455,21 @@ 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 a sandbox with a time to live pauses. */
+export function idleSeconds(autoStopMinutes) {
+    if (autoStopMinutes <= 0)
+        return Infinity;
+    return Math.max(60, Math.round(autoStopMinutes * 60));
+}
 /** Minutes as Runtime's retention: whole days, 1 to 365. */
 export function retentionDays(minutes) {
     return Math.min(365, Math.max(1, Math.ceil(minutes / 1440)));

package/dist/e2b/client.d.ts

@@ -3,6 +3,8 @@ import { Runtime } from "../client.js";
 export type RuntimeSandbox = Awaited<ReturnType<Runtime["sandboxes"]["create"]>>;
 /** What `Sandbox.create` sends to Runtime. */
 export type RuntimeCreate = NonNullable<Parameters<Runtime["sandboxes"]["create"]>[0]>;
+/** E2B's HTTP version for its API and sandboxes (e2b 2.52.0). */
+export type HttpVersion = "1.1" | "2";
 /** E2B's connection options, as far as they mean anything on Runtime. */
 export interface ConnectionOpts {
     /** A Runtime key. Default: RUNTIME_API_KEY, then E2B_API_KEY if it holds a
@@ -18,6 +20,9 @@ export interface ConnectionOpts {
     retries?: number;
     /** Accepted and ignored: Runtime's SDK does not take a logger. */
     logger?: unknown;
+    /** Checked as E2B checks it (and E2B_HTTP_VERSION), then left to Runtime's
+     * SDK, which picks its own transport. */
+    httpVersion?: HttpVersion;
     /** E2B endpoints. Refused: this package only talks to Runtime. */
     domain?: string;
     apiUrl?: string;

package/dist/e2b/client.js

@@ -1,5 +1,5 @@
 import { Runtime } from "../client.js";
-import { AuthenticationError, NotSupportedError } from "./errors.js";
+import { AuthenticationError, InvalidArgumentError, NotSupportedError } from "./errors.js";
 const env = (name) => typeof process === "undefined" ? undefined : process.env[name];
 const isE2BKey = (key) => key.startsWith("e2b_");
 /** Refuses the E2B-only connection options: they point at E2B, and quietly
@@ -18,6 +18,10 @@ export function refuseE2BConnection(opts = {}) {
                 ? "Set HTTPS_PROXY in the environment instead; Runtime's SDK reads it."
                 : "Remove it: this package talks only to Runtime (RUNTIME_API_URL overrides the API origin).");
     }
+    // E2B refuses any other version, from the option or the environment.
+    const version = opts.httpVersion ?? (env("E2B_HTTP_VERSION") || undefined);
+    if (version !== undefined && version !== "1.1" && version !== "2")
+        throw new InvalidArgumentError(`${opts.httpVersion === undefined ? "E2B_HTTP_VERSION" : "httpVersion"} must be '1.1' or '2', got '${version}'`);
     if (opts.debug)
         throw new NotSupportedError("E2B's debug mode (a local envd)", "Remove debug: true; there is no local Runtime guest to connect to.");
 }

package/dist/e2b/commands.d.ts

@@ -1,5 +1,5 @@
 import type { Process } from "../sandbox.js";
-import type { ProcessInfo as RuntimeProcessInfo } from "../types.js";
+import type { OutputEvent, ProcessInfo as RuntimeProcessInfo } from "../types.js";
 import type { RequestOptions } from "../transport.js";
 import type { RuntimeSandbox } from "./client.js";
 import { TimeoutError, type CommandResult } from "./errors.js";
@@ -12,9 +12,9 @@ export interface CommandRequestOpts {
 export interface CommandStartOpts extends CommandRequestOpts {
     background?: boolean;
     cwd?: string;
-    /** Only the default user. Runtime runs commands as `runtime`, the sandbox's
-     * owner, with passwordless sudo; E2B's `root` is refused rather than
-     * silently run as someone else. */
+    /** "user" (the default) is the sandbox's own user, `runtime`; any other
+     * user that exists in the sandbox, `root` included, runs it through
+     * `sudo -u`. An unknown user is refused, never created. */
     user?: Username;
     envs?: Record<string, string>;
     onStdout?: (data: string) => void | Promise<void>;
@@ -47,7 +47,6 @@ export interface SandboxContext {
 /** 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 declare function pidOf(processId: string): number;
-export declare function refuseUser(user: Username | undefined): void;
 export declare function timeoutFor(timeoutMs: number | undefined): number;
 /** One budget for lookup and mutation, including retries and queued input. */
 export declare function commandRequest(opts: CommandRequestOpts, defaultTimeoutMs?: number): RequestOptions;
@@ -88,13 +87,23 @@ export declare class Commands {
     /** Attaches to a running command; output from now on reaches the handle. */
     connect(pid: number, opts?: CommandConnectOpts): Promise<CommandHandle>;
 }
+/** A command whose output this handle reads from the request that started
+ * it: its process id, the rest of its events, the controller that ends the
+ * read, and the Runtime process, fetched only when something needs it. */
+export interface StartedStream {
+    started: true;
+    id: string;
+    events: AsyncIterator<OutputEvent>;
+    abort: AbortController;
+    process: () => Promise<Process>;
+}
 /** A command started in the background: E2B's CommandHandle over a Runtime
  * process. Output streams into `stdout`/`stderr` and the callbacks as it
  * arrives. */
 export declare class CommandHandle {
     #private;
     readonly pid: number;
-    constructor(process: Process, options: {
+    constructor(source: Process | StartedStream, options: {
         stdin: boolean;
         timeoutMs: number;
         cursor?: number;