withruntime 0.4.0 → 0.5.1

package/dist/client.d.ts

@@ -16,6 +16,12 @@ export type RuntimeOptions = {
     maxRetries?: number;
     /** Calls in flight at once; more wait their turn and reuse connections. Default 32. */
     maxConnections?: number;
+    /** How long `sandboxes.create` keeps retrying, with the same key and input,
+     * when the trial's slots, the account's quota or the region is full
+     * (trial_busy, quota_exceeded, no_capacity and the like). Default 120 000
+     * (two minutes); 0 fails at once. The refusal is thrown as it came when the
+     * wait runs out. */
+    waitForCapacityMs?: number;
 };
 /** One client for every Runtime Cloud product. Create it once and reuse it:
  * it keeps its connections open. */
@@ -34,6 +40,10 @@ export declare class Runtime {
         principalId: string;
         credentialId: string | null;
         apiVersion: string;
+        /** The account's name. */
+        orgName?: string | null;
+        /** The role of the member who made this key: owner, admin, developer or billing. */
+        role?: string | null;
     }>;
     /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
     /** Credit, holds, trial time and per-resource charges. */
@@ -44,10 +54,23 @@ export declare class Sandboxes {
     constructor(t: Transport);
     /** Creates a sandbox and waits until it is running. Every field is optional:
      * with none you get the free trial while it lasts, the default region and a
-     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once. */
+     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
+     * When every trial slot or the account's quota is taken, it waits for one to
+     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
     create(input?: CreateSandbox & {
         wait?: boolean;
-    }, options?: RequestOptions): Promise<Sandbox>;
+    }, options?: RequestOptions & {
+        waitForCapacityMs?: number;
+    }): Promise<Sandbox>;
+    /** The sandbox named `name` in this account, ready to use: running as it
+     * is, woken if it is paused, restarted if it is stopped and persistent, or
+     * created with `input` when no sandbox has the name. `sandbox.info.reused`
+     * says which. The other fields apply only when it is created. */
+    getOrCreate(name: string, input?: Omit<CreateSandbox, "name" | "getOrCreate"> & {
+        wait?: boolean;
+    }, options?: RequestOptions & {
+        waitForCapacityMs?: number;
+    }): Promise<Sandbox>;
     get(id: string, options?: RequestOptions): Promise<Sandbox>;
     /** Live sandboxes, oldest first. Await for a page, or `for await` over all. */
     list(filter?: {

package/dist/client.js

@@ -30,6 +30,9 @@ export class Runtime {
             ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
             ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
             ...(options.maxConnections ? { maxConnections: options.maxConnections } : {}),
+            ...(options.waitForCapacityMs !== undefined
+                ? { waitForCapacityMs: options.waitForCapacityMs }
+                : {}),
         });
         this.sandboxes = new Sandboxes(this.transport);
         this.snapshots = new Snapshots(this.transport);
@@ -63,7 +66,9 @@ export class Sandboxes {
     }
     /** Creates a sandbox and waits until it is running. Every field is optional:
      * with none you get the free trial while it lasts, the default region and a
-     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once. */
+     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
+     * When every trial slot or the account's quota is taken, it waits for one to
+     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
     async create(input = {}, options = {}) {
         const { wait, ...body } = input;
         const info = await this.t.json({
@@ -72,6 +77,7 @@ export class Sandboxes {
             body,
             wait: wait === false ? 0 : 60,
             ...options,
+            waitForCapacityMs: options.waitForCapacityMs ?? this.t.waitForCapacityMs,
         });
         const sandbox = new Sandbox(this.t, info);
         if (wait !== false && info.state !== "running") {
@@ -86,6 +92,13 @@ export class Sandboxes {
         }
         return sandbox;
     }
+    /** The sandbox named `name` in this account, ready to use: running as it
+     * is, woken if it is paused, restarted if it is stopped and persistent, or
+     * created with `input` when no sandbox has the name. `sandbox.info.reused`
+     * says which. The other fields apply only when it is created. */
+    async getOrCreate(name, input = {}, options = {}) {
+        return this.create({ ...input, name, getOrCreate: true }, options);
+    }
     async get(id, options = {}) {
         return new Sandbox(this.t, await this.t.json({
             method: "GET",

package/dist/credentials.d.ts

@@ -7,6 +7,8 @@ export type SavedConnection = {
     connectionId: string;
     orgId: string;
     agentName: string;
+    /** The account's name when it was saved, for `runtime account`. */
+    orgName?: string;
 };
 export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
     api: string;
@@ -16,7 +18,15 @@ export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
  * returns a secret to CLI output. Store names bind credentials to both origins. */
 export declare function connectionStore(env: NodeJS.ProcessEnv, directory?: string): {
     read(): Promise<SavedConnection | null>;
+    /** Save the connection in use. One for another account moves to the
+     * saved accounts, so connecting a second account never loses the first
+     * (ARCHITECTURE.md section 3.9); one for the same account is replaced. */
     save(connection: SavedConnection): Promise<void>;
+    /** The other accounts this machine has connected, newest first. */
+    others(): Promise<SavedConnection[]>;
+    /** Use another saved account's connection, by account id or name. The one
+     * in use moves to the saved accounts. Null when none matches. */
+    use(which: string): Promise<SavedConnection | null>;
     remove(): Promise<void>;
     /** A browser approval that was started and not yet answered, so a command
      * that was stopped while it waited picks up the same link and code rather

package/dist/credentials.js

@@ -5,6 +5,8 @@ import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { apiOrigin } from "./index.js";
 import { missingKey } from "./transport.js";
+/** How many other accounts' connections one machine keeps beside the one in use. */
+const SAVED_ACCOUNTS = 20;
 export function connectionOrigins(env) {
     return {
         api: apiOrigin(env.RUNTIME_API_URL ?? "https://api.withruntime.com"),
@@ -93,6 +95,7 @@ export function connectionStore(env, directory = defaultDirectory(env)) {
             });
     }
     const pendingFile = join(directory, `${name}.pending.json`);
+    const accountsFile = join(directory, `${name}.accounts.json`);
     return {
         async read() {
             const text = await readPrivate(file, 4096, "saved connection");
@@ -112,15 +115,67 @@ export function connectionStore(env, directory = defaultDirectory(env)) {
                 !/^rtcloud_[a-f0-9-]{36}_[A-Za-z0-9_-]{43}$/.test(saved.key) ||
                 typeof saved.connectionId !== "string" ||
                 typeof saved.orgId !== "string" ||
-                typeof saved.agentName !== "string")
+                typeof saved.agentName !== "string" ||
+                (saved.orgName !== undefined && typeof saved.orgName !== "string"))
                 throw new Error("Runtime's saved connection is invalid. Connect again.");
             return saved;
         },
+        /** Save the connection in use. One for another account moves to the
+         * saved accounts, so connecting a second account never loses the first
+         * (ARCHITECTURE.md section 3.9); one for the same account is replaced. */
         async save(connection) {
             if (connection.apiOrigin !== origins.api || connection.authOrigin !== origins.auth)
                 throw new Error("Connection origins do not match.");
+            const previous = await this.read().catch(() => null);
+            if (previous && previous.orgId !== connection.orgId) {
+                const others = (await this.others()).filter((one) => one.orgId !== previous.orgId && one.orgId !== connection.orgId);
+                await writePrivate(accountsFile, JSON.stringify([previous, ...others].slice(0, SAVED_ACCOUNTS)));
+            }
             await writePrivate(file, JSON.stringify(connection));
         },
+        /** The other accounts this machine has connected, newest first. */
+        async others() {
+            let text;
+            try {
+                text = await readPrivate(accountsFile, 64 * 1024, "saved accounts");
+            }
+            catch {
+                return [];
+            }
+            if (text === null)
+                return [];
+            try {
+                const list = JSON.parse(text);
+                return Array.isArray(list)
+                    ? list.filter((one) => one &&
+                        one.version === 1 &&
+                        one.apiOrigin === origins.api &&
+                        one.authOrigin === origins.auth &&
+                        typeof one.key === "string" &&
+                        /^rtcloud_[a-f0-9-]{36}_[A-Za-z0-9_-]{43}$/.test(one.key) &&
+                        typeof one.orgId === "string")
+                    : [];
+            }
+            catch {
+                return [];
+            }
+        },
+        /** Use another saved account's connection, by account id or name. The one
+         * in use moves to the saved accounts. Null when none matches. */
+        async use(which) {
+            const others = await this.others();
+            const wanted = which.trim().toLowerCase();
+            const chosen = others.find((one) => one.orgId === which) ??
+                others.find((one) => one.orgName?.toLowerCase() === wanted) ??
+                null;
+            if (!chosen)
+                return null;
+            const current = await this.read().catch(() => null);
+            const rest = others.filter((one) => one.orgId !== chosen.orgId);
+            await writePrivate(accountsFile, JSON.stringify((current ? [current, ...rest] : rest).slice(0, SAVED_ACCOUNTS)));
+            await writePrivate(file, JSON.stringify(chosen));
+            return chosen;
+        },
         async remove() {
             await removePrivate(file);
         },

package/dist/daytona/client.d.ts

@@ -0,0 +1,44 @@
+import { Runtime } from "../client.js";
+/** The Runtime sandbox the adapter drives. */
+export type RuntimeSandbox = Awaited<ReturnType<Runtime["sandboxes"]["create"]>>;
+/** What `daytona.create` sends to Runtime. */
+export type RuntimeCreate = NonNullable<Parameters<Runtime["sandboxes"]["create"]>[0]>;
+/** Runtime-only options, for code that has been through the switch. */
+export interface WithRuntime {
+    /** A Runtime client to use instead of one made from the key. */
+    client?: Runtime;
+    /** Fields sent as they are with every create, over the adapter's own: for
+     * example `{ funding: "trial" }`. */
+    create?: Partial<RuntimeCreate>;
+}
+/** Daytona's client options, as far as they mean anything on Runtime. */
+export interface DaytonaConfig {
+    /** A Runtime key (`rtcloud_...`). Default: RUNTIME_API_KEY, then a Runtime
+     * key left in DAYTONA_API_KEY, then the key `npx withruntime login` saved.
+     * A Daytona key is never sent anywhere. */
+    apiKey?: string;
+    /** Refused: Runtime authenticates with keys. */
+    jwtToken?: string;
+    organizationId?: string;
+    /** Daytona's API address. Ignored: this package talks only to Runtime
+     * (RUNTIME_API_URL overrides Runtime's). */
+    apiUrl?: string;
+    serverUrl?: string;
+    /** "us" is Runtime's one region; any other is refused. */
+    target?: string;
+    /** Accepted and ignored: Runtime's SDK does not export traces. */
+    otelEnabled?: boolean;
+    useDeprecatedPolling?: boolean;
+    /** Accepted and ignored: Runtime's SDK sets its own request deadlines. */
+    requestTimeoutMs?: number;
+    _experimental?: Record<string, unknown>;
+    /** Runtime-only: an explicit client, or fields for every create. */
+    withruntime?: WithRuntime;
+}
+/** Explicit Runtime key, then RUNTIME_API_KEY, then DAYTONA_API_KEY when it
+ * holds a Runtime key; undefined lets the Runtime SDK find the saved login. */
+export declare function pickKey(explicit?: string): string | undefined;
+/** The Runtime client for this configuration. */
+export declare function clientFor(config?: DaytonaConfig): Runtime;
+/** Test hook: forget the cached clients. */
+export declare function resetClients(): void;

package/dist/daytona/client.js

@@ -0,0 +1,40 @@
+import { Runtime } from "../client.js";
+import { DaytonaAuthenticationError, NotSupportedError } from "./errors.js";
+const env = (name) => typeof process === "undefined" ? undefined : process.env[name];
+const isRuntimeKey = (key) => key.startsWith("rtcloud_");
+/** Explicit Runtime key, then RUNTIME_API_KEY, then DAYTONA_API_KEY when it
+ * holds a Runtime key; undefined lets the Runtime SDK find the saved login. */
+export function pickKey(explicit) {
+    if (explicit !== undefined && isRuntimeKey(explicit))
+        return explicit;
+    const runtimeKey = env("RUNTIME_API_KEY");
+    if (runtimeKey)
+        return runtimeKey;
+    if (explicit !== undefined && explicit !== "")
+        throw new DaytonaAuthenticationError("The apiKey passed is a Daytona API key, and it was not sent. Set RUNTIME_API_KEY to a Runtime key " +
+            "(https://withruntime.com/account/keys, or run `npx withruntime login`), or pass the Runtime key as apiKey.");
+    const daytonaVariable = env("DAYTONA_API_KEY");
+    return daytonaVariable && isRuntimeKey(daytonaVariable) ? daytonaVariable : undefined;
+}
+const clients = new Map();
+/** The Runtime client for this configuration. */
+export function clientFor(config = {}) {
+    if (config.jwtToken !== undefined || (config.organizationId !== undefined && !config.apiKey))
+        throw new NotSupportedError("Daytona JWT sign-in (jwtToken, organizationId)", "Use a Runtime key: set RUNTIME_API_KEY, or run `npx withruntime login` once.");
+    const target = config.target ?? env("DAYTONA_TARGET");
+    if (target !== undefined && target !== "" && target !== "us")
+        throw new NotSupportedError(`The Daytona target "${target}"`, 'Runtime runs in one US region; remove target or use "us".');
+    if (config.withruntime?.client)
+        return config.withruntime.client;
+    const key = pickKey(config.apiKey);
+    let client = clients.get(key ?? "");
+    if (!client) {
+        client = new Runtime(key ? { apiKey: key } : {});
+        clients.set(key ?? "", client);
+    }
+    return client;
+}
+/** Test hook: forget the cached clients. */
+export function resetClients() {
+    clients.clear();
+}

package/dist/daytona/context.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeSandbox } from "./client.js";
+/** What a sandbox's modules (process, fs, git, code interpreter) share. */
+export interface SandboxContext {
+    /** The Runtime sandbox, with its lease renewed if this call is activity
+     * that should keep it running (autoStopInterval). */
+    live(): Promise<RuntimeSandbox>;
+    /** Environment given at create (envVars) or with updateEnv. */
+    readonly env: Record<string, string>;
+    /** The language of `process.codeRun`: python, javascript or typescript. */
+    readonly language: string;
+    /** Makes /home/daytona (Daytona's home) lead to /workspace (Runtime's),
+     * once, the first time something names it. */
+    ensureHome(text: string | undefined): Promise<void>;
+}
+/** Daytona's home, and the working directory relative paths resolve from. */
+export declare const DAYTONA_HOME = "/home/daytona";
+/** Runtime's. */
+export declare const HOME = "/workspace";
+export declare const HOME_LINK = "[ -e /home/daytona ] || sudo ln -s /workspace /home/daytona";
+/** Commands without a timeout run until the sandbox ends: Runtime's longest. */
+export declare const LONGEST_MS = 86400000;
+/** Given to exec so it streams and returns the whole output, as Daytona does:
+ * an exec with no output callback returns at most 64 KiB of each stream. */
+export declare const WHOLE_OUTPUT: {
+    readonly onStdout: () => undefined;
+};
+/** A Daytona path as a Runtime one: relative paths (and `~`) resolve from the
+ * working directory, /workspace on Runtime. */
+export declare function resolvePath(path: string): string;
+/** Quotes a word for bash. */
+export declare function quote(word: string): string;

package/dist/daytona/context.js

@@ -0,0 +1,25 @@
+/** Daytona's home, and the working directory relative paths resolve from. */
+export const DAYTONA_HOME = "/home/daytona";
+/** Runtime's. */
+export const HOME = "/workspace";
+export const HOME_LINK = `[ -e ${DAYTONA_HOME} ] || sudo ln -s ${HOME} ${DAYTONA_HOME}`;
+/** Commands without a timeout run until the sandbox ends: Runtime's longest. */
+export const LONGEST_MS = 86_400_000;
+/** Given to exec so it streams and returns the whole output, as Daytona does:
+ * an exec with no output callback returns at most 64 KiB of each stream. */
+export const WHOLE_OUTPUT = { onStdout: () => undefined };
+/** A Daytona path as a Runtime one: relative paths (and `~`) resolve from the
+ * working directory, /workspace on Runtime. */
+export function resolvePath(path) {
+    if (path === "~" || path === "")
+        return HOME;
+    if (path.startsWith("~/"))
+        return `${HOME}/${path.slice(2)}`;
+    if (path.startsWith("/"))
+        return path;
+    return `${HOME}/${path.replace(/^\.\/?/, "")}`.replace(/\/+$/, "") || HOME;
+}
+/** Quotes a word for bash. */
+export function quote(word) {
+    return `'${word.replace(/'/g, `'\\''`)}'`;
+}

package/dist/daytona/daytona.d.ts

@@ -0,0 +1,185 @@
+import type { Runtime } from "../client.js";
+import { type DaytonaConfig, type WithRuntime } from "./client.js";
+import type { Image } from "./image.js";
+import { Sandbox, type Lifecycle, type SandboxState } from "./sandbox.js";
+/** Daytona's default machine: 1 vCPU, 1 GiB memory, 3 GiB disk (checked
+ * 23 September 2026). */
+export declare const DEFAULT_RESOURCES: {
+    readonly cpu: 1;
+    readonly memory: 1;
+    readonly disk: 3;
+};
+/** Daytona's default autoStopInterval, 15 minutes. */
+export declare const DEFAULT_AUTO_STOP_MINUTES = 15;
+/** Daytona's label for a sandbox's code language. */
+export declare const LANGUAGE_LABEL = "code-toolbox-language";
+export declare enum CodeLanguage {
+    PYTHON = "python",
+    TYPESCRIPT = "typescript",
+    JAVASCRIPT = "javascript"
+}
+export interface Resources {
+    cpu?: number;
+    gpu?: number;
+    gpuType?: unknown;
+    /** GiB. */
+    memory?: number;
+    /** GiB. */
+    disk?: number;
+}
+export interface VolumeMount {
+    volumeId: string;
+    mountPath: string;
+    subpath?: string;
+}
+export type CreateSandboxBaseParams = {
+    name?: string;
+    user?: string;
+    language?: CodeLanguage | string;
+    envVars?: Record<string, string>;
+    labels?: Record<string, string>;
+    public?: boolean;
+    autoStopInterval?: number;
+    autoPauseInterval?: number;
+    autoArchiveInterval?: number;
+    autoDeleteInterval?: number;
+    ttlMinutes?: number;
+    volumes?: VolumeMount[];
+    networkBlockAll?: boolean;
+    networkAllowList?: string;
+    domainAllowList?: string;
+    outboundProxyUrl?: string;
+    otelEndpointOverride?: string;
+    ephemeral?: boolean;
+    spot?: boolean;
+    linkedSandbox?: string;
+    secrets?: Record<string, string>;
+    /** Runtime-only: an explicit client, or fields for this create. */
+    withruntime?: WithRuntime;
+};
+export type CreateSandboxFromImageParams = CreateSandboxBaseParams & {
+    image: string | Image;
+    resources?: Resources;
+};
+export type CreateSandboxFromSnapshotParams = CreateSandboxBaseParams & {
+    snapshot?: string;
+    resources?: Resources;
+};
+export type ForkSandboxParams = {
+    name?: string;
+};
+export interface ListSandboxesQuery {
+    limit?: number;
+    name?: string;
+    labels?: Record<string, string>;
+    states?: SandboxState[];
+    [other: string]: unknown;
+}
+/** A Daytona snapshot: on Runtime, an image (or a snapshot made with
+ * sandbox.createSnapshot). */
+export interface Snapshot {
+    id: string;
+    name: string;
+    imageName: string;
+    state: "active" | "building" | "pending" | "error" | "removing";
+    size: number | null;
+    errorReason: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string | null;
+    general: boolean;
+    cpu: number;
+    gpu: number;
+    mem: number;
+    disk: number;
+}
+export interface PaginatedSnapshots {
+    items: Snapshot[];
+    total: number;
+    page: number;
+    totalPages: number;
+}
+export interface CreateSnapshotParams {
+    name: string;
+    image: string | Image;
+    resources?: Resources;
+    entrypoint?: string[];
+    regionId?: string;
+}
+export interface Volume {
+    id: string;
+    name: string;
+    organizationId: string;
+    state: string;
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string | null;
+    errorReason: string | null;
+}
+/** `daytona.snapshot`: Daytona snapshots as Runtime images. */
+export declare class SnapshotService {
+    #private;
+    constructor(client: Runtime);
+    list(queryOrPage?: {
+        page?: number;
+        limit?: number;
+        sourceSandboxId?: string;
+    } | number, maybeLimit?: number): Promise<PaginatedSnapshots>;
+    get(idOrName: string): Promise<Snapshot>;
+    /** Builds a Runtime image named `name` from a registry image or a Daytona
+     * Image, streaming the build log to `onLogs`. */
+    create(params: CreateSnapshotParams, options?: {
+        onLogs?: (chunk: string) => void;
+        timeout?: number;
+    }): Promise<Snapshot>;
+    delete(snapshot: Snapshot | string): Promise<void>;
+    /** Runtime images do not go inactive: returns the snapshot as it is. */
+    activate(snapshot: Snapshot | string): Promise<Snapshot>;
+}
+/** `daytona.volume`: Daytona volumes as Runtime volumes. */
+export declare class VolumeService {
+    #private;
+    constructor(client: Runtime);
+    list(): Promise<Volume[]>;
+    get(name: string, create?: boolean): Promise<Volume>;
+    create(name: string): Promise<Volume>;
+    delete(volume: Volume): Promise<void>;
+}
+/** Daytona's client. Uses RUNTIME_API_KEY (or a Runtime key in apiKey or
+ * DAYTONA_API_KEY, or the saved `npx withruntime login`). */
+export declare class Daytona implements AsyncDisposable {
+    #private;
+    readonly snapshot: SnapshotService;
+    readonly volume: VolumeService;
+    readonly secret: unknown;
+    readonly warmPool: unknown;
+    constructor(config?: DaytonaConfig);
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Creates a sandbox and waits until it runs, with Daytona's defaults: 1
+     * vCPU, 1 GiB, 3 GiB disk, pausing after 15 minutes without calls. Funding
+     * is left to Runtime: the free trial while the account has trial time, then
+     * prepaid credit, exactly as withruntime's own create. */
+    create(params?: CreateSandboxFromSnapshotParams | CreateSandboxFromImageParams, options?: {
+        timeout?: number;
+        onSnapshotCreateLogs?: (chunk: string) => void;
+    }): Promise<Sandbox>;
+    /** A sandbox by id or name. */
+    get(sandboxIdOrName: string): Promise<Sandbox>;
+    /** Live and stopped (paused) sandboxes, oldest first. Await it for the old
+     * paginated shape, `{ items, total, page, totalPages }`. */
+    list(query?: ListSandboxesQuery): AsyncIterableIterator<Sandbox> & PromiseLike<{
+        items: Sandbox[];
+        total: number;
+        page: number;
+        totalPages: number;
+    }>;
+    start(sandbox: Sandbox, timeout?: number): Promise<void>;
+    stop(sandbox: Sandbox): Promise<void>;
+    delete(sandbox: Sandbox, timeout?: number): Promise<void>;
+    /** Daytona's older name for delete. */
+    remove(sandbox: Sandbox, timeout?: number): Promise<void>;
+    fork(sandbox: Sandbox, params?: ForkSandboxParams, timeout?: number): Promise<Sandbox>;
+    _experimental_fork(sandbox: Sandbox, params?: ForkSandboxParams, timeout?: number): Promise<Sandbox>;
+}
+/** Daytona's lifecycle settings as the lease Runtime keeps. */
+export declare function lifecycleOf(params: CreateSandboxBaseParams): Lifecycle;