withruntime 0.12.0 → 0.16.0

package/dist/client.d.ts

@@ -6,7 +6,7 @@ import { Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, type RequestOptions } from "./transport.js";
 import type { CreateSandbox, DeletedSandbox, FeedbackKind, SandboxInfo, Usage } from "./types.js";
-export type { CreateOptions } from "./machine.js";
+export type { CreateOptions, LifecycleOptions } from "./machine.js";
 export type RuntimeOptions = {
     /** Default: the RUNTIME_API_KEY environment variable. */
     apiKey?: string;

package/dist/credentials.d.ts

@@ -26,6 +26,9 @@ export declare function connectionOrigins(env: NodeJS.ProcessEnv): {
 /** Browser-issued production credentials must only reach the production API.
  * CLI and MCP share this boundary, including resumed device requests. */
 export declare function checkBrowserOrigins(origins: ReturnType<typeof connectionOrigins>): void;
+/** A wallet account's key, from its claim, saved as this machine's connection
+ * (the MCP bridge's runtime_wallet_claim; `billing claim` saves the same). */
+export declare function saveWalletConnection(env: NodeJS.ProcessEnv, key: string, orgId: string): Promise<void>;
 /** Private user storage, outside project files. Nothing reading this module
  * returns a secret to CLI output. Store names bind credentials to both origins. */
 export declare function connectionStore(env: NodeJS.ProcessEnv, directory?: string): {

package/dist/credentials.js

@@ -37,6 +37,21 @@ export function checkBrowserOrigins(origins) {
         (local(origins.auth) && local(origins.api))))
         throw new Error("Browser login supports Runtime's production endpoints or local test endpoints. Check RUNTIME_AUTH_URL and RUNTIME_API_URL.");
 }
+/** A wallet account's key, from its claim, saved as this machine's connection
+ * (the MCP bridge's runtime_wallet_claim; `billing claim` saves the same). */
+export function saveWalletConnection(env, key, orgId) {
+    const origins = connectionOrigins(env);
+    checkBrowserOrigins(origins);
+    return connectionStore(env).save({
+        version: 1,
+        apiOrigin: origins.api,
+        authOrigin: origins.auth,
+        key,
+        connectionId: "pasted",
+        orgId,
+        agentName: "Wallet agent",
+    });
+}
 function defaultDirectory(env) {
     const root = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
     if (!isAbsolute(root))

package/dist/daytona/client.d.ts

@@ -40,5 +40,9 @@ export interface DaytonaConfig {
 export declare function pickKey(explicit?: string): string | undefined;
 /** The Runtime client for this configuration. */
 export declare function clientFor(config?: DaytonaConfig): Runtime;
+/** Runtime runs in one US region: a Daytona target (the client's, or a
+ * create's own since @daytona/sdk 0.224) other than "us" is refused, and
+ * none or "" means that region. */
+export declare function refuseTarget(target: string | undefined): void;
 /** Test hook: forget the cached clients. */
 export declare function resetClients(): void;

package/dist/daytona/client.js

@@ -21,9 +21,7 @@ const clients = new Map();
 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".');
+    refuseTarget(config.target ?? env("DAYTONA_TARGET"));
     if (config.withruntime?.client)
         return config.withruntime.client;
     const key = pickKey(config.apiKey);
@@ -34,6 +32,13 @@ export function clientFor(config = {}) {
     }
     return client;
 }
+/** Runtime runs in one US region: a Daytona target (the client's, or a
+ * create's own since @daytona/sdk 0.224) other than "us" is refused, and
+ * none or "" means that region. */
+export function refuseTarget(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".');
+}
 /** Test hook: forget the cached clients. */
 export function resetClients() {
     clients.clear();

package/dist/daytona/daytona.d.ts

@@ -62,6 +62,9 @@ export type CreateSandboxBaseParams = {
     spot?: boolean;
     linkedSandbox?: string;
     secrets?: Record<string, string>;
+    /** The region for this create, over the client's target: "us" (Runtime's
+     * one region) or none; any other is refused. */
+    target?: string;
     /** Runtime-only: an explicit client, or fields for this create. */
     withruntime?: WithRuntime;
 };
@@ -183,7 +186,7 @@ export declare class Daytona implements AsyncDisposable {
     [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 included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     create(params?: CreateSandboxFromSnapshotParams | CreateSandboxFromImageParams, options?: {
         timeout?: number;
         onSnapshotCreateLogs?: (chunk: string) => void;

package/dist/daytona/daytona.js

@@ -1,4 +1,4 @@
-import { clientFor, } from "./client.js";
+import { clientFor, refuseTarget, } from "./client.js";
 import { DaytonaError, DaytonaInvalidArgumentError, DaytonaNotFoundError, DaytonaQueueTimeoutError, guard, NotSupportedError, } from "./errors.js";
 import { RuntimeError } from "../errors.js";
 import { LEASE_MAX_SECONDS } from "../compat/lease.js";
@@ -184,7 +184,7 @@ export class Daytona {
     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 included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     async create(params = {}, options = {}) {
         refuseCreate(params);
         const timeout = options.timeout;
@@ -433,6 +433,7 @@ function refuseCreate(params) {
             gpuType !== "" &&
             (!Array.isArray(gpuType) || gpuType.length > 0)))
         throw new NotSupportedError("GPUs", "Runtime runs sandboxes on CPUs; remove gpu and gpuType from resources.");
+    refuseTarget(params.target);
     if (params.volumes?.some((mount) => mount.subpath))
         throw new NotSupportedError("Mounting part of a volume (subpath)", "Mount the whole volume.");
     if (params.kvm)

package/dist/e2b/sandbox.d.ts

@@ -133,7 +133,7 @@ export declare class Sandbox {
     protected get client(): Runtime;
     /** Creates a sandbox from `template` (default "base", Runtime's stock image)
      * with E2B's default machine, 2 vCPU and 512 MiB, and waits until it runs.
-     * Funding is left to Runtime: the included usage first, then prepaid credit, exactly as withruntime's own create. */
+     * Funding is left to Runtime: the free usage first, then prepaid credit, exactly as withruntime's own create. */
     static create<S extends typeof Sandbox>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>;
     static create<S extends typeof Sandbox>(this: S, template: string, opts?: SandboxOpts): Promise<InstanceType<S>>;
     /** Connects to a sandbox by id, waking it if it is paused, as E2B does. A
@@ -148,11 +148,12 @@ export declare class Sandbox {
      * deleted. */
     static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>;
     kill(opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<boolean>;
-    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours, as E2B
-     * does; the server keeps the deadline. Runtime cannot bring an end
-     * sooner, so that is refused. A sandbox with no time limit (one on a pilot
-     * account, kept running by the server) has no end to move, and nothing
-     * changes. */
+    /** Sets the sandbox to end `timeoutMs` from now, sooner or later, up to 24
+     * hours, as E2B does: the server keeps the new time limit (an update's
+     * timeoutSeconds), and what the end does stays as created. Under a minute
+     * is a minute, Runtime's shortest limit. A sandbox with no time limit gets
+     * one; a persistent one (a pilot's, kept running by the server) has none to
+     * set, and nothing changes. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise<void>;
     setTimeout(timeoutMs: number, opts?: Pick<ConnectionOpts, "requestTimeoutMs" | "signal">): Promise<void>;
     static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>;

package/dist/e2b/sandbox.js

@@ -414,11 +414,12 @@ export class Sandbox {
             throw error;
         }
     }
-    /** Sets the sandbox to end `timeoutMs` from now, up to 24 hours, as E2B
-     * does; the server keeps the deadline. Runtime cannot bring an end
-     * sooner, so that is refused. A sandbox with no time limit (one on a pilot
-     * account, kept running by the server) has no end to move, and nothing
-     * changes. */
+    /** Sets the sandbox to end `timeoutMs` from now, sooner or later, up to 24
+     * hours, as E2B does: the server keeps the new time limit (an update's
+     * timeoutSeconds), and what the end does stays as created. Under a minute
+     * is a minute, Runtime's shortest limit. A sandbox with no time limit gets
+     * one; a persistent one (a pilot's, kept running by the server) has none to
+     * set, and nothing changes. */
     static async setTimeout(sandboxId, timeoutMs, opts = {}) {
         const client = clientFor(opts);
         const runtime = await guard("sandbox", () => client.sandboxes.get(sandboxId, request(opts)));
@@ -617,14 +618,10 @@ function secondsLater(runtime, timeoutMs) {
     return (Date.now() + timeoutMs - end) / 1000;
 }
 async function extendTo(runtime, timeoutMs, opts) {
-    checkTimeout(timeoutMs);
-    if (runtime.info.endsAt === null)
+    const seconds = timeoutSeconds(timeoutMs);
+    if (runtime.info.persistent === true)
         return;
-    const later = secondsLater(runtime, timeoutMs);
-    if (later < -1)
-        throw new NotSupportedError("Ending a sandbox sooner than its time limit (a shorter setTimeout)", "Runtime cannot bring a time limit forward. Call kill() when the work is done.");
-    if (later > 1)
-        await guard("sandbox", () => runtime.extend(Math.ceil(later), request(opts)));
+    await guard("sandbox", () => runtime.update({ timeoutSeconds: seconds }, request(opts)));
 }
 async function pause(runtime, opts) {
     if (snapshotMemory("mode", opts.mode, opts.keepMemory) === false)

package/dist/errors.d.ts

@@ -13,7 +13,7 @@ export declare const DELIBERATE: ReadonlySet<string>;
  * minutes when it has none), however many retries it allows otherwise. */
 export declare const NOTHING_RAN: ReadonlySet<string>;
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: an account without credit's eight at once and its total, an
+ * frees room: an account without credit's four at once and its total, an
  * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export declare const WAITS_FOR_ROOM: ReadonlySet<string>;

package/dist/errors.js

@@ -27,7 +27,7 @@ export const NOTHING_RAN = new Set(["guest_busy", "busy", "rate_limited"]);
  * account without credit stops. */
 const PASSING = new Set(["no_capacity", "no_credit_running_limit", "no_credit_total_limit"]);
 /** Refusals of a create that clear when a sandbox stops or pauses, or a host
- * frees room: an account without credit's eight at once and its total, an
+ * frees room: an account without credit's four at once and its total, an
  * email domain's, the account's quota and the region's capacity. `sandboxes.create` waits them out, retrying
  * with the same key and input, for up to `waitForCapacityMs`. */
 export const WAITS_FOR_ROOM = new Set([

package/dist/freestyle/index.d.ts

@@ -1,5 +1,5 @@
 import type { Runtime } from "../client.js";
-import type { Sandbox, Terminal } from "../sandbox.js";
+import type { Sandbox } from "../sandbox.js";
 import type { Snapshot } from "../snapshots.js";
 import { CompatibilityError, type ClientOptions, type Refused, type RefusedAsync } from "../compat/core.js";
 export { CompatibilityError };
@@ -341,7 +341,30 @@ export interface PtyAttachOptions {
     session: PtySessionSelector;
     linuxUser?: string;
 }
+export type PtyConnectionState = "connecting" | "connected" | "reconnecting" | "closed" | "exited";
+export interface PtyReconnectOptions {
+    /** Total time to recover one dropped connection. Default: five minutes. */
+    timeoutMs?: number;
+    /** Initial backoff, with 30% jitter. Default: 400ms. */
+    initialDelayMs?: number;
+    /** Backoff ceiling before jitter. Default: 10 seconds. */
+    maxDelayMs?: number;
+}
 export interface PtySessionEvents {
+    /** Reattach by itself after a dropped connection (Freestyle 0.2.18). */
+    reconnect?: boolean | PtyReconnectOptions;
+    /** Longest wait for each connection's terminal. Recovery waits at most 15
+     * seconds by default; a first connection, only when this is given. */
+    connectTimeoutMs?: number;
+    onStateChange?: (state: PtyConnectionState) => void;
+    /** Freestyle's exact replay boundaries. A Runtime terminal replays the
+     * session's output from its start on each connection without marking where
+     * the replay ends, as Freestyle's older guest agents do, so these never
+     * fire: the replay begins at the "connected" state. */
+    onReplayStart?: (info: {
+        exact: boolean;
+    }) => void;
+    onReplayEnd?: () => void;
     onData?: (data: Uint8Array) => void;
     onExit?: (exitCode: number) => void;
     onClose?: (info: {
@@ -353,25 +376,37 @@ export interface PtySessionEvents {
 }
 /** A session's number: FNV-1a of its process id, 31 bits, never 0. */
 export declare function sessionNumber(processId: string): number;
+/** A stable handle across reattachments; input is never retried or buffered.
+ * Each connection is a Runtime terminal attached to the session's process. */
 export declare class PtySession {
     #private;
-    private readonly terminal;
     private readonly sandbox;
     private readonly processId;
     readonly sessionId: number;
     readonly slug: string | undefined;
     readonly created: boolean;
-    constructor(terminal: Terminal, sandbox: Sandbox, processId: string, sessionId: number, slug: string | undefined, created: boolean, events: PtySessionEvents);
-    private readonly onError;
+    private readonly events;
+    /** Resolves once the first connection is up. */
+    readonly ready: Promise<void>;
+    constructor(sandbox: Sandbox, processId: string, sessionId: number, slug: string | undefined, created: boolean, events: PtySessionEvents, dimensions?: {
+        cols: number;
+        rows: number;
+    });
+    /** Retry now after a network change or a spent retry budget. Never opens a new shell. */
+    reconnect(): void;
+    /** Send input once. Throws while disconnected; uncertain keystrokes are never replayed. */
     write(data: Uint8Array | string): void;
+    /** Remembers the size and applies it again after a reattachment. */
     resize(options: {
         cols: number;
         rows: number;
     }): void;
     signal(sig: "sigint" | "sigkill"): void;
-    /** Closes the connection; the shell keeps running and attach() finds it. */
+    /** Cancels recovery and closes the connection; the shell keeps running and
+     * attach() finds it. */
     detach(): void;
     get readyState(): number;
+    get state(): PtyConnectionState;
 }
 export declare class VmPty {
     private readonly get;
@@ -414,6 +449,43 @@ export declare class VmLinuxUserPty {
         exitCode?: undefined;
     }>;
 }
+interface XtermDisposable {
+    dispose(): void;
+}
+interface XtermSequence {
+    prefix?: string;
+    intermediates?: string;
+    final: string;
+}
+/** The xterm.js surface connectXterm uses; xterm itself is not a dependency. */
+export interface XtermTerminal {
+    cols: number;
+    rows: number;
+    write(data: string | Uint8Array, callback?: () => void): void;
+    onData(listener: (data: string) => void): XtermDisposable;
+    onResize(listener: (size: {
+        cols: number;
+        rows: number;
+    }) => void): XtermDisposable;
+    parser: {
+        registerCsiHandler(id: XtermSequence, handler: () => boolean): XtermDisposable;
+        registerDcsHandler(id: XtermSequence, handler: () => boolean): XtermDisposable;
+    };
+}
+export type ConnectXtermOptions = PtyOpenOptions & PtySessionEvents & {
+    pty: VmPty | VmLinuxUserPty;
+    terminal: XtermTerminal;
+    slug: string;
+};
+/** Freestyle 0.2.18's connectXterm: xterm.js on a named session that
+ * reattaches by itself unless `reconnect: false`. Each connection replays the
+ * session's output from its start, so the screen is reset first and the
+ * replay's terminal queries go unanswered until it has been written (150ms
+ * quiet, at most 2 seconds). dispose() detaches; the shell keeps running. */
+export declare function connectXterm({ pty, terminal, ...options }: ConnectXtermOptions): Promise<{
+    session: PtySession;
+    dispose(): void;
+}>;
 export declare class VmLinuxUser {
     private readonly vm;
     private readonly linuxUser;