withruntime 0.10.0 → 0.11.1

package/dist/client.js

@@ -4,7 +4,7 @@ import { clientFactories, clientProductAliases } from "./products/index.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
 import { Sandbox, deleteSandbox, sandboxPage } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
-import { Transport, missingKey } from "./transport.js";
+import { DEFAULT_BASE_URL, Transport, missingKey } from "./transport.js";
 /** The key `runtime login` saved for this machine and this API origin, found
  * on first use. A constructor override must never receive another API's key. */
 const savedKey = async (apiOrigin) => {
@@ -30,10 +30,14 @@ export class Runtime {
     /** Date-range settlements, paged with exact charges and the server's CSV. */
     usageExport;
     constructor(options = {}) {
+        // The saved key is found by the origin as given, as `runtime login` saved
+        // it; the calls go where that origin is reachable from here, which in a
+        // sandbox is runtime.internal (transport.ts, `reachable`).
+        const origin = options.baseUrl || env("RUNTIME_API_URL") || DEFAULT_BASE_URL;
         this.transport = new Transport({
             // A key given, then RUNTIME_API_KEY, then (in Node and Bun) the key
             // `runtime login` saved for this machine, read on the first call.
-            apiKey: options.apiKey ?? env("RUNTIME_API_KEY") ?? (() => savedKey(this.transport.baseUrl)),
+            apiKey: options.apiKey ?? env("RUNTIME_API_KEY") ?? (() => savedKey(origin)),
             baseUrl: options.baseUrl ?? env("RUNTIME_API_URL"),
             ...(options.fetch ? { fetch: options.fetch } : {}),
             ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
@@ -97,6 +101,9 @@ export class Sandboxes {
      * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
     async create(input = {}, options = {}) {
         const { wait, ...body } = input;
+        const began = performance.now();
+        // Time spent waiting for capacity is the room's, not the deadline's.
+        let waited = 0;
         const info = await this.t.json({
             method: "POST",
             path: "/v1/sandboxes",
@@ -104,13 +111,22 @@ export class Sandboxes {
             wait: wait === false ? 0 : 60,
             ...options,
             waitForCapacityMs: options.waitForCapacityMs ?? this.t.waitForCapacityMs,
+            onCapacityWait: (refusal, waitMs) => {
+                waited += waitMs;
+                options.onCapacityWait?.(refusal, waitMs);
+            },
         });
         const sandbox = new Sandbox(this.t, info);
         if (wait !== false && info.state !== "running") {
+            // One deadline for the whole create: the wait for running gets what the
+            // create left of it (1 ms when nothing is left, so it ends as a timeout).
+            const { timeoutMs } = options;
             await sandbox.waitFor("running", {
                 timeoutSeconds: WAIT_FOR_TIMEOUT_SECONDS,
                 signal: options.signal,
-                timeoutMs: options.timeoutMs,
+                timeoutMs: timeoutMs
+                    ? Math.max(1, Math.ceil(timeoutMs - (performance.now() - began - waited)))
+                    : timeoutMs,
                 idempotencyKey: options.idempotencyKey,
             });
             if (sandbox.state !== "running")
@@ -156,6 +172,33 @@ export class Sandboxes {
         };
         return sandboxPage(this.t, await this.t.json({ method: "GET", path: "/v1/sandboxes", query, ...options }), query, options);
     }
+    /** Stops every live sandbox whose labels all match, eight at a time, and
+     * says which stopped and which failed; one failure does not stop the rest.
+     * Needs at least one label, so stopping everything is never one call. */
+    async stopAll(filter, options = {}) {
+        if (!filter?.labels || Object.keys(filter.labels).length === 0)
+            throw new RuntimeError({
+                message: "stopAll needs at least one label to match.",
+                code: "invalid_request",
+                status: 0,
+                hint: "Stop one sandbox with sandbox.stop(), or label the ones to stop together.",
+            });
+        const live = await (await this.list({ labels: filter.labels, limit: 100 }, options)).toArray(Infinity);
+        // One key cannot name several stops: each stop makes its own.
+        const { idempotencyKey: _one, ...each } = options;
+        // In list order, oldest first, whichever finishes first.
+        const errors = new Array(live.length);
+        let next = 0;
+        const worker = async () => {
+            for (let at = next++; at < live.length; at = next++)
+                await live[at].stop(each).catch((error) => (errors[at] = error ?? "failed"));
+        };
+        await Promise.all(Array.from({ length: Math.min(8, live.length) }, worker));
+        return {
+            stopped: live.filter((_, at) => errors[at] === undefined).map((sbx) => sbx.id),
+            failed: live.flatMap((sbx, at) => errors[at] === undefined ? [] : [{ id: sbx.id, error: errors[at] }]),
+        };
+    }
 }
 export class FeedbackApi {
     t;

package/dist/compat/files.js

@@ -63,10 +63,14 @@ export class GuestFiles {
         if (!overwrite) {
             // cp -n alone reports success when it skips a raced destination. Stage
             // privately, then publish without replacement and verify it moved.
+            // mv -n that skips succeeds before coreutils 9.2 and fails from it on
+            // (the guest's 9.4 says "not replacing"), so a skip is told by the
+            // staged copy still being there beside a destination; with none there,
+            // mv's own error stands.
             await checked(sandbox, [
                 "bash",
                 "-c",
-                'set -e; parent=$(dirname -- "$2"); stage="$parent/.runtime-copy-$4"; mkdir -m 700 -- "$stage"; trap \'rm -rf -- "$stage"\' EXIT; if [ "$3" = true ]; then cp -R -n -- "$1" "$stage/item"; else cp -n -- "$1" "$stage/item"; fi; mv -n -T -- "$stage/item" "$2"; if [ -e "$stage/item" ] || [ -L "$stage/item" ]; then printf "Destination exists: %s\\n" "$2" >&2; exit 73; fi',
+                'set -e; parent=$(dirname -- "$2"); stage="$parent/.runtime-copy-$4"; mkdir -m 700 -- "$stage"; trap \'rm -rf -- "$stage"\' EXIT; if [ "$3" = true ]; then cp -R -- "$1" "$stage/item"; else cp -- "$1" "$stage/item"; fi; mv -n -T -- "$stage/item" "$2" 2>"$stage/mv.err" || :; if [ -e "$stage/item" ] || [ -L "$stage/item" ]; then if [ -e "$2" ] || [ -L "$2" ]; then printf "Destination exists: %s\\n" "$2" >&2; exit 73; fi; cat -- "$stage/mv.err" >&2; exit 1; fi',
                 "bash",
                 this.path(from),
                 this.path(to),

package/dist/compat/lease.d.ts

@@ -0,0 +1,37 @@
+/** The most one lease runs ahead of now. */
+export declare const LEASE_MAX_SECONDS = 3600;
+/** What the keeper needs of a Runtime sandbox. */
+export interface Leased {
+    readonly state: string;
+    readonly info: {
+        expiresAt: string;
+        endsAt?: string | null;
+    };
+    extend(seconds: number): Promise<unknown>;
+    refresh(): Promise<unknown>;
+}
+/** Whole seconds to add to a lease ending at `expiresAt` (epoch ms) so it
+ * reaches toward `until`, at most an hour ahead of `now`; 0 when more than
+ * `marginMs` is left or there is nothing to add. */
+export declare function extensionSeconds(expiresAt: number, until: number, now: number, marginMs: number): number;
+/** Keeps a running sandbox's lease reaching toward `until()`: on `check()`,
+ * and once a minute on a timer that never keeps a Node or Bun process alive.
+ * When the process ends, the lease runs out within the hour and the sandbox
+ * pauses or stops as it was told to at create. A paused or stopped sandbox is
+ * left alone; the adapter wakes it on its next call. */
+export declare class LeaseKeeper {
+    #private;
+    constructor(options: {
+        sandbox: () => Leased;
+        /** Epoch ms the lease should reach; Infinity for as long as this lives. */
+        until: () => number;
+        /** Extend only when less than this is left. */
+        marginMs: () => number;
+        everyMs?: number;
+    });
+    /** Extends the lease if it is near its end and should go further; `now`
+     * extends it as far as it may go whatever is left. One call at a time. */
+    check(now?: boolean): Promise<void>;
+    /** Stops extending: after stop() or delete(). */
+    end(): void;
+}

package/dist/compat/lease.js

@@ -0,0 +1,93 @@
+import { RuntimeError } from "../errors.js";
+/* 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
+ * reaches toward `until`, at most an hour ahead of `now`; 0 when more than
+ * `marginMs` is left or there is nothing to add. */
+export function extensionSeconds(expiresAt, until, now, marginMs) {
+    // A lease with no readable end (one that never ends) is left alone.
+    if (!Number.isFinite(expiresAt) || expiresAt - now > marginMs)
+        return 0;
+    const target = Math.min(until, now + LEASE_MAX_SECONDS * 1000);
+    return Math.max(0, Math.floor((target - expiresAt) / 1000));
+}
+/** Keeps a running sandbox's lease reaching toward `until()`: on `check()`,
+ * and once a minute on a timer that never keeps a Node or Bun process alive.
+ * When the process ends, the lease runs out within the hour and the sandbox
+ * pauses or stops as it was told to at create. A paused or stopped sandbox is
+ * left alone; the adapter wakes it on its next call. */
+export class LeaseKeeper {
+    #sandbox;
+    #until;
+    #marginMs;
+    #everyMs;
+    #timer;
+    #pending;
+    #ended = false;
+    constructor(options) {
+        this.#sandbox = options.sandbox;
+        this.#until = options.until;
+        this.#marginMs = options.marginMs;
+        this.#everyMs = options.everyMs ?? 60_000;
+    }
+    /** Starts the timer when the lease must outlive the next extension. */
+    #schedule() {
+        if (this.#ended || this.#timer)
+            return;
+        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(() => {
+            this.#timer = undefined;
+            void this.check().catch(() => undefined);
+        }, this.#everyMs);
+        this.#timer.unref?.();
+    }
+    /** Extends the lease if it is near its end and should go further; `now`
+     * extends it as far as it may go whatever is left. One call at a time. */
+    check(now = false) {
+        if (this.#ended)
+            return Promise.resolve();
+        this.#pending ??= this.#extend(now).finally(() => {
+            this.#pending = undefined;
+            this.#schedule();
+        });
+        return this.#pending;
+    }
+    async #extend(now) {
+        const sandbox = this.#sandbox();
+        // 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.endsAt ?? sandbox.info.expiresAt), this.#until(), Date.now(), now ? Infinity : this.#marginMs());
+        if (seconds < 1)
+            return;
+        try {
+            await sandbox.extend(seconds);
+        }
+        catch (error) {
+            // The lease may have ended since the sandbox was last read; the next
+            // call through the adapter says what state it is in.
+            if (!(error instanceof RuntimeError && error.status === 409))
+                throw error;
+            await sandbox.refresh().catch(() => undefined);
+        }
+    }
+    /** Stops extending: after stop() or delete(). */
+    end() {
+        this.#ended = true;
+        if (this.#timer)
+            clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+}

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/computer-use.d.ts

@@ -0,0 +1,162 @@
+import type { RuntimeSandbox } from "./client.js";
+type Live = () => Promise<RuntimeSandbox>;
+export interface ScreenshotRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ScreenshotOptions {
+    showCursor?: boolean;
+    format?: string;
+    quality?: number;
+    scale?: number;
+}
+export interface Position {
+    x?: number;
+    y?: number;
+}
+export interface ScreenshotResponse {
+    cursorPosition?: Position;
+    /** The image, base64. */
+    screenshot?: string;
+    sizeBytes?: number;
+}
+export interface DisplayInfo {
+    height?: number;
+    id?: number;
+    isActive?: boolean;
+    width?: number;
+    x?: number;
+    y?: number;
+}
+export interface WindowInfo {
+    height?: number;
+    id?: number;
+    isActive?: boolean;
+    title?: string;
+    width?: number;
+    x?: number;
+    y?: number;
+}
+export interface ProcessStatus {
+    autoRestart?: boolean;
+    pid?: number;
+    priority?: number;
+    running?: boolean;
+}
+export interface ComputerUseStartResponse {
+    message?: string;
+    status?: Record<string, ProcessStatus>;
+}
+export type ComputerUseStopResponse = ComputerUseStartResponse;
+export interface ComputerUseStatusResponse {
+    status?: string;
+}
+export interface Recording {
+    durationSeconds?: number;
+    endTime?: string;
+    fileName: string;
+    filePath: string;
+    id: string;
+    sizeBytes?: number;
+    startTime: string;
+    status: string;
+}
+export interface ListRecordingsResponse {
+    recordings: Recording[];
+}
+/** `sandbox.computerUse.mouse`. */
+export declare class Mouse {
+    #private;
+    /** Use sandbox.computerUse.mouse. */
+    constructor(live: Live);
+    getPosition(): Promise<Position>;
+    move(x: number, y: number): Promise<Position>;
+    click(x: number, y: number, button?: string, double?: boolean): Promise<Position>;
+    drag(startX: number, startY: number, endX: number, endY: number, button?: string): Promise<Position>;
+    /** `amount` wheel clicks up or down at (x, y). */
+    scroll(x: number, y: number, direction: "up" | "down", amount?: number): Promise<boolean>;
+}
+/** `sandbox.computerUse.keyboard`. Key names are Daytona's (enter, esc,
+ * ctrl, cmd, pageup, f5) or xdotool's (Return, Escape, Prior). */
+export declare class Keyboard {
+    #private;
+    /** Use sandbox.computerUse.keyboard. */
+    constructor(live: Live);
+    /** Types `text`, `delay` milliseconds between keys. */
+    type(text: string, delay?: number): Promise<void>;
+    press(key: string, modifiers?: string[]): Promise<void>;
+    /** A combination such as "ctrl+c" or "ctrl+shift+t". */
+    hotkey(keys: string): Promise<void>;
+}
+/** `sandbox.computerUse.screenshot`: the whole screen, PNG or JPEG. */
+export declare class Screenshot {
+    #private;
+    /** Use sandbox.computerUse.screenshot. */
+    constructor(live: Live);
+    takeFullScreen(showCursor?: boolean): Promise<ScreenshotResponse>;
+    takeRegion(_region: ScreenshotRegion, _showCursor?: boolean): Promise<ScreenshotResponse>;
+    takeCompressed(options?: ScreenshotOptions): Promise<ScreenshotResponse>;
+    takeCompressedRegion(_region: ScreenshotRegion, _options?: ScreenshotOptions): Promise<ScreenshotResponse>;
+}
+/** `sandbox.computerUse.display`. */
+export declare class Display {
+    #private;
+    /** Use sandbox.computerUse.display. */
+    constructor(live: Live);
+    /** The one screen, its size read from a screenshot. */
+    getInfo(): Promise<{
+        displays?: DisplayInfo[];
+    }>;
+    getWindows(): Promise<{
+        windows?: WindowInfo[];
+    }>;
+}
+/** `sandbox.computerUse.recording`: screen recordings to MP4. */
+export declare class RecordingService {
+    #private;
+    /** Use sandbox.computerUse.recording. */
+    constructor(live: Live);
+    /** Starts recording. Runtime names the file itself; `label` is not used. */
+    start(_label?: string): Promise<Recording>;
+    stop(id: string): Promise<Recording>;
+    list(): Promise<ListRecordingsResponse>;
+    get(id: string): Promise<Recording>;
+    delete(id: string): Promise<void>;
+    /** Saves the MP4 to `localPath`, making its directory. */
+    download(id: string, localPath: string): Promise<void>;
+}
+/** `sandbox.computerUse.accessibility`: Runtime's desktop has no
+ * accessibility tree; every method throws NotSupportedError. */
+export declare class Accessibility {
+    #private;
+    getTree(_options?: unknown): Promise<never>;
+    findNodes(_options?: unknown): Promise<never>;
+    focusNode(_id: string): Promise<never>;
+    invokeNode(_id: string, _action?: string): Promise<never>;
+    setNodeValue(_id: string, _value: string): Promise<never>;
+}
+/** `sandbox.computerUse`: a Linux desktop driven like a person would. */
+export declare class ComputerUse {
+    #private;
+    readonly mouse: Mouse;
+    readonly keyboard: Keyboard;
+    readonly screenshot: Screenshot;
+    readonly display: Display;
+    readonly recording: RecordingService;
+    readonly accessibility: Accessibility;
+    /** Use sandbox.computerUse. */
+    constructor(live: Live);
+    /** Starts the desktop. A sandbox's first start installs it, which takes a
+     * minute or two; this waits for that. */
+    start(): Promise<ComputerUseStartResponse>;
+    stop(): Promise<ComputerUseStopResponse>;
+    /** "active" while the desktop runs, else "inactive". */
+    getStatus(): Promise<ComputerUseStatusResponse>;
+    getProcessStatus(_processName: string): Promise<never>;
+    restartProcess(_processName: string): Promise<never>;
+    getProcessLogs(_processName: string): Promise<never>;
+    getProcessErrors(_processName: string): Promise<never>;
+}
+export {};