withruntime 0.10.0 → 0.11.0

package/dist/daytona/index.d.ts

@@ -1,8 +1,9 @@
 export { Daytona, CodeLanguage, SnapshotService, VolumeService, DEFAULT_RESOURCES, DEFAULT_AUTO_STOP_MINUTES, lifecycleOf, type CreateSandboxBaseParams, type CreateSandboxFromImageParams, type CreateSandboxFromSnapshotParams, type CreateSnapshotParams, type ForkSandboxParams, type ListSandboxesQuery, type PaginatedSnapshots, type Resources, type Snapshot, type Volume, type VolumeMount, } from "./daytona.js";
 export { Sandbox, CodeInterpreter, networkRules, windowSeconds, type ExecutionError, type ExecutionResult, type InterpreterContext, type OutputMessage, type PortPreviewUrl, } from "./sandbox.js";
-export { Process, CodeRunParams, type Command, type ExecuteResponse, type Session, type SessionCommandLogsResponse, type SessionExecuteRequest, type SessionExecuteResponse, } from "./process.js";
+export { Process, CodeRunParams, PtyHandle, type PtyConnectOptions, type PtyCreateOptions, type PtyResult, type PtySessionInfo, type Command, type ExecuteResponse, type Session, type SessionCommandLogsResponse, type SessionExecuteRequest, type SessionExecuteResponse, } from "./process.js";
 export { FileSystem, type FileDownloadRequest, type FileDownloadResponse, type FileInfo, type FilePermissionsParams, type FileUpload, type Match, type ReplaceResult, type SearchFilesResponse, type UploadSource, type UploadProgress, type UploadStreamOptions, } from "./filesystem.js";
 export { Git, type GitStatus, type ListBranchResponse } from "./git.js";
+export { Accessibility, ComputerUse, Display, Keyboard, Mouse, RecordingService, Screenshot, type ComputerUseStartResponse, type ComputerUseStatusResponse, type ComputerUseStopResponse, type DisplayInfo, type ListRecordingsResponse, type Recording, type ScreenshotOptions, type ScreenshotRegion, type ScreenshotResponse, type WindowInfo, } from "./computer-use.js";
 export { Image } from "./image.js";
 export { resolvePath } from "./context.js";
 export type { DaytonaConfig, WithRuntime } from "./client.js";
@@ -18,31 +19,6 @@ export declare const SandboxState: {
     readonly DESTROYED: "destroyed";
 };
 export type SandboxState = (typeof SandboxState)[keyof typeof SandboxState];
-export declare const ComputerUse: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare const Mouse: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare const Keyboard: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare const Screenshot: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
-export declare const Display: {
-    (...args: unknown[]): never;
-    new (...args: unknown[]): never;
-    readonly [key: string]: (...args: unknown[]) => never;
-};
 export declare const LspLanguageId: {
     (...args: unknown[]): never;
     new (...args: unknown[]): never;

package/dist/daytona/index.js

@@ -9,9 +9,10 @@
 import { NotSupportedError } from "./errors.js";
 export { Daytona, CodeLanguage, SnapshotService, VolumeService, DEFAULT_RESOURCES, DEFAULT_AUTO_STOP_MINUTES, lifecycleOf, } from "./daytona.js";
 export { Sandbox, CodeInterpreter, networkRules, windowSeconds, } from "./sandbox.js";
-export { Process, CodeRunParams, } from "./process.js";
+export { Process, CodeRunParams, PtyHandle, } from "./process.js";
 export { FileSystem, } from "./filesystem.js";
 export { Git } from "./git.js";
+export { Accessibility, ComputerUse, Display, Keyboard, Mouse, RecordingService, Screenshot, } from "./computer-use.js";
 export { Image } from "./image.js";
 export { resolvePath } from "./context.js";
 export * from "./errors.js";
@@ -41,10 +42,4 @@ function unsupportedExport(name, alternative) {
         },
     });
 }
-const DESKTOP = "Use Runtime's desktop: `await sandbox.withruntime.desktop.start()`.";
-export const ComputerUse = unsupportedExport("computer use", DESKTOP);
-export const Mouse = unsupportedExport("computer use (Mouse)", DESKTOP);
-export const Keyboard = unsupportedExport("computer use (Keyboard)", DESKTOP);
-export const Screenshot = unsupportedExport("computer use (Screenshot)", DESKTOP);
-export const Display = unsupportedExport("computer use (Display)", DESKTOP);
 export const LspLanguageId = unsupportedExport("language servers", "Start one in a session with process.executeSessionCommand(..., { runAsync: true }).");

