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

package/dist/pty.js

@@ -2,6 +2,8 @@ import { createHash, randomBytes } from "node:crypto";
 import { CALLER_HEADER } from "./caller.js";
 import { requestVia } from "./proxy.js";
 export const PTY_INPUT_CHUNK = 64 * 1024;
+export const PTY_INPUT_KEEP = 256 * 1024;
+export const PTY_RESUME_HEADER = "promigence-resume";
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 export const PTY_COMMAND_HEADER = "promigence-pty-command";
 export const PTY_SECRETS_HEADER = "promigence-pty-secrets";
@@ -92,11 +94,17 @@ export 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; });
     }
@@ -104,10 +112,67 @@ export 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 += PTY_INPUT_CHUNK) {
+                this.writeNow(0x2, again.subarray(at, at + 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 > PTY_INPUT_KEEP) {
+                const drop = this.inputLog.length - 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;
@@ -134,16 +199,49 @@ export class PtySession {
     disconnect() {
         if (this.closed)
             return;
+        this.pending = undefined;
         this.send(0x8, Buffer.from([0x03, 0xe8]));
         this.closed = true;
         this.socket.end();
     }
 }
-export function connectPty(opts) {
-    const url = new URL(opts.url);
+export const PTY_RECONNECT_CODE = 1012;
+export const PTY_RECONNECT_FOR_MS = 30_000;
+export const PTY_RECONNECT_FIRST_WAIT_MS = 250;
+export const PTY_RECONNECT_MAX_WAIT_MS = 4_000;
+export const 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",
+    },
+};
+export const 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 = randomBytes(16).toString("base64");
     const req = requestVia(url, {
         method: "GET",
+        agent: false,
         headers: {
             connection: "Upgrade",
             upgrade: "websocket",
@@ -152,58 +250,51 @@ export function connectPty(opts) {
             authorization: `Bearer ${opts.apiKey}`,
             "user-agent": opts.userAgent,
             ...(opts.caller ? { [CALLER_HEADER]: opts.caller } : {}),
-            ...(opts.command
+            ...(resume ? { [PTY_RESUME_HEADER]: resume } : {}),
+            ...(opts.command && !resume
                 ? { [PTY_COMMAND_HEADER]: Buffer.from(opts.command, "utf8").toString("base64") }
                 : {}),
-            ...(opts.secrets?.length
+            ...(opts.secrets?.length && !resume
                 ? {
                     [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) {
@@ -217,14 +308,18 @@ export 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 = {
@@ -244,17 +339,158 @@ export 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 === PTY_RECONNECT_CODE && exit === undefined;
+                    const e = restart ? 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;
+}
+export 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 === 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(PTY_RESTART_CLOSED_EXIT);
+                return;
+            }
+            session.holdInput();
+            const t0 = Date.now();
+            for (let attempt = 0;; attempt++) {
+                const wait = Math.min(PTY_RECONNECT_FIRST_WAIT_MS * 2 ** attempt, PTY_RECONNECT_MAX_WAIT_MS) * (0.5 + Math.random() / 2);
+                if (Date.now() - t0 + wait > (opts.reconnectForMs ?? 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(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 ? 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(PTY_RECONNECT_FIRST_WAIT_MS * 2 ** attempt, PTY_RECONNECT_MAX_WAIT_MS) * (0.5 + Math.random() / 2);
+                if (e instanceof LegRefused && e.restart && reconnect && Date.now() - t0 + wait <= (opts.reconnectForMs ?? PTY_RECONNECT_FOR_MS)) {
+                    await sleep(wait);
+                    continue;
+                }
+                throw e instanceof LegRefused ? e.error : e;
+            }
+        }
+    })();
 }

package/dist/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/sandbox.js

@@ -317,6 +317,9 @@ export 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/ssh.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.8",
   "description": "The fastest sandboxes for AI agents and code. The Promigence TypeScript SDK: snapshot an environment once, fork it as often as you need, run commands in every copy. A simple Sandbox class and the full PromigenceClient, with zero runtime dependencies.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",