@promigence/sdk 0.1.0-beta.7 → 0.1.0-beta.8

package/dist/cjs/pty.d.ts

@@ -13,6 +13,10 @@
  */
 /** Largest terminal input frame sent; the server's cap is 1 MiB per client frame. */
 export declare const PTY_INPUT_CHUNK: number;
+/** How much of what was typed a session keeps, to send again to a terminal picked up again. */
+export declare const PTY_INPUT_KEEP: number;
+/** The header a terminal is picked up again with (its resume token). */
+export declare const PTY_RESUME_HEADER = "promigence-resume";
 export interface PtySize {
     cols: number;
     rows: number;
@@ -53,6 +57,33 @@ export interface PtyConnectOpts {
     caller?: string;
     onData?: (data: Uint8Array) => void;
     onExit?: (exit: PtyExit) => void;
+    /**
+     * Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+     * terminal cannot be picked up again ([`resume`]). The session goes on over a new connection,
+     * with its callbacks, its size and what was typed meanwhile, in a NEW shell: what ran in the old
+     * one has ended. Tried for up to 30 s ([`PTY_RECONNECT_FOR_MS`]); past that the session ends with
+     * `error.code` `"service_restart"`.
+     *
+     * Default: on for a shell, off when `command` is set (reconnecting starts the command again,
+     * which may not be safe to run twice); `true` or `false` decides either way.
+     */
+    reconnect?: boolean;
+    /**
+     * Pick the same terminal up again when its connection drops or the service restarts (default
+     * on): the terminal keeps running for a short while, and the session picks up where it left off
+     * over a new connection, with what was typed meanwhile delivered once — the same shell, or the
+     * same command, still running. Where it cannot be picked up (it ended meanwhile, or too much time
+     * passed), a restart falls back to [`reconnect`]; a dropped connection ends the session, as
+     * before.
+     */
+    resume?: boolean;
+    /**
+     * Called after each reconnect: `resumed` is `true` when it is the same terminal picked up
+     * again, `false` when it is a new shell (what ran in the old one has ended).
+     */
+    onReconnected?: (how: {
+        resumed: boolean;
+    }) => void;
     /** Handshake bound (default 30 s). The session itself has none. */
     timeoutMs?: number;
     /** Maps a refused upgrade (`status`, body text, its `Retry-After`) onto the SDK's error classes. */
@@ -80,15 +111,28 @@ export declare class FrameReader {
  */
 export declare class PtySession {
     #private;
-    private readonly socket;
-    /** The id of the terminal's process inside the sandbox (`req_id`); what `pty.kill(pid)` addresses. */
+    private socket;
+    /**
+     * The id of the terminal's process inside the sandbox (`req_id`); what `pty.kill(pid)`
+     * addresses. It names this session: it stays the same after a reconnect.
+     */
     readonly pid: number;
     cols: number;
     rows: number;
     private closed;
     private readonly done;
+    /** Frames written while the session reconnects, sent once it has (at most 1 MiB). */
+    private pending;
+    /** Keystrokes written to a connection, in all, and the last of them, from `inputBase` on: what a
+     *  terminal picked up again did not take is sent again. */
+    private inputSent;
+    private inputBase;
+    private inputLog;
     /** `true` once the terminal has ended (its exit arrived, or the socket closed). */
     get ended(): boolean;
+    private flush;
+    /** Write a frame to the connection now, counting keystrokes. */
+    private writeNow;
     private send;
     /** Keystrokes / a paste. A string is sent as UTF-8. */
     write(data: string | Uint8Array): void;
@@ -105,5 +149,23 @@ export declare class PtySession {
      */
     disconnect(): void;
 }
-/** Open a terminal. Rejects with `opts.refuse(...)` if the server does not switch protocols. */
+/** The `Close` code a terminal is asked to reconnect with: 1012, "service restart" (RFC 6455's registry). */
+export declare const PTY_RECONNECT_CODE = 1012;
+/** How long a terminal tries to reconnect before it ends (`error.code` `"service_restart"`). */
+export declare const PTY_RECONNECT_FOR_MS = 30000;
+/** The first wait before a reconnect, doubled each try up to [`PTY_RECONNECT_MAX_WAIT_MS`]; each wait is jittered (50-100 %). */
+export declare const PTY_RECONNECT_FIRST_WAIT_MS = 250;
+export declare const PTY_RECONNECT_MAX_WAIT_MS = 4000;
+/** How a session that could not reconnect within [`PTY_RECONNECT_FOR_MS`] ends. */
+export declare const PTY_RESTART_EXIT: PtyExit;
+/** How a session that is not to reconnect (`reconnect` off, or a command's) ends at a 1012. */
+export declare const PTY_RESTART_CLOSED_EXIT: PtyExit;
+/**
+ * Open a terminal. Rejects with `opts.refuse(...)` if the server does not switch protocols.
+ *
+ * When its connection drops, or the service asks it to reconnect (`Close` 1012), the session goes
+ * on over a new connection: the same terminal picked up again where the service still holds it
+ * ([`PtyConnectOpts.resume`]), else, at a restart, a new shell ([`PtyConnectOpts.reconnect`]).
+ * `wait()` resolves only when the session really ends.
+ */
 export declare function connectPty(opts: PtyConnectOpts): Promise<PtySession>;

package/dist/cjs/pty.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PtySession = exports.FrameReader = exports.PTY_SECRETS_HEADER = exports.PTY_COMMAND_HEADER = exports.PTY_INPUT_CHUNK = void 0;
+exports.PTY_RESTART_CLOSED_EXIT = exports.PTY_RESTART_EXIT = exports.PTY_RECONNECT_MAX_WAIT_MS = exports.PTY_RECONNECT_FIRST_WAIT_MS = exports.PTY_RECONNECT_FOR_MS = exports.PTY_RECONNECT_CODE = exports.PtySession = exports.FrameReader = exports.PTY_SECRETS_HEADER = exports.PTY_COMMAND_HEADER = exports.PTY_RESUME_HEADER = exports.PTY_INPUT_KEEP = exports.PTY_INPUT_CHUNK = void 0;
 exports.wsAccept = wsAccept;
 exports.encodeFrame = encodeFrame;
 exports.connectPty = connectPty;
@@ -8,6 +8,8 @@ const node_crypto_1 = require("node:crypto");
 const caller_js_1 = require("./caller.js");
 const proxy_js_1 = require("./proxy.js");
 exports.PTY_INPUT_CHUNK = 64 * 1024;
+exports.PTY_INPUT_KEEP = 256 * 1024;
+exports.PTY_RESUME_HEADER = "promigence-resume";
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 exports.PTY_COMMAND_HEADER = "promigence-pty-command";
 exports.PTY_SECRETS_HEADER = "promigence-pty-secrets";
@@ -99,11 +101,17 @@ class PtySession {
     rows;
     closed = false;
     done;
+    pending;
+    resumeToken;
+    inputSent = 0;
+    inputBase = 0;
+    inputLog = Buffer.alloc(0);
     constructor(socket, open, done) {
         this.socket = socket;
         this.pid = open.pid;
         this.cols = open.cols;
         this.rows = open.rows;
+        this.resumeToken = open.resume;
         this.done = done;
         void done.then(() => { this.#ended = true; });
     }
@@ -111,10 +119,67 @@ class PtySession {
     get ended() {
         return this.#ended;
     }
-    send(opcode, payload) {
+    holdInput() {
+        this.pending ??= [];
+    }
+    rebind(socket, open) {
+        this.socket = socket;
+        this.resumeToken = open.resume;
+        this.inputSent = 0;
+        this.inputBase = 0;
+        this.inputLog = Buffer.alloc(0);
+        this.flush(open);
+    }
+    resumed(socket, open) {
+        this.socket = socket;
+        this.resumeToken = open.resume ?? this.resumeToken;
+        const took = open.input ?? this.inputSent;
+        if (took < this.inputSent) {
+            const from = Math.max(took, this.inputBase) - this.inputBase;
+            const again = this.inputLog.subarray(from);
+            this.inputSent = Math.max(took, this.inputBase);
+            for (let at = 0; at < again.length; at += exports.PTY_INPUT_CHUNK) {
+                this.writeNow(0x2, again.subarray(at, at + exports.PTY_INPUT_CHUNK));
+            }
+        }
+        this.flush(open);
+    }
+    flush(open) {
+        const queued = this.pending ?? [];
+        this.pending = undefined;
+        if (open.cols !== this.cols || open.rows !== this.rows) {
+            this.resize({ cols: this.cols, rows: this.rows });
+        }
+        for (const f of queued)
+            this.writeNow(f.opcode, f.payload);
+    }
+    writeNow(opcode, payload) {
         if (this.closed || this.socket.destroyed)
             return;
         this.socket.write(encodeFrame(opcode, payload));
+        if (opcode === 0x2) {
+            this.inputSent += payload.length;
+            this.inputLog = Buffer.concat([this.inputLog, payload]);
+            if (this.inputLog.length > exports.PTY_INPUT_KEEP) {
+                const drop = this.inputLog.length - exports.PTY_INPUT_KEEP;
+                this.inputLog = this.inputLog.subarray(drop);
+                this.inputBase += drop;
+            }
+        }
+    }
+    get hungUp() {
+        return this.closed;
+    }
+    send(opcode, payload) {
+        if (this.closed)
+            return;
+        if (this.pending) {
+            if (this.pending.reduce((n, f) => n + f.payload.length, 0) + payload.length <= 1 << 20) {
+                this.pending.push({ opcode, payload: Buffer.from(payload) });
+            }
+            return;
+        }
+        this.writeNow(opcode, payload);
     }
     write(data) {
         const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
@@ -141,17 +206,50 @@ class PtySession {
     disconnect() {
         if (this.closed)
             return;
+        this.pending = undefined;
         this.send(0x8, Buffer.from([0x03, 0xe8]));
         this.closed = true;
         this.socket.end();
     }
 }
 exports.PtySession = PtySession;
-function connectPty(opts) {
-    const url = new URL(opts.url);
+exports.PTY_RECONNECT_CODE = 1012;
+exports.PTY_RECONNECT_FOR_MS = 30_000;
+exports.PTY_RECONNECT_FIRST_WAIT_MS = 250;
+exports.PTY_RECONNECT_MAX_WAIT_MS = 4_000;
+exports.PTY_RESTART_EXIT = {
+    exitCode: null,
+    signal: null,
+    error: {
+        code: "service_restart",
+        message: "the service restarted and the terminal could not reconnect within 30 s; open it again",
+    },
+};
+exports.PTY_RESTART_CLOSED_EXIT = {
+    exitCode: null,
+    signal: null,
+    error: { code: "service_restart", message: "the service restarted and closed the terminal; open it again" },
+};
+const CLOSED_EXIT = {
+    exitCode: null,
+    signal: null,
+    error: { code: "closed", message: "the terminal connection closed without an exit record" },
+};
+class LegRefused {
+    status;
+    error;
+    restart;
+    constructor(status, error, restart = false) {
+        this.status = status;
+        this.error = error;
+        this.restart = restart;
+    }
+}
+function openLeg(opts, url, resume) {
     const key = (0, node_crypto_1.randomBytes)(16).toString("base64");
     const req = (0, proxy_js_1.requestVia)(url, {
         method: "GET",
+        agent: false,
         headers: {
             connection: "Upgrade",
             upgrade: "websocket",
@@ -160,58 +258,51 @@ function connectPty(opts) {
             authorization: `Bearer ${opts.apiKey}`,
             "user-agent": opts.userAgent,
             ...(opts.caller ? { [caller_js_1.CALLER_HEADER]: opts.caller } : {}),
-            ...(opts.command
+            ...(resume ? { [exports.PTY_RESUME_HEADER]: resume } : {}),
+            ...(opts.command && !resume
                 ? { [exports.PTY_COMMAND_HEADER]: Buffer.from(opts.command, "utf8").toString("base64") }
                 : {}),
-            ...(opts.secrets?.length
+            ...(opts.secrets?.length && !resume
                 ? {
                     [exports.PTY_SECRETS_HEADER]: Buffer.from(JSON.stringify(opts.secrets), "utf8").toString("base64"),
                 }
                 : {}),
         },
     });
-    return new Promise((resolve, reject) => {
+    let resolveEnded;
+    const ended = new Promise((r) => { resolveEnded = r; });
+    const opened = new Promise((resolve, reject) => {
         let settled = false;
-        const fail = (e) => { if (!settled) {
+        const fail = (status, body, retryAfter, restart = false) => {
+            if (settled)
+                return;
             settled = true;
-            reject(e);
-        } };
+            reject(new LegRefused(status, opts.refuse(status, body, retryAfter), restart));
+        };
         const timer = setTimeout(() => {
             req.destroy();
-            fail(opts.refuse(504, JSON.stringify({ error: { code: "timeout", message: `terminal handshake to ${url.host} took over ${opts.timeoutMs ?? 30_000} ms`, fix: "Retry; if it repeats, check the sandbox is ready (`promigence run report <run_id>`)." } })));
+            fail(504, JSON.stringify({ error: { code: "timeout", message: `terminal handshake to ${url.host} took over ${opts.timeoutMs ?? 30_000} ms`, fix: "Retry; if it repeats, check the sandbox is ready (`promigence run report <run_id>`)." } }));
         }, opts.timeoutMs ?? 30_000);
-        req.on("error", (e) => { clearTimeout(timer); fail(opts.refuse(0, JSON.stringify({ error: { code: "unreachable", message: `cannot reach ${url.host}: ${e.code ?? e.message}` } }))); });
+        req.on("error", (e) => { clearTimeout(timer); fail(0, JSON.stringify({ error: { code: "unreachable", message: `cannot reach ${url.host}: ${e.code ?? e.message}` } })); });
         req.on("response", (res) => {
             clearTimeout(timer);
             const parts = [];
             res.on("data", (d) => parts.push(d));
             const retryAfter = res.headers["retry-after"];
-            res.on("end", () => fail(opts.refuse(res.statusCode ?? 0, Buffer.concat(parts).toString("utf8"), typeof retryAfter === "string" ? retryAfter : undefined)));
+            res.on("end", () => fail(res.statusCode ?? 0, Buffer.concat(parts).toString("utf8"), typeof retryAfter === "string" ? retryAfter : undefined));
         });
         req.on("upgrade", (res, socket, head) => {
             clearTimeout(timer);
             if (res.headers["sec-websocket-accept"] !== wsAccept(key)) {
                 socket.destroy();
-                fail(opts.refuse(502, JSON.stringify({ error: { code: "internal", message: "the terminal server answered the WebSocket handshake with the wrong Sec-WebSocket-Accept" } })));
+                fail(502, JSON.stringify({ error: { code: "internal", message: "the terminal server answered the WebSocket handshake with the wrong Sec-WebSocket-Accept" } }));
                 return;
             }
             socket.setNoDelay(true);
             const reader = new FrameReader();
             let exit;
-            let session;
-            let resolveDone;
-            const done = new Promise((r) => { resolveDone = r; });
-            let finished = false;
-            const finish = () => {
-                if (finished)
-                    return;
-                finished = true;
-                const e = exit ?? { exitCode: null, signal: null, error: { code: "closed", message: "the terminal connection closed without an exit record" } };
-                opts.onExit?.(e);
-                resolveDone(e);
-                if (!settled)
-                    fail(opts.refuse(502, JSON.stringify({ error: { code: e.error?.code ?? "internal", message: e.error?.message ?? "the terminal ended before it opened" } })));
-            };
+            let closeCode;
+            let wasOpen = false;
             const onFrames = (chunk) => {
                 for (const f of reader.push(chunk)) {
                     if (f.opcode === 0x2) {
@@ -225,14 +316,18 @@ function connectPty(opts) {
                         catch {
                             continue;
                         }
-                        if (v["event"] === "open" && !session) {
-                            session = new PtySession(socket, {
+                        if (v["event"] === "open" && !wasOpen) {
+                            wasOpen = true;
+                            settled = true;
+                            resolve({
+                                socket,
                                 pid: typeof v["req_id"] === "number" ? v["req_id"] : 0,
                                 cols: Number(v["cols"] ?? 80),
                                 rows: Number(v["rows"] ?? 24),
-                            }, done);
-                            settled = true;
-                            resolve(session);
+                                ...(typeof v["resume"] === "string" ? { resume: v["resume"] } : {}),
+                                ...(v["reattached"] === true ? { reattached: true } : {}),
+                                ...(typeof v["input"] === "number" ? { input: v["input"] } : {}),
+                            });
                         }
                         else if (v["event"] === "exit") {
                             exit = {
@@ -252,17 +347,158 @@ function connectPty(opts) {
                         socket.write(encodeFrame(0xa, f.payload));
                     }
                     else if (f.opcode === 0x8) {
+                        if (closeCode === undefined)
+                            closeCode = f.payload.length >= 2 ? f.payload.readUInt16BE(0) : 1005;
                         if (!socket.destroyed)
                             socket.end(encodeFrame(0x8, f.payload.subarray(0, 2)));
                     }
                 }
             };
             socket.on("data", onFrames);
-            socket.on("close", finish);
+            socket.on("close", () => {
+                if (!wasOpen) {
+                    const restart = closeCode === exports.PTY_RECONNECT_CODE && exit === undefined;
+                    const e = restart ? exports.PTY_RESTART_CLOSED_EXIT : (exit ?? CLOSED_EXIT);
+                    fail(restart ? 503 : 502, JSON.stringify({ error: { code: e.error?.code ?? "internal", message: e.error?.message ?? "the terminal ended before it opened" } }), undefined, restart);
+                    return;
+                }
+                resolveEnded({ code: closeCode, exit });
+            });
             socket.on("error", () => { });
             if (head.length)
                 onFrames(head);
         });
         req.end();
     });
+    return { opened, ended };
+}
+function sizedUrl(url, size) {
+    const u = new URL(url);
+    u.searchParams.set("cols", String(Math.floor(size.cols)));
+    u.searchParams.set("rows", String(Math.floor(size.rows)));
+    return u;
+}
+function resumeUrl(url, size, received) {
+    const u = sizedUrl(url, size);
+    u.searchParams.set("received", String(received));
+    return u;
+}
+function worthRetrying(status) {
+    return status === 0 || status === 429 || status >= 500;
+}
+function connectPty(opts) {
+    const reconnect = opts.reconnect ?? opts.command === undefined;
+    const resumeOn = opts.resume ?? true;
+    let received = 0;
+    const legOpts = {
+        ...opts,
+        onData: (d) => {
+            received += d.length;
+            opts.onData?.(d);
+        },
+    };
+    let resolveDone;
+    const done = new Promise((r) => { resolveDone = r; });
+    let finished = false;
+    const finish = (e) => {
+        if (finished)
+            return;
+        finished = true;
+        opts.onExit?.(e);
+        resolveDone(e);
+    };
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const follow = (session, leg) => {
+        void leg.ended.then(async ({ code, exit }) => {
+            if (exit !== undefined || session.hungUp) {
+                finish(exit ?? CLOSED_EXIT);
+                return;
+            }
+            const restart = code === exports.PTY_RECONNECT_CODE;
+            const dropped = code === undefined || code === 1006;
+            let resumable = resumeOn && session.resumeToken !== undefined && (restart || dropped);
+            if (!restart && !resumable) {
+                finish(CLOSED_EXIT);
+                return;
+            }
+            if (!resumable && !reconnect) {
+                finish(exports.PTY_RESTART_CLOSED_EXIT);
+                return;
+            }
+            session.holdInput();
+            const t0 = Date.now();
+            for (let attempt = 0;; attempt++) {
+                const wait = Math.min(exports.PTY_RECONNECT_FIRST_WAIT_MS * 2 ** attempt, exports.PTY_RECONNECT_MAX_WAIT_MS) * (0.5 + Math.random() / 2);
+                if (Date.now() - t0 + wait > (opts.reconnectForMs ?? exports.PTY_RECONNECT_FOR_MS))
+                    break;
+                await sleep(wait);
+                if (session.hungUp) {
+                    finish(CLOSED_EXIT);
+                    return;
+                }
+                const next = resumable
+                    ? openLeg(legOpts, resumeUrl(opts.url, session, received), session.resumeToken)
+                    : openLeg(legOpts, sizedUrl(opts.url, session));
+                try {
+                    const o = await next.opened;
+                    if (session.hungUp) {
+                        o.socket.destroy();
+                        finish(CLOSED_EXIT);
+                        return;
+                    }
+                    if (resumable) {
+                        session.resumed(o.socket, o);
+                    }
+                    else {
+                        received = 0;
+                        session.rebind(o.socket, o);
+                    }
+                    follow(session, next);
+                    opts.onReconnected?.({ resumed: resumable });
+                    return;
+                }
+                catch (e) {
+                    const refused = e instanceof LegRefused ? e : undefined;
+                    if (resumable && refused?.status === 404) {
+                        resumable = false;
+                        if (!restart) {
+                            finish(CLOSED_EXIT);
+                            return;
+                        }
+                        if (!reconnect) {
+                            finish(exports.PTY_RESTART_CLOSED_EXIT);
+                            return;
+                        }
+                        continue;
+                    }
+                    if (refused && !worthRetrying(refused.status)) {
+                        const err = refused.error;
+                        finish({ exitCode: null, signal: null, error: { code: typeof err.code === "string" ? err.code : "internal", message: err.message } });
+                        return;
+                    }
+                }
+            }
+            finish(restart ? exports.PTY_RESTART_EXIT : CLOSED_EXIT);
+        });
+    };
+    return (async () => {
+        const t0 = Date.now();
+        for (let attempt = 0;; attempt++) {
+            const first = openLeg(legOpts, new URL(opts.url));
+            try {
+                const o = await first.opened;
+                const session = new PtySession(o.socket, o, done);
+                follow(session, first);
+                return session;
+            }
+            catch (e) {
+                const wait = Math.min(exports.PTY_RECONNECT_FIRST_WAIT_MS * 2 ** attempt, exports.PTY_RECONNECT_MAX_WAIT_MS) * (0.5 + Math.random() / 2);
+                if (e instanceof LegRefused && e.restart && reconnect && Date.now() - t0 + wait <= (opts.reconnectForMs ?? exports.PTY_RECONNECT_FOR_MS)) {
+                    await sleep(wait);
+                    continue;
+                }
+                throw e instanceof LegRefused ? e.error : e;
+            }
+        }
+    })();
 }

package/dist/cjs/sandbox.d.ts

@@ -88,6 +88,24 @@ export interface PtyCreateOpts extends Partial<PtySize> {
     cmd?: string;
     /** Handshake bound (default 30 s). */
     timeoutMs?: number;
+    /**
+     * When the connection drops, or the service is updated, the same terminal is picked up again
+     * over a new connection, where it left off: the same shell or command, still running.
+     * Default: on.
+     */
+    resume?: boolean;
+    /**
+     * When the service is updated and the terminal cannot be picked up again, the session goes on
+     * over a new connection in a NEW shell (what ran in the old one has ended), with its callbacks
+     * and its size, for up to 30 s of trying; past that it ends with `error.code`
+     * `"service_restart"`. Default: on for the login shell, off with `cmd` (reconnecting would start
+     * the command again).
+     */
+    reconnect?: boolean;
+    /** Called after each reconnect: `resumed` says whether it is the same terminal or a new shell. */
+    onReconnected?: (how: {
+        resumed: boolean;
+    }) => void;
 }
 /** The default terminal command. */
 export declare const DEFAULT_PTY_CMD = "TERM=${TERM:-xterm-256color} exec /bin/sh -l";
@@ -156,6 +174,20 @@ export interface SandboxCreateOpts extends SandboxOpts {
      * nobody), then it rejects with `TimeoutError` ("aborted by the caller's signal").
      */
     signal?: AbortSignal;
+    /**
+     * Stored secrets the sandbox receives, as environment variables: a name binds the secret to a
+     * variable of the same name, `{ name, as }` to a different one. Every command run against the
+     * sandbox gets them. As `Sandbox.fork` takes them.
+     */
+    secrets?: SecretBinding[];
+    /**
+     * The only destinations the sandbox may reach: `["github.com", "*.npmjs.org"]`. Everything
+     * else is refused, and the refusal names the host. It wins over `allowInternetAccess`. As
+     * `Sandbox.fork` takes it.
+     */
+    allowHosts?: string[];
+    /** What to favour, `start` or `compute`. As `Sandbox.fork` takes it. */
+    optimizeFor?: OptimizeFor;
 }
 /**
  * Create-or-reuse the snapshot for an image digest and return its `snapshot_id`.

package/dist/cjs/sandbox.js

@@ -327,6 +327,9 @@ class Sandbox {
                     ...(opts.secrets?.length ? { secrets: opts.secrets } : {}),
                     ...(opts.onData ? { onData: opts.onData } : {}),
                     ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                    ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                    reconnect: opts.reconnect ?? opts.cmd === undefined,
+                    ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
                     onExit: (e) => { this.terminals.delete(pid); opts.onExit?.(e); },
                 });
                 pid = session.pid;

package/dist/cjs/ssh.js

@@ -10,6 +10,7 @@ function connectSshTunnel(opts) {
     const key = (0, node_crypto_1.randomBytes)(16).toString("base64");
     const req = (0, proxy_js_1.requestVia)(url, {
         method: "GET",
+        agent: false,
         headers: {
             connection: "Upgrade",
             upgrade: "websocket",

package/dist/client.d.ts

@@ -748,6 +748,8 @@ export interface CreditOffer {
     state: string;
     credit_usd: number;
     card_bonus_usd: number;
+    /** USD charged to confirm Apple Pay, Google Pay or Amazon Pay when one is added (added to the credit). */
+    method_check_usd?: number;
     expires_at?: string | null;
     campaign?: string | null;
     message: string;
@@ -906,6 +908,16 @@ export interface BillingUsage {
         brand?: string;
         last4?: string;
     } | null;
+    /** Set when the card on file does not unlock paid limits for this organization (it already pays for another one,
+     *  it is being confirmed with a $1 charge, or that charge did not go through). */
+    card_note?: string | null;
+    /** The $1 that confirms Apple Pay, Google Pay or Amazon Pay on file: `confirming`, `paid` or `failed`. */
+    method_check?: {
+        method: string;
+        status: string;
+        amount_usd: number;
+        bonus_usd?: number | null;
+    } | null;
     suspended?: boolean;
     suspend_reason?: string | null;
     period?: {
@@ -929,6 +941,10 @@ export interface BillingUsage {
     upcoming_invoice_error?: string | null;
     [extra: string]: unknown;
 }
+/** One row of `GET /billing/history`: a credit the organization received, or a payment. */
+export type BillingHistoryEntry = M.BillingHistoryEntry;
+/** What `billing.historyPage()` lists: everything, only credits, or only payments. */
+export type BillingHistoryKind = "all" | "credits" | "payments";
 /** One metered row of `GET /me/ledger`. */
 export interface LedgerEntry {
     entry_id: string;
@@ -2033,6 +2049,16 @@ export declare class PromigenceClient {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<LedgerEntry>>;
+        /**
+         * `GET /billing/history` — the credits the organization received and its payments, newest
+         * first (one page). `kind` narrows it to `credits` or `payments`; feed `nextCursor` back as
+         * `cursor` until it is `null`. An owner's key.
+         */
+        historyPage: (opts?: {
+            kind?: BillingHistoryKind;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<BillingHistoryEntry>>;
         /** `POST /billing/checkout` — the hosted page that puts a card on file. */
         checkout: () => Promise<{
             url: string;
@@ -2433,6 +2459,18 @@ export declare class PromigenceClient {
             onData?: (data: Uint8Array) => void;
             onExit?: (exit: PtyExit) => void;
             timeoutMs?: number;
+            /** Pick the same terminal up again when its connection drops or the service is updated;
+             *  see `PtyConnectOpts.resume`. Default: on. */
+            resume?: boolean;
+            /** Reconnect in a new shell when the service is updated (a WebSocket `Close` 1012) and the
+             *  terminal cannot be picked up again; see `PtyConnectOpts.reconnect`. Default: on without
+             *  `cmd`, off with one. */
+            reconnect?: boolean;
+            /** Called after each reconnect: `resumed` says whether it is the same terminal or a new
+             *  shell. */
+            onReconnected?: (how: {
+                resumed: boolean;
+            }) => void;
         }) => Promise<PtySession>;
         /** `GET /sandboxes/:id`. */
         get: (sandboxId: string) => Promise<SandboxRecord>;