package/dist/daytona/process.d.ts

@@ -1,3 +1,4 @@
+import type { Terminal } from "../sandbox.js";
 import { quote, type SandboxContext } from "./context.js";
 /** Daytona's ExecuteResponse. `result` is the command's stdout and stderr
  * together, in the order they were written. */
@@ -76,11 +77,67 @@ export declare class Process {
     deleteSession(sessionId: string): Promise<void>;
     getEntrypointSession(): Promise<never>;
     getEntrypointLogs(): Promise<never>;
-    createPty(): Promise<never>;
-    connectPty(): Promise<never>;
-    listPtySessions(): Promise<never>;
-    getPtySessionInfo(): Promise<never>;
-    killPtySession(): Promise<never>;
-    resizePtySession(): Promise<never>;
+    /** 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. */
+    createPty(options: PtyCreateOptions & Partial<PtyConnectOptions>): Promise<PtyHandle>;
+    /** Attaches to a running PTY session. Output it printed before arrives
+     * first, then what it prints from now on. */
+    connectPty(sessionId: string, options?: Partial<PtyConnectOptions>): Promise<PtyHandle>;
+    listPtySessions(): Promise<PtySessionInfo[]>;
+    getPtySessionInfo(sessionId: string): Promise<PtySessionInfo>;
+    /** Ends the session's shell and everything it runs. */
+    killPtySession(sessionId: string): Promise<void>;
+    resizePtySession(sessionId: string, cols: number, rows: number): Promise<PtySessionInfo>;
+}
+/** Daytona's PtyCreateOptions. */
+export interface PtyCreateOptions {
+    id: string;
+    cwd?: string;
+    envs?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+}
+/** Daytona's PtyConnectOptions. */
+export interface PtyConnectOptions {
+    onData: (data: Uint8Array) => void | Promise<void>;
+}
+/** Daytona's PtyResult. */
+export interface PtyResult {
+    exitCode?: number;
+    error?: string;
+}
+/** Daytona's PtySessionInfo. */
+export interface PtySessionInfo {
+    active: boolean;
+    cols: number;
+    createdAt: string;
+    cwd: string;
+    envs: Record<string, string>;
+    id: string;
+    lazyStart: boolean;
+    rows: number;
+}
+/** One connection to a PTY session, Daytona's PtyHandle over Runtime's
+ * terminal WebSocket. */
+export declare class PtyHandle {
+    #private;
+    readonly sessionId: string;
+    /** Use process.createPty or process.connectPty. */
+    constructor(terminal: Terminal, sessionId: string, resize: (cols: number, rows: number) => Promise<PtySessionInfo>, kill: () => Promise<void>);
+    get exitCode(): number | undefined;
+    get error(): string | undefined;
+    isConnected(): boolean;
+    /** Resolves at once: the handle is returned connected. */
+    waitForConnection(): Promise<void>;
+    sendInput(data: string | Uint8Array): Promise<void>;
+    resize(cols: number, rows: number): Promise<PtySessionInfo>;
+    /** Closes this connection; the session keeps running. */
+    disconnect(): Promise<void>;
+    /** Resolves when the session ends (or this connection closes) with its
+     * exit code, or `error` saying why there is none. */
+    wait(): Promise<PtyResult>;
+    kill(): Promise<void>;
 }
 export { quote };

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;
@@ -126,7 +135,7 @@ export declare class Sandbox {
     /** 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). */
+     * client; 0 never. Past an hour, while this object lives. */
     setAutostopInterval(interval: number): Promise<void>;
     setAutoPauseInterval(interval: number): Promise<void>;
     /** Runtime has no archive tier; recorded only. */
@@ -161,7 +170,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 +192,9 @@ 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 seconds without a
+ * call before the sandbox 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) {
@@ -248,6 +249,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 +271,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 }));
@@ -289,11 +292,12 @@ export class Sandbox {
         await guard("sandbox", () => this.#live(true));
     }
     /** The sandbox pauses after `interval` minutes without a call from this
-     * client (1 to 60; 0 is 60). */
+     * client; 0 never. Past an hour, while this object lives. */
     async setAutostopInterval(interval) {
         const lifecycle = this.#options.lifecycle;
         lifecycle.autoStopInterval = interval;
         lifecycle.windowSeconds = windowSeconds(interval);
+        lifecycle.idleSeconds = idleSeconds(interval);
         await guard("sandbox", () => this.#live());
     }
     setAutoPauseInterval(interval) {
@@ -377,8 +381,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 +444,13 @@ 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 seconds without a
+ * call before the sandbox 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)));