withruntime 0.3.1 → 0.5.0

package/dist/daytona/daytona.js

@@ -0,0 +1,416 @@
+import { clientFor, } from "./client.js";
+import { DaytonaError, DaytonaNotFoundError, guard, NotSupportedError } from "./errors.js";
+import { 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
+ * 23 September 2026). */
+export const DEFAULT_RESOURCES = { cpu: 1, memory: 1, disk: 3 };
+/** Daytona's default autoStopInterval, 15 minutes. */
+export const DEFAULT_AUTO_STOP_MINUTES = 15;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Daytona's own snapshots (daytona-small, daytonaio/sandbox:...) are
+ * Runtime's stock image: Ubuntu 24.04 with Python 3.12, Node.js 24 and Bun. */
+const STOCK_SNAPSHOT = /^daytona(io)?[-/:]|^daytona$/;
+/** Daytona's label for a sandbox's code language. */
+export const LANGUAGE_LABEL = "code-toolbox-language";
+export var CodeLanguage;
+(function (CodeLanguage) {
+    CodeLanguage["PYTHON"] = "python";
+    CodeLanguage["TYPESCRIPT"] = "typescript";
+    CodeLanguage["JAVASCRIPT"] = "javascript";
+})(CodeLanguage || (CodeLanguage = {}));
+/** An image name Runtime accepts: letters, digits, dot, dash and underscore. */
+const imageName = (reference) => reference.replace(/[^A-Za-z0-9._-]+/g, "-").slice(0, 128);
+function snapshotOf(image) {
+    const state = image.state === "ready"
+        ? "active"
+        : image.state === "failed"
+            ? "error"
+            : image.state === "deleting" || image.state === "deleted"
+                ? "removing"
+                : image.state === "queued"
+                    ? "pending"
+                    : "building";
+    return {
+        id: image.id,
+        name: image.name ?? image.id,
+        imageName: image.name ?? image.id,
+        state,
+        size: image.sizeBytes === null ? null : image.sizeBytes / 1_073_741_824,
+        errorReason: image.error,
+        createdAt: image.createdAt,
+        updatedAt: image.readyAt ?? image.createdAt,
+        lastUsedAt: null,
+        general: false,
+        cpu: 0,
+        gpu: 0,
+        mem: 0,
+        disk: 0,
+    };
+}
+function volumeOf(volume) {
+    return {
+        id: volume.id,
+        name: volume.name ?? volume.id,
+        organizationId: "",
+        state: volume.state === "ready" ? "ready" : volume.state,
+        createdAt: volume.createdAt,
+        updatedAt: volume.readyAt ?? volume.createdAt,
+        lastUsedAt: null,
+        errorReason: volume.error,
+    };
+}
+/** Builds (or finds, when built before) the Runtime image for a Daytona
+ * image: a registry reference or a declarative Image. */
+async function imageFor(client, image, onLogs, name) {
+    const built = typeof image === "string" ? undefined : await image.build();
+    const wanted = name ?? (built ? built.name : imageName(image));
+    const existing = (await client.images.list({ name: wanted, state: "ready", limit: 1 })).data[0];
+    if (existing)
+        return existing;
+    return client.images.build(built
+        ? { name: wanted, dockerfile: built.dockerfile, files: built.files }
+        : { name: wanted, image: image }, onLogs ? { onLog: (line) => onLogs(`${line.text}\n`) } : {});
+}
+/** `daytona.snapshot`: Daytona snapshots as Runtime images. */
+export class SnapshotService {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    async list(queryOrPage, maybeLimit) {
+        const query = typeof queryOrPage === "object" ? queryOrPage : { page: queryOrPage, limit: maybeLimit };
+        if (query.sourceSandboxId !== undefined)
+            throw new NotSupportedError("Listing snapshots by source sandbox", "Use runtime.snapshots.list({ sandboxId }) through sandbox.withruntime.");
+        const all = await guard("other", async () => (await this.#client.images.list()).toArray(10_000));
+        const limit = query.limit ?? 100;
+        const page = query.page ?? 1;
+        const items = all.filter((one) => one.state !== "deleted").map(snapshotOf);
+        return {
+            items: items.slice((page - 1) * limit, page * limit),
+            total: items.length,
+            page,
+            totalPages: Math.max(1, Math.ceil(items.length / limit)),
+        };
+    }
+    async get(idOrName) {
+        if (UUID.test(idOrName))
+            return snapshotOf(await guard("other", () => this.#client.images.get(idOrName)));
+        const found = (await guard("other", () => this.#client.images.list({ name: imageName(idOrName), limit: 1 }))).data[0];
+        if (!found)
+            throw notFound(`Snapshot ${idOrName}`);
+        return snapshotOf(found);
+    }
+    /** Builds a Runtime image named `name` from a registry image or a Daytona
+     * Image, streaming the build log to `onLogs`. */
+    async create(params, options = {}) {
+        if (params.resources)
+            throw new NotSupportedError("Resources on a snapshot", "Pass resources when creating each sandbox from it: daytona.create({ snapshot, resources }).");
+        if (params.entrypoint)
+            throw new NotSupportedError("An entrypoint on a snapshot", "Start the program in a session after create: process.executeSessionCommand(id, { command, runAsync: true }).");
+        const image = await guard("other", () => imageFor(this.#client, params.image, options.onLogs, imageName(params.name)));
+        return snapshotOf(image);
+    }
+    async delete(snapshot) {
+        const id = typeof snapshot === "string" ? (await this.get(snapshot)).id : snapshot.id;
+        await guard("other", () => this.#client.images.delete(id));
+    }
+    /** Runtime images do not go inactive: returns the snapshot as it is. */
+    async activate(snapshot) {
+        return this.get(typeof snapshot === "string" ? snapshot : snapshot.id);
+    }
+}
+/** `daytona.volume`: Daytona volumes as Runtime volumes. */
+export class VolumeService {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    async list() {
+        const all = await guard("other", async () => (await this.#client.volumes.list()).toArray(10_000));
+        return all.filter((one) => one.state !== "deleted").map(volumeOf);
+    }
+    async get(name, create = false) {
+        const found = (await guard("other", () => this.#client.volumes.list({ name, limit: 1 })))
+            .data[0];
+        if (found)
+            return volumeOf(found);
+        if (create)
+            return this.create(name);
+        throw notFound(`Volume ${name}`);
+    }
+    create(name) {
+        return Promise.reject(new NotSupportedError(`Creating the volume ${name} without a size`, `Runtime volumes have a fixed size: runtime.volumes.create({ name: "${name}", sizeMiB: 10240 }), then mount it by name.`));
+    }
+    async delete(volume) {
+        await guard("other", () => this.#client.volumes.delete(volume.id));
+    }
+}
+function unsupportedService(name, alternative) {
+    return new Proxy({}, {
+        get: (_target, property) => {
+            if (typeof property === "symbol" || property === "then")
+                return undefined;
+            return () => Promise.reject(new NotSupportedError(`Daytona's ${name}`, alternative));
+        },
+    });
+}
+/** Daytona's client. Uses RUNTIME_API_KEY (or a Runtime key in apiKey or
+ * DAYTONA_API_KEY, or the saved `npx withruntime login`). */
+export class Daytona {
+    snapshot;
+    volume;
+    secret;
+    warmPool;
+    #client;
+    #create;
+    constructor(config = {}) {
+        this.#client = clientFor(config);
+        this.#create = config.withruntime?.create ?? {};
+        this.snapshot = new SnapshotService(this.#client);
+        this.volume = new VolumeService(this.#client);
+        this.secret = unsupportedService("secrets", "Pass credentials as envVars or per command, never in the command text.");
+        this.warmPool = unsupportedService("warm pools", "Runtime starts sandboxes from warm templates already; nothing to configure.");
+    }
+    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. */
+    async create(params = {}, options = {}) {
+        refuseCreate(params);
+        const client = params.withruntime?.client ?? this.#client;
+        const lifecycle = lifecycleOf(params);
+        const resources = { ...DEFAULT_RESOURCES, ...params.resources };
+        if (resources.gpu)
+            throw new NotSupportedError("GPUs", "Runtime runs sandboxes on CPUs; remove gpu from resources.");
+        const source = await this.#source(client, params, options.onSnapshotCreateLogs);
+        const volumes = await this.#volumes(client, params.volumes);
+        const network = networkRules(params);
+        // Daytona keeps the language in this label, so a sandbox found later with
+        // get() or list() runs codeRun in the language it was made for.
+        const labels = params.language && params.language !== "python"
+            ? { ...params.labels, [LANGUAGE_LABEL]: params.language }
+            : params.labels && Object.keys(params.labels).length
+                ? params.labels
+                : undefined;
+        const input = {
+            ...(source.snapshot
+                ? {}
+                : {
+                    vcpu: resources.cpu,
+                    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,
+            onLeaseEnd: lifecycle.ephemeral || lifecycle.deadline ? "stop" : "pause",
+            ...(params.name ? { name: params.name } : {}),
+            ...(labels ? { labels } : {}),
+            ...(network ? { network } : {}),
+            ...(volumes.length ? { volumes } : {}),
+            ...source,
+            ...this.#create,
+            ...params.withruntime?.create,
+        };
+        const runtime = await guard("sandbox", () => client.sandboxes.create(input));
+        if (lifecycle.autoDeleteInterval > 0)
+            await guard("sandbox", () => runtime.setRetention(retentionDays(lifecycle.autoDeleteInterval))).catch(async (error) => {
+                await runtime.stop({ wait: false }).catch(() => undefined);
+                throw error;
+            });
+        const env = {
+            ...params.envVars,
+            ...(params.outboundProxyUrl
+                ? { HTTP_PROXY: params.outboundProxyUrl, HTTPS_PROXY: params.outboundProxyUrl }
+                : {}),
+        };
+        return new Sandbox(runtime, client, {
+            env,
+            language: params.language ?? "python",
+            public: params.public ?? false,
+            lifecycle,
+            ...("snapshot" in params && params.snapshot ? { snapshot: params.snapshot } : {}),
+        });
+    }
+    async #source(client, params, onLogs) {
+        if ("image" in params && params.image !== undefined) {
+            const image = await guard("other", () => imageFor(client, params.image, onLogs));
+            return { image: image.id };
+        }
+        const name = "snapshot" in params ? params.snapshot : undefined;
+        if (name === undefined || STOCK_SNAPSHOT.test(name))
+            return {};
+        if (UUID.test(name)) {
+            try {
+                await client.images.get(name);
+                return { image: name };
+            }
+            catch (error) {
+                if (error.status !== 404)
+                    throw error;
+            }
+            return { snapshot: name };
+        }
+        const image = (await guard("other", () => client.images.list({ name: imageName(name), state: "ready", limit: 1 }))).data[0];
+        if (image)
+            return { image: image.id };
+        const snapshot = (await guard("other", () => client.snapshots.list({ name, state: "ready", limit: 1 }))).data[0];
+        if (snapshot)
+            return { snapshot: snapshot.id };
+        throw new DaytonaNotFoundError(`No Runtime image or snapshot is named "${name}". Daytona snapshots do not move to Runtime; build the same ` +
+            `environment as a Runtime image with that name: daytona.snapshot.create({ name: "${name}", image }) with this ` +
+            `package, or \`npx withruntime image build --dockerfile Dockerfile --name ${imageName(name)}\`.`, 404);
+    }
+    async #volumes(client, mounts) {
+        const out = [];
+        for (const mount of mounts ?? []) {
+            if (mount.subpath)
+                throw new NotSupportedError("Mounting part of a volume (subpath)", "Mount the whole volume.");
+            let id = mount.volumeId;
+            if (!UUID.test(id)) {
+                const found = (await guard("other", () => client.volumes.list({ name: id, limit: 1 })))
+                    .data[0];
+                if (!found)
+                    throw notFound(`Volume ${id}`);
+                id = found.id;
+            }
+            out.push({ volumeId: id, path: mount.mountPath });
+        }
+        return out;
+    }
+    /** A sandbox by id or name. */
+    async get(sandboxIdOrName) {
+        const runtime = await guard("sandbox", () => find(this.#client, sandboxIdOrName));
+        return this.#adopt(runtime);
+    }
+    #adopt(runtime) {
+        const onLeaseEnd = runtime.info.onLeaseEnd;
+        return new Sandbox(runtime, this.#client, {
+            env: {},
+            language: runtime.info.labels[LANGUAGE_LABEL] ?? "python",
+            public: false,
+            lifecycle: {
+                windowSeconds: runtime.info.timeoutSeconds,
+                ephemeral: onLeaseEnd === "stop",
+                autoStopInterval: Math.round(runtime.info.timeoutSeconds / 60),
+                autoArchiveInterval: 0,
+                autoDeleteInterval: -1,
+            },
+        });
+    }
+    /** Live and stopped (paused) sandboxes, oldest first. Await it for the old
+     * paginated shape, `{ items, total, page, totalPages }`. */
+    list(query = {}) {
+        const known = new Set(["limit", "name", "labels", "states"]);
+        const other = Object.keys(query).find((key) => query[key] !== undefined && !known.has(key));
+        if (other)
+            throw new NotSupportedError(`Listing sandboxes by ${other}`, "Filter by name, labels or states, and sort or narrow the result yourself.");
+        const states = query.states?.flatMap((state) => state === "started"
+            ? ["running"]
+            : state === "starting"
+                ? ["starting", "resuming"]
+                : state === "stopping"
+                    ? ["pausing"]
+                    : state === "stopped" || state === "paused"
+                        ? ["paused"]
+                        : []);
+        const client = this.#client;
+        const adopt = (runtime) => this.#adopt(runtime);
+        const filter = {
+            ...(query.labels ? { labels: query.labels } : {}),
+            ...(query.name ? { name: query.name } : {}),
+            ...(states ? { state: states } : {}),
+            ...(query.limit ? { limit: Math.min(query.limit, 100) } : {}),
+        };
+        async function* iterate() {
+            const page = await guard("other", () => client.sandboxes.list(filter));
+            for await (const runtime of page)
+                yield adopt(runtime);
+        }
+        const iterator = iterate();
+        return Object.assign(iterator, {
+            then(onFulfilled, onRejected) {
+                const all = (async () => {
+                    const page = await guard("other", () => client.sandboxes.list(filter));
+                    const items = (await page.toArray(10_000)).map(adopt);
+                    return { items, total: items.length, page: 1, totalPages: 1 };
+                })();
+                return all.then(onFulfilled, onRejected);
+            },
+        });
+    }
+    start(sandbox, timeout) {
+        return sandbox.start(timeout);
+    }
+    stop(sandbox) {
+        return sandbox.stop();
+    }
+    delete(sandbox, timeout) {
+        return sandbox.delete(timeout);
+    }
+    /** Daytona's older name for delete. */
+    remove(sandbox, timeout) {
+        return sandbox.delete(timeout);
+    }
+    fork(sandbox, params, timeout) {
+        return sandbox.fork(params, timeout);
+    }
+    _experimental_fork(sandbox, params, timeout) {
+        return sandbox.fork(params, timeout);
+    }
+}
+function refuseCreate(params) {
+    const refusals = [
+        ["spot", "Spot GPU sandboxes (spot)", "Remove it: Runtime runs sandboxes on CPUs."],
+        [
+            "linkedSandbox",
+            "Linked sandboxes (linkedSandbox)",
+            "Run both programs in one sandbox, or connect them through a preview address.",
+        ],
+        ["secrets", "Daytona secrets", "Pass credentials as envVars, never in the command text."],
+        [
+            "otelEndpointOverride",
+            "Sending sandbox telemetry elsewhere (otelEndpointOverride)",
+            "Remove it: Runtime does not export sandbox telemetry.",
+        ],
+    ];
+    for (const [field, feature, alternative] of refusals)
+        if (params[field] !== undefined)
+            throw new NotSupportedError(feature, alternative);
+    if (params.user !== undefined && params.user !== "daytona")
+        throw new NotSupportedError(`Running as the user "${params.user}"`, 'Commands run as the sandbox owner with passwordless sudo: prefix a command with "sudo" to run it as root.');
+    if (params.language !== undefined &&
+        !["python", "javascript", "typescript"].includes(params.language))
+        throw new NotSupportedError(`The language ${params.language}`, "Use python, javascript or typescript; run anything else with process.executeCommand.");
+    if (params.autoStopInterval !== undefined &&
+        params.autoPauseInterval !== undefined &&
+        params.autoStopInterval !== 0 &&
+        params.autoPauseInterval !== 0)
+        throw new DaytonaError("At most one of autoStopInterval and autoPauseInterval may be non-zero.", 400);
+}
+/** Daytona's lifecycle settings as the lease Runtime keeps. */
+export function lifecycleOf(params) {
+    const autoStop = params.autoPauseInterval || (params.autoStopInterval ?? DEFAULT_AUTO_STOP_MINUTES);
+    const autoDelete = params.ephemeral ? 0 : (params.autoDeleteInterval ?? -1);
+    return {
+        windowSeconds: windowSeconds(autoStop),
+        ...(params.ttlMinutes ? { deadline: Date.now() + params.ttlMinutes * 60_000 } : {}),
+        ephemeral: autoDelete === 0,
+        autoStopInterval: autoStop,
+        autoArchiveInterval: params.autoArchiveInterval ?? 10_080,
+        autoDeleteInterval: autoDelete,
+    };
+}
+/** The sandbox with this Runtime id, or the newest live one with this name. */
+async function find(client, idOrName) {
+    if (UUID.test(idOrName))
+        return client.sandboxes.get(idOrName);
+    const all = await (await client.sandboxes.list({ name: idOrName })).toArray(1000);
+    const found = all.at(-1);
+    if (!found)
+        throw notFound(`Sandbox ${idOrName}`);
+    return found;
+}

package/dist/daytona/errors.d.ts

@@ -0,0 +1,106 @@
+export declare const SOURCE_API = "DAYTONA_API";
+export declare const SOURCE_DAEMON = "DAYTONA_DAEMON";
+export declare const SOURCE_PROXY = "DAYTONA_PROXY";
+export declare class DaytonaError extends Error {
+    statusCode?: number;
+    code?: string;
+    readonly source?: string;
+    headers?: unknown;
+    hint?: string;
+    requestId?: string;
+    constructor(message: string, statusCode?: number, headers?: unknown, code?: string, source?: string);
+    /** Daytona's older name for `code`. */
+    get errorCode(): string | undefined;
+}
+export declare class DaytonaBadRequestError extends DaytonaError {
+}
+export declare class DaytonaAuthenticationError extends DaytonaError {
+}
+export declare class DaytonaForbiddenError extends DaytonaError {
+}
+export declare class DaytonaNotFoundError extends DaytonaError {
+}
+export declare class DaytonaTimeoutError extends DaytonaError {
+}
+export declare class DaytonaConflictError extends DaytonaError {
+}
+export declare class DaytonaGoneError extends DaytonaError {
+}
+export declare class DaytonaUnprocessableEntityError extends DaytonaError {
+}
+export declare class DaytonaRateLimitError extends DaytonaError {
+}
+export declare class DaytonaInternalServerError extends DaytonaError {
+}
+export declare class DaytonaBadGatewayError extends DaytonaError {
+}
+export declare class DaytonaServiceUnavailableError extends DaytonaError {
+}
+export declare class DaytonaValidationError extends DaytonaBadRequestError {
+}
+export declare class DaytonaAuthorizationError extends DaytonaForbiddenError {
+}
+export declare class DaytonaInvalidArgumentError extends DaytonaValidationError {
+}
+export declare class DaytonaConnectionError extends DaytonaError {
+}
+export declare class DaytonaConnectionTimeoutError extends DaytonaConnectionError {
+}
+export declare class DaytonaGitAuthFailedError extends DaytonaAuthenticationError {
+}
+export declare class DaytonaGitRepoNotFoundError extends DaytonaNotFoundError {
+}
+export declare class DaytonaGitBranchNotFoundError extends DaytonaNotFoundError {
+}
+export declare class DaytonaGitBranchExistsError extends DaytonaConflictError {
+}
+export declare class DaytonaGitPushRejectedError extends DaytonaConflictError {
+}
+export declare class DaytonaGitDirtyWorktreeError extends DaytonaConflictError {
+}
+export declare class DaytonaGitMergeConflictError extends DaytonaConflictError {
+}
+export declare class DaytonaGitTransportFailedError extends DaytonaBadGatewayError {
+}
+export declare class DaytonaGitRemoteRejectedError extends DaytonaUnprocessableEntityError {
+}
+export declare class DaytonaFileNotFoundError extends DaytonaNotFoundError {
+}
+export declare class DaytonaFileAccessDeniedError extends DaytonaForbiddenError {
+}
+export declare class DaytonaInvalidFilePathError extends DaytonaBadRequestError {
+}
+export declare class DaytonaFileReadFailedError extends DaytonaInternalServerError {
+}
+export declare class DaytonaLspServerNotInitializedError extends DaytonaBadRequestError {
+}
+export declare class DaytonaProcessExecutionTimeoutError extends DaytonaTimeoutError {
+}
+export declare class DaytonaProcessNotFoundError extends DaytonaNotFoundError {
+}
+export declare class DaytonaSessionEndedError extends DaytonaGoneError {
+}
+export declare class DaytonaCommandAlreadyCompletedError extends DaytonaGoneError {
+}
+export declare class DaytonaA11yUnavailableError extends DaytonaServiceUnavailableError {
+}
+export declare class DaytonaRecordingStillActiveError extends DaytonaConflictError {
+}
+export declare class DaytonaRecordingFfmpegNotFoundError extends DaytonaServiceUnavailableError {
+}
+/** A call that Daytona 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 Runtime instead. */
+export declare class NotSupportedError extends DaytonaError {
+    readonly feature: string;
+    readonly alternative: string;
+    constructor(feature: string, alternative: string, message?: string);
+}
+/** Which object a call was about, to name a 404 the way Daytona would. */
+export type Subject = "sandbox" | "file" | "process" | "other";
+/** Turns a Runtime SDK error into the Daytona error a caller written for
+ * Daytona expects. Anything that is not a Runtime error passes through. */
+export declare function translate(error: unknown, subject?: Subject): unknown;
+/** Runs `work`, turning any Runtime error into its Daytona counterpart. */
+export declare function guard<T>(subject: Subject, work: () => Promise<T>): Promise<T>;