withruntime 0.12.0 → 0.16.0

package/dist/freestyle/index.js

@@ -31,23 +31,27 @@ export class FreestyleTransportError extends TypeError {
         return { name: this.name, message: this.message, errors: this.errors };
     }
 }
+/** A Runtime error as Freestyle's client throws it. */
+function translate(error) {
+    if (error instanceof ConnectionError)
+        return new FreestyleTransportError(error, [
+            { name: error.name, message: error.message, code: error.code },
+        ]);
+    if (!(error instanceof RuntimeError))
+        return error;
+    const translated = new FreestyleApiError(error.status, {
+        code: error.code.toUpperCase(),
+        message: error.message,
+    });
+    Object.defineProperty(translated, "cause", { value: error });
+    return translated;
+}
 async function api(call) {
     try {
         return await call();
     }
     catch (error) {
-        if (error instanceof ConnectionError)
-            throw new FreestyleTransportError(error, [
-                { name: error.name, message: error.message, code: error.code },
-            ]);
-        if (!(error instanceof RuntimeError))
-            throw error;
-        const translated = new FreestyleApiError(error.status, {
-            code: error.code.toUpperCase(),
-            message: error.message,
-        });
-        Object.defineProperty(translated, "cause", { value: error });
-        throw translated;
+        throw translate(error);
     }
 }
 const notFound = (what) => new FreestyleApiError(404, { code: "NOT_FOUND", message: `${what} not found` });
@@ -555,63 +559,295 @@ const dimension = (value, fallback, name) => {
         throw new TypeError(`${name} must be a whole number from 1 to 1000`);
     return value;
 };
-const PTY_OPEN = [
-    "exec",
-    "cols",
-    "rows",
-    "linuxUser",
-    "slug",
+const PTY_EVENTS = [
+    "reconnect",
+    "connectTimeoutMs",
+    "onStateChange",
+    "onReplayStart",
+    "onReplayEnd",
     "onData",
     "onExit",
     "onClose",
     "onError",
 ];
+const PTY_OPEN = ["exec", "cols", "rows", "linuxUser", "slug", ...PTY_EVENTS];
+/** Freestyle 0.2.18 checks its timers before anything is opened. */
+function connectionOptions(options) {
+    const { reconnect } = options;
+    if (reconnect !== undefined && reconnect !== null && typeof reconnect !== "boolean") {
+        if (typeof reconnect !== "object")
+            throw new TypeError("reconnect must be true, false or reconnect options");
+        only("Freestyle pty reconnect", reconnect, ["timeoutMs", "initialDelayMs", "maxDelayMs"]);
+    }
+    const timers = {
+        connectTimeoutMs: options.connectTimeoutMs,
+        ...(typeof reconnect === "object" && reconnect ? reconnect : {}),
+    };
+    for (const [name, value] of Object.entries(timers))
+        if (value !== undefined &&
+            (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 2_147_483_647))
+            throw new RangeError(`${name} must be a positive finite timer duration`);
+}
+const LOST = { wasClean: false, code: 1006, reason: "Connection lost" };
+/** A 4xx other than 409 and 429 will not get better by retrying. */
+const fatal = (error) => error instanceof RuntimeError &&
+    error.status >= 400 &&
+    error.status < 500 &&
+    error.status !== 409 &&
+    error.status !== 429;
+/** A stable handle across reattachments; input is never retried or buffered.
+ * Each connection is a Runtime terminal attached to the session's process. */
 export class PtySession {
-    terminal;
     sandbox;
     processId;
     sessionId;
     slug;
     created;
-    #readyState = 1;
-    constructor(terminal, sandbox, processId, sessionId, slug, created, events) {
-        this.terminal = terminal;
+    events;
+    #state = "connecting";
+    #readyState = 0;
+    #terminal;
+    #generation = 0;
+    #attempt = 0;
+    #deadline = 0;
+    #retry;
+    #stopped = false;
+    #exited = false;
+    #fatal = false;
+    #established = false;
+    #closeReported = false;
+    #dimensions;
+    #removeWake;
+    #resolveReady;
+    #rejectReady;
+    /** Resolves once the first connection is up. */
+    ready;
+    constructor(sandbox, processId, sessionId, slug, created, events, dimensions) {
         this.sandbox = sandbox;
         this.processId = processId;
         this.sessionId = sessionId;
         this.slug = slug;
         this.created = created;
-        void terminal.exited.then((exitCode) => {
-            this.#readyState = 3;
-            if (exitCode !== null)
-                events.onExit?.(exitCode);
-            events.onClose?.({ wasClean: true, code: 1000, reason: "" });
+        this.events = events;
+        this.#dimensions = dimensions;
+        this.ready = new Promise((resolve, reject) => {
+            this.#resolveReady = resolve;
+            this.#rejectReady = reject;
+        });
+        void this.ready.catch(() => { });
+        if (events.reconnect && typeof window !== "undefined" && typeof document !== "undefined") {
+            // A browser back online or back in view retries a dropped session now.
+            const wake = () => {
+                if (document.visibilityState !== "hidden" && this.#state === "closed")
+                    this.reconnect();
+            };
+            window.addEventListener("online", wake);
+            window.addEventListener("pageshow", wake);
+            document.addEventListener("visibilitychange", wake);
+            this.#removeWake = () => {
+                window.removeEventListener("online", wake);
+                window.removeEventListener("pageshow", wake);
+                document.removeEventListener("visibilitychange", wake);
+            };
+        }
+        void this.#dial();
+    }
+    #setState(state) {
+        if (this.#state === state)
+            return;
+        this.#state = state;
+        this.events.onStateChange?.(state);
+    }
+    async #dial() {
+        const generation = ++this.#generation;
+        const current = () => generation === this.#generation && !this.#stopped;
+        const limit = this.#established
+            ? Math.min(this.events.connectTimeoutMs ?? 15_000, Math.max(1, this.#deadline - Date.now()))
+            : this.events.connectTimeoutMs;
+        try {
+            // Before a reattachment, as Freestyle's preflight: a session that is
+            // gone, or credentials that no longer work, end it instead of retrying.
+            if (this.#established)
+                await this.sandbox.processes.get(this.processId);
+            if (!current())
+                return;
+            const opening = this.sandbox.terminal({
+                processId: this.processId,
+                onData: (data) => {
+                    if (current())
+                        this.events.onData?.(data);
+                },
+            });
+            let timer;
+            const terminal = await (limit === undefined
+                ? opening
+                : Promise.race([
+                    opening,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            void opening.then((late) => late.close()).catch(() => { });
+                            reject(new Error("PTY handshake timed out"));
+                        }, limit);
+                    }),
+                ]).finally(() => clearTimeout(timer)));
+            if (!current()) {
+                terminal.close();
+                return;
+            }
+            this.#bind(terminal, generation);
+        }
+        catch (error) {
+            if (!current())
+                return;
+            if (!this.#established)
+                return this.#finish(translate(error));
+            if (fatal(error)) {
+                this.#fatal = true;
+                this.#finish(translate(error));
+            }
+            else
+                this.#scheduleRetry(translate(error));
+        }
+    }
+    #bind(terminal, generation) {
+        this.#terminal = terminal;
+        this.#readyState = 1;
+        const recovering = this.#established;
+        this.#established = true;
+        this.#attempt = 0;
+        this.#deadline = 0;
+        this.#closeReported = false;
+        this.#resolveReady();
+        this.#setState("connected");
+        if (recovering && this.#dimensions)
+            terminal.resize(this.#dimensions.cols, this.#dimensions.rows);
+        void terminal.exited.then((exitCode) => this.#ended(generation, exitCode));
+    }
+    /** The connection ended: with the shell's exit code, or without one when the
+     * shell was killed by a signal or the connection dropped. */
+    #ended(generation, exitCode) {
+        const current = () => generation === this.#generation && !this.#stopped;
+        if (!current())
+            return;
+        this.#readyState = 3;
+        if (exitCode !== null)
+            return this.#exit(exitCode);
+        this.sandbox.processes.get(this.processId).then((process) => {
+            if (!current())
+                return;
+            if (process.state === "running")
+                this.#lost();
+            else
+                this.#exit(process.exitCode);
+        }, (error) => {
+            if (current())
+                this.#lost(translate(error));
         });
-        this.onError = events.onError;
     }
-    onError;
+    #retire() {
+        ++this.#generation;
+        clearTimeout(this.#retry);
+        if (this.#readyState === 1)
+            this.#readyState = 2;
+        this.#terminal?.close();
+        this.#terminal = undefined;
+    }
+    #exit(exitCode) {
+        this.#exited = true;
+        this.#retire();
+        this.#readyState = 3;
+        this.#setState("exited");
+        this.#removeWake?.();
+        if (exitCode !== null)
+            this.events.onExit?.(exitCode);
+        this.#report({ wasClean: true, code: 1000, reason: "" });
+    }
+    #lost(error) {
+        this.#retire();
+        this.#readyState = 3;
+        if (this.#stopped)
+            return;
+        if (!this.events.reconnect || this.#exited || this.#fatal)
+            return this.#finish(error);
+        this.#scheduleRetry(error);
+    }
+    #scheduleRetry(error) {
+        const options = typeof this.events.reconnect === "object" ? this.events.reconnect : null;
+        this.#deadline ||= Date.now() + (options?.timeoutMs ?? 300_000);
+        if (Date.now() >= this.#deadline)
+            return this.#finish(error ?? new Error("PTY reconnect timed out"));
+        this.#setState("reconnecting");
+        const base = Math.min((options?.initialDelayMs ?? 400) * 2 ** this.#attempt++, options?.maxDelayMs ?? 10_000);
+        const delay = Math.min(Math.round(base * (0.7 + Math.random() * 0.6)), Math.max(0, this.#deadline - Date.now()));
+        this.#retry = setTimeout(() => void this.#dial(), delay);
+    }
+    #finish(error, info = LOST) {
+        clearTimeout(this.#retry);
+        if (!this.#established)
+            this.#rejectReady(error ?? new Error("PTY connection failed"));
+        this.#setState(this.#exited ? "exited" : "closed");
+        if (this.#fatal || this.#exited || !this.#established)
+            this.#removeWake?.();
+        this.#report(info, error);
+    }
+    #report(info, error) {
+        if (this.#closeReported)
+            return;
+        this.#closeReported = true;
+        if (error)
+            this.events.onError?.(error);
+        this.events.onClose?.(info);
+    }
+    /** Retry now after a network change or a spent retry budget. Never opens a new shell. */
+    reconnect() {
+        if (this.#stopped || this.#exited || this.#fatal || !this.#established)
+            return;
+        this.#retire();
+        this.#attempt = 0;
+        this.#deadline = 0;
+        this.#closeReported = false;
+        this.#scheduleRetry();
+    }
+    /** Send input once. Throws while disconnected; uncertain keystrokes are never replayed. */
     write(data) {
-        this.terminal.write(data);
+        if (this.#state !== "connected" || !this.#terminal)
+            throw new Error("PTY is not connected");
+        this.#terminal.write(data);
     }
+    /** Remembers the size and applies it again after a reattachment. */
     resize(options) {
-        this.terminal.resize(dimension(options.cols, 80, "cols"), dimension(options.rows, 24, "rows"));
+        const cols = dimension(options.cols, 80, "cols");
+        const rows = dimension(options.rows, 24, "rows");
+        this.#dimensions = { cols, rows };
+        if (this.#state === "connected")
+            this.#terminal?.resize(cols, rows);
     }
     signal(sig) {
         if (sig !== "sigint" && sig !== "sigkill")
             throw new TypeError('signal must be "sigint" or "sigkill"');
+        if (this.#state !== "connected")
+            throw new Error("PTY is not connected");
         void (async () => {
             const process = await this.sandbox.processes.get(this.processId);
             await process.kill(sig === "sigint" ? "SIGINT" : "SIGKILL");
-        })().catch((error) => this.onError?.(error));
+        })().catch((error) => this.events.onError?.(translate(error)));
     }
-    /** 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() {
-        this.#readyState = 2;
-        this.terminal.close();
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#retire();
+        this.#removeWake?.();
+        this.#finish(undefined, { wasClean: true, code: 1000, reason: "Detached" });
     }
     get readyState() {
         return this.#readyState;
     }
+    get state() {
+        return this.#state;
+    }
 }
 export class VmPty {
     get;
@@ -633,12 +869,14 @@ export class VmPty {
             throw notFound(`PTY session ${selector} of ${linuxUser}`);
         return found;
     }
-    async connect(sandbox, found, created, events) {
-        const terminal = await sandbox.terminal({ processId: found.processId, onData: events.onData });
-        return new PtySession(terminal, sandbox, found.processId, found.info.sessionId, found.info.slug ?? undefined, created, events);
+    async connect(sandbox, found, created, events, dimensions) {
+        const session = new PtySession(sandbox, found.processId, found.info.sessionId, found.info.slug ?? undefined, created, events, dimensions);
+        await session.ready;
+        return session;
     }
     async open(options = {}) {
         only("Freestyle pty open", options, PTY_OPEN);
+        connectionOptions(options);
         const cols = dimension(options.cols, 80, "cols");
         const rows = dimension(options.rows, 24, "rows");
         const user = options.linuxUser === undefined ? "" : validateLinuxUser(options.linuxUser);
@@ -654,7 +892,7 @@ export class VmPty {
                 const existing = (await this.sessions(sandbox)).find((s) => s.info.slug === options.slug);
                 // Get-or-create: a running session with the slug is handed back, exec unrun.
                 if (existing)
-                    return this.connect(sandbox, existing, false, options);
+                    return this.connect(sandbox, existing, false, options, { cols, rows });
             }
             const shell = options.exec === undefined
                 ? user
@@ -667,18 +905,12 @@ export class VmPty {
             const started = session(process.toJSON());
             if (!started)
                 throw new Error("The started PTY session has no session line");
-            return this.connect(sandbox, started, true, options);
+            return this.connect(sandbox, started, true, options, { cols, rows });
         });
     }
     async attach(options) {
-        only("Freestyle pty attach", options, [
-            "session",
-            "linuxUser",
-            "onData",
-            "onExit",
-            "onClose",
-            "onError",
-        ]);
+        only("Freestyle pty attach", options, ["session", "linuxUser", ...PTY_EVENTS]);
+        connectionOptions(options);
         if (options.linuxUser !== undefined)
             validateLinuxUser(options.linuxUser);
         return api(async () => {
@@ -732,6 +964,106 @@ export class VmLinuxUserPty {
         return this.pty.close(session, { linuxUser: this.linuxUser });
     }
 }
+/** Terminal queries a replay may hold (device attributes, status and mode
+ * reports, window ops): answering them again would type the answers. */
+const XTERM_QUERIES = [
+    { final: "c" },
+    { prefix: ">", final: "c" },
+    { final: "n" },
+    { prefix: "?", final: "n" },
+    { final: "t" },
+    { intermediates: "$", final: "p" },
+    { prefix: "?", intermediates: "$", final: "p" },
+];
+/** 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 async function connectXterm({ pty, terminal, ...options }) {
+    only("Freestyle connectXterm", options, PTY_OPEN);
+    let muted = [];
+    let quiet;
+    let cap;
+    let replay = 0;
+    let disposed = false;
+    const unmute = () => {
+        clearTimeout(quiet);
+        clearTimeout(cap);
+        for (const handler of muted)
+            handler.dispose();
+        muted = [];
+    };
+    const endReplay = () => {
+        clearTimeout(quiet);
+        clearTimeout(cap);
+        const current = replay;
+        // Unmute once xterm has parsed everything written before this point.
+        terminal.write("", () => {
+            if (current === replay)
+                unmute();
+        });
+    };
+    const beginReplay = () => {
+        ++replay;
+        unmute();
+        terminal.write("\x1bc");
+        muted = XTERM_QUERIES.map((id) => terminal.parser.registerCsiHandler(id, () => true));
+        muted.push(terminal.parser.registerDcsHandler({ intermediates: "$", final: "q" }, () => true));
+        quiet = setTimeout(endReplay, 150);
+        cap = setTimeout(endReplay, 2_000);
+    };
+    const stopReplay = () => {
+        ++replay;
+        unmute();
+    };
+    try {
+        const session = await pty.open({
+            ...options,
+            reconnect: options.reconnect ?? true,
+            cols: options.cols ?? terminal.cols,
+            rows: options.rows ?? terminal.rows,
+            onStateChange(state) {
+                if (state === "connected")
+                    beginReplay();
+                if (state === "closed" || state === "exited")
+                    endReplay();
+                options.onStateChange?.(state);
+            },
+            onData(bytes) {
+                if (disposed)
+                    return;
+                if (muted.length) {
+                    clearTimeout(quiet);
+                    quiet = setTimeout(endReplay, 150);
+                }
+                terminal.write(bytes);
+                options.onData?.(bytes);
+            },
+        });
+        const input = terminal.onData((data) => {
+            if (session.state === "connected")
+                session.write(data);
+        });
+        const resize = terminal.onResize((size) => session.resize(size));
+        return {
+            session,
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                input.dispose();
+                resize.dispose();
+                session.detach();
+                stopReplay();
+            },
+        };
+    }
+    catch (error) {
+        stopReplay();
+        throw error;
+    }
+}
 export class VmLinuxUser {
     vm;
     linuxUser;

package/dist/identity.js

@@ -1,20 +1,27 @@
 import { RuntimeError } from "./errors.js";
 import { sandboxMarker } from "./transport.js";
+/** The guest's environment file, which holds the sandbox's current request
+ * token: the guest writes it again when the token changes (a wake on another
+ * server, a restore), while a process keeps the environment it started with. */
+async function fileCredentials() {
+    try {
+        // Loaded here, so the SDK still loads where there is no file system.
+        const { readFile } = await import("node:fs/promises");
+        const env = JSON.parse(await readFile(sandboxMarker.path, "utf8"));
+        return { url: env.RUNTIME_ID_TOKEN_REQUEST_URL, token: env.RUNTIME_ID_TOKEN_REQUEST_TOKEN };
+    }
+    catch {
+        return null;
+    }
+}
 async function requestCredentials() {
     let url = process.env.RUNTIME_ID_TOKEN_REQUEST_URL;
     let token = process.env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
     if (!url || !token) {
         // A process started before the guest wrote its environment still finds it.
-        try {
-            // Loaded here, so the SDK still loads where there is no file system.
-            const { readFile } = await import("node:fs/promises");
-            const env = JSON.parse(await readFile(sandboxMarker.path, "utf8"));
-            url = env.RUNTIME_ID_TOKEN_REQUEST_URL;
-            token = env.RUNTIME_ID_TOKEN_REQUEST_TOKEN;
-        }
-        catch {
-            return null;
-        }
+        const file = await fileCredentials();
+        url = file?.url;
+        token = file?.token;
     }
     return url && token ? { url, token } : null;
 }
@@ -37,14 +44,25 @@ export async function identityToken(input) {
             status: 0,
             message: "Identity tokens are issued only inside a Runtime sandbox (RUNTIME_ID_TOKEN_REQUEST_TOKEN is not set).",
         });
-    const url = new URL(found.url);
-    url.searchParams.set("audience", input.audience);
-    if (input.lifetimeSeconds !== undefined)
-        url.searchParams.set("lifetimeSeconds", String(input.lifetimeSeconds));
-    const response = await fetch(url, {
-        headers: { authorization: `Bearer ${found.token}` },
-        signal: input.signal ?? AbortSignal.timeout(10_000),
-    });
+    const ask = (from) => {
+        const url = new URL(from.url);
+        url.searchParams.set("audience", input.audience);
+        if (input.lifetimeSeconds !== undefined)
+            url.searchParams.set("lifetimeSeconds", String(input.lifetimeSeconds));
+        return fetch(url, {
+            headers: { authorization: `Bearer ${from.token}` },
+            signal: input.signal ?? AbortSignal.timeout(10_000),
+        });
+    };
+    let response = await ask(found);
+    // Refused for a request token that has since changed: a long-running
+    // process asks again with the current one from the guest's file (the hub's
+    // own, 16 October 2026, from its start until it was restarted).
+    if (response.status === 401 || response.status === 403) {
+        const file = await fileCredentials();
+        if (file?.url && file.token && file.token !== found.token)
+            response = await ask({ url: file.url, token: file.token });
+    }
     const body = (await response.json().catch(() => ({})));
     if (!response.ok || !body.token)
         throw new RuntimeError({

package/dist/index.d.ts

@@ -9,14 +9,14 @@ import { type CreateOptions, type RuntimeOptions } from "./client.js";
 import { Sandbox as SandboxClass } from "./sandbox.js";
 import type { CreateSandbox, KeepAliveOptions } from "./types.js";
 import type { RequestOptions } from "./transport.js";
-export { Runtime, Sandboxes, FeedbackApi, SupportApi, type CreateOptions, type RuntimeOptions, type SupportReply, } from "./client.js";
+export { Runtime, Sandboxes, FeedbackApi, SupportApi, type CreateOptions, type LifecycleOptions, type RuntimeOptions, type SupportReply, } from "./client.js";
 export { Files, Process, Processes, SandboxSessions, Terminal, type CreatedSandboxSession, type SandboxSession, } from "./sandbox.js";
 export { Tunnel, TunnelStream, type PortForward } from "./tunnel.js";
 export { Page } from "./page.js";
-export type { KeyLimits } from "./products/limits.js";
+export type { AccountLimit, KeyLimits } from "./products/limits.js";
 export type { AuditEvent, AuditPage } from "./products/audit.js";
 export type { UsageExportQuery, UsageExportRow, UsageExportPage, } from "./products/observability.js";
-export type { JobSecret, Secret, SecretRule, SecretUse, SetSecret } from "./products/secrets.js";
+export type { JobSecret, Secret, SecretRule, SecretScope, SecretUse, SetSecret, } from "./products/secrets.js";
 export { SecretPartlyStoredError } from "./products/secrets.js";
 export type { McpCatalogEntry, McpGateway, McpServerRequest } from "./products/mcp.js";
 export type { FileEvent, FileEventType, WatchHandle, WatchNotice, WatchOptions, } from "./products/watch.js";
@@ -74,4 +74,5 @@ export type { RuntimeOptions as ClientOptions };
 export { identityToken, type IdentityToken } from "./identity.js";
 export { openWalletAccount, claimWalletAccount, type OpenedWalletAccount, type WalletClaim, type WalletOptions, } from "./wallet.js";
 export type { Topup } from "./products/billing.js";
+export type { NewKey, MadeKey, ListedKey, KeyUsage } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";