@promigence/sdk 0.1.0-beta.12

package/dist/transport-worker.js

@@ -0,0 +1,466 @@
+import * as dns from "node:dns";
+import { readFileSync } from "node:fs";
+import * as http2 from "node:http2";
+import { isIP, isIPv4 } from "node:net";
+import * as tls from "node:tls";
+import * as wt from "node:worker_threads";
+import { __caGuardInternals, guardCertChain } from "./ca-guard.js";
+const { NGHTTP2_CANCEL, NGHTTP2_REFUSED_STREAM } = http2.constants;
+const MAX_UNPROCESSED_RESENDS = 3;
+const MAX_REPLAYS = 1;
+const STREAM_WINDOW = 8 * 1024 * 1024;
+const SESSION_WINDOW = 32 * 1024 * 1024;
+const DEFAULT_STREAM_LIMIT = 100;
+const MAX_STREAM_LIMIT = 1_000;
+const hrNow = () => Number(process.hrtime.bigint()) / 1e6;
+function start(init) {
+    const port = init.port;
+    const origin = new URL(init.origin);
+    const host = origin.hostname.replace(/^\[(.*)\]$/, "$1");
+    const tcpPort = origin.port ? Number(origin.port) : 443;
+    for (const h of init.distrustedForTest ?? [])
+        __caGuardInternals.addForTest(h);
+    const sessions = [];
+    const inflight = new Map();
+    let everReady = false;
+    let closed = false;
+    let draining;
+    let running = 0;
+    let idleTimer;
+    let pendingConnects = 0;
+    const post = (m, transfer) => {
+        try {
+            port.postMessage(m, transfer ?? []);
+        }
+        catch { }
+    };
+    const live = () => sessions.filter((e) => !e.retired && !e.session.closed && !e.session.destroyed);
+    const end = (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        if (pumpTimer !== undefined)
+            clearTimeout(pumpTimer);
+        if (pumpSoon !== undefined)
+            clearImmediate(pumpSoon);
+        for (const w of waiting.splice(0))
+            w.resolve(null);
+        for (const e of sessions) {
+            try {
+                e.session.close();
+            }
+            catch { }
+        }
+        for (const c of inflight.values())
+            c.cancel();
+        post({ t: "closed", reason });
+        try {
+            port.close();
+        }
+        catch { }
+    };
+    const armIdle = (ms) => {
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => { if (running === 0)
+            end("idle"); }, ms);
+    };
+    const drain = (reason) => {
+        if (closed || draining !== undefined)
+            return;
+        draining = reason;
+        post({ t: "draining", reason });
+        if (running === 0)
+            end(reason);
+    };
+    const retire = (e) => {
+        if (e.retired)
+            return;
+        e.retired = true;
+        if (!everReady)
+            return;
+        const n = live().length;
+        if (n === 0 && pendingConnects === 0)
+            drain("sessions closed");
+        else
+            post({ t: "sessions", sessions: n });
+    };
+    let context;
+    try {
+        context = tls.createSecureContext();
+    }
+    catch {
+        context = undefined;
+    }
+    const connect = (address) => new Promise((resolve) => {
+        let done = false;
+        const finish = (e) => { if (!done) {
+            done = true;
+            clearTimeout(timer);
+            resolve(e);
+        } };
+        const timer = setTimeout(() => { try {
+            socket.destroy();
+        }
+        catch { } finish(null); }, init.connectTimeoutMs);
+        const socket = tls.connect({
+            host: address,
+            port: tcpPort,
+            ...(isIP(host) !== 0 ? {} : { servername: host }),
+            ALPNProtocols: ["h2", "http/1.1"],
+            checkServerIdentity: guardCertChain,
+            ...(context === undefined ? {} : { secureContext: context }),
+        });
+        socket.once("error", () => finish(null));
+        socket.once("secureConnect", () => {
+            if (socket.alpnProtocol !== "h2") {
+                socket.destroy();
+                finish(null);
+                return;
+            }
+            let session;
+            try {
+                session = http2.connect(origin.origin, { createConnection: () => socket, settings: { enablePush: false, initialWindowSize: STREAM_WINDOW } });
+            }
+            catch {
+                socket.destroy();
+                finish(null);
+                return;
+            }
+            const entry = { session, active: 0, retired: false, goawayLast: undefined, nextFree: 0, granted: 0, index: -1, addr: address, localPort: socket.localPort ?? 0 };
+            try {
+                session.setLocalWindowSize(SESSION_WINDOW);
+            }
+            catch { }
+            session.on("error", () => retire(entry));
+            session.on("close", () => retire(entry));
+            session.on("frameError", () => { });
+            session.on("goaway", (_c, last) => {
+                entry.goawayLast = Math.min(entry.goawayLast ?? last, last);
+                retire(entry);
+            });
+            session.once("remoteSettings", () => finish(entry));
+        });
+    });
+    const lookup = () => new Promise((resolve) => {
+        if (isIP(host) !== 0) {
+            resolve([host]);
+            return;
+        }
+        const name = host.toLowerCase();
+        let named = false;
+        const v4 = [];
+        try {
+            for (const line of readFileSync(init.hostsFile || "/etc/hosts", "utf8").split("\n")) {
+                const f = line.replace(/#.*/, "").trim().split(/\s+/);
+                if (f.length < 2 || !f.slice(1).some((n) => n.toLowerCase() === name))
+                    continue;
+                named = true;
+                if (isIPv4(f[0]) && !v4.includes(f[0]))
+                    v4.push(f[0]);
+            }
+        }
+        catch { }
+        if (named) {
+            resolve(v4);
+            return;
+        }
+        try {
+            const r = new dns.Resolver({ timeout: init.lookupTimeoutMs, tries: 1 });
+            if (Array.isArray(init.servers) && init.servers.length > 0)
+                r.setServers(init.servers);
+            r.resolve4(name, (err, addrs) => resolve(!err && Array.isArray(addrs) ? addrs : []));
+        }
+        catch {
+            resolve([]);
+        }
+    });
+    const limitOf = (e) => {
+        try {
+            const m = e.session.remoteSettings?.maxConcurrentStreams;
+            return typeof m === "number" && m > 0 ? Math.min(m, MAX_STREAM_LIMIT) : DEFAULT_STREAM_LIMIT;
+        }
+        catch {
+            return DEFAULT_STREAM_LIMIT;
+        }
+    };
+    const open = async () => {
+        const addrs = await lookup();
+        if (closed)
+            return;
+        if (addrs.length === 0) {
+            end("lookup failed");
+            return;
+        }
+        const n = Math.max(1, init.sessions);
+        pendingConnects = n;
+        const tries = Array.from({ length: n }, (_, i) => connect(addrs[i % addrs.length]).then((e) => {
+            pendingConnects--;
+            if (closed) {
+                if (e)
+                    try {
+                        e.session.close();
+                    }
+                    catch { }
+                return;
+            }
+            if (e !== null) {
+                e.index = sessions.length;
+                sessions.push(e);
+                if (!everReady) {
+                    everReady = true;
+                    armIdle(init.firstUseMs);
+                }
+                post({ t: "ready", sessions: live().length, limit: limitOf(e), index: e.index, addr: e.addr, localPort: e.localPort, hr: Number(process.hrtime.bigint()) / 1e6 });
+            }
+            else if (pendingConnects === 0 && live().length === 0) {
+                if (everReady)
+                    drain("sessions closed");
+                else
+                    end("connect failed");
+            }
+        }));
+        await Promise.all(tries);
+    };
+    const gapMs = Math.max(0, init.gapUs) / 1000;
+    const waiting = [];
+    let rr = 0;
+    let rrAny = 0;
+    let pumpTimer;
+    let pumpSoon;
+    const freeNow = (l, now) => {
+        for (let i = 0; i < l.length; i++) {
+            const k = (rr + i) % l.length;
+            const e = l[k];
+            if (e.nextFree <= now) {
+                rr = k + 1;
+                return e;
+            }
+        }
+        return undefined;
+    };
+    const pump = () => {
+        pumpTimer = undefined;
+        pumpSoon = undefined;
+        while (waiting.length > 0) {
+            const l = live();
+            if (l.length === 0) {
+                for (const w of waiting.splice(0))
+                    w.resolve(null);
+                return;
+            }
+            const now = hrNow();
+            const e = freeNow(l, now);
+            if (e === undefined)
+                break;
+            e.nextFree = now + gapMs;
+            e.granted = now;
+            waiting.shift().resolve(e);
+        }
+        if (waiting.length === 0)
+            return;
+        let next = Infinity;
+        for (const e of live())
+            next = Math.min(next, e.nextFree);
+        const wait = next - hrNow();
+        if (wait > 2)
+            pumpTimer = setTimeout(pump, Math.floor(wait) - 1);
+        else
+            pumpSoon = setImmediate(pump);
+    };
+    const nextSession = (id, paced) => {
+        const l = live();
+        if (l.length === 0)
+            return null;
+        if (gapMs <= 0) {
+            let best = l[0];
+            for (const e of l)
+                if (e.active < best.active)
+                    best = e;
+            return best;
+        }
+        if (!paced) {
+            const e = l[rrAny % l.length];
+            rrAny = (rrAny % l.length) + 1;
+            return e;
+        }
+        if (waiting.length === 0) {
+            const now = hrNow();
+            const e = freeNow(l, now);
+            if (e !== undefined) {
+                e.nextFree = now + gapMs;
+                e.granted = now;
+                return e;
+            }
+        }
+        return new Promise((resolve) => {
+            waiting.push({ id, resolve });
+            if (pumpTimer === undefined && pumpSoon === undefined)
+                pump();
+        });
+    };
+    const unwait = (id) => {
+        const i = waiting.findIndex((w) => w.id === id);
+        if (i >= 0)
+            waiting.splice(i, 1)[0].resolve(null);
+    };
+    const attempt = async (req, deadline) => {
+        const paced = req.paced !== false;
+        const given = nextSession(req.id, paced);
+        const entry = given instanceof Promise ? await given : given;
+        if (entry === null || cancelled.has(req.id) || entry.retired || entry.session.closed || entry.session.destroyed) {
+            return { kind: "failed", processed: "no", code: "ERR_HTTP2_NO_SESSION", message: "no session", unsent: true };
+        }
+        return send(req, deadline, entry, gapMs > 0 && paced ? entry.granted : 0);
+    };
+    const send = (req, deadline, entry, granted) => new Promise((resolve) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            resolve({ kind: "timeout" });
+            return;
+        }
+        const headers = { ...req.headers };
+        headers[http2.sensitiveHeaders] = req.sensitive;
+        const body = req.body === undefined ? undefined : Buffer.from(req.body, "utf8");
+        let stream;
+        try {
+            stream = entry.session.request(headers, { endStream: body === undefined });
+        }
+        catch (e) {
+            retire(entry);
+            resolve({ kind: "failed", processed: "no", code: e.code ?? "ERR", message: String(e.message ?? e), unsent: true });
+            return;
+        }
+        entry.active++;
+        post({ t: "ack", id: req.id });
+        const sent = init.trace !== true ? 0 : granted > 0 ? granted : hrNow();
+        let head = 0;
+        let status = 0;
+        let resHeaders = {};
+        const chunks = [];
+        let settled = false;
+        const finish = (o) => { if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            inflight.delete(req.id);
+            resolve(o);
+        } };
+        const timer = setTimeout(() => { try {
+            stream.close(NGHTTP2_CANCEL);
+        }
+        catch { } finish({ kind: "timeout" }); }, remaining);
+        inflight.set(req.id, { cancel: () => { try {
+                stream.close(NGHTTP2_CANCEL);
+            }
+            catch { } finish({ kind: "failed", processed: "maybe", code: "ABORT", message: "cancelled" }); } });
+        stream.on("response", (h) => { resHeaders = h; status = Number(h[":status"]); if (init.trace === true)
+            head = hrNow(); });
+        stream.on("data", (c) => { chunks.push(c); });
+        stream.on("error", () => { });
+        stream.on("end", () => { if (status !== 0)
+            finish({ kind: "res", status, headers: resHeaders, body: Buffer.concat(chunks), sent, head, end: init.trace === true ? hrNow() : 0, conn: entry.index }); });
+        stream.on("close", () => {
+            entry.active = Math.max(0, entry.active - 1);
+            if (settled)
+                return;
+            const rst = stream.rstCode;
+            let processed;
+            if (status !== 0)
+                processed = "yes";
+            else if (rst === NGHTTP2_REFUSED_STREAM || stream.id === undefined)
+                processed = "no";
+            else if (entry.goawayLast !== undefined && stream.id > entry.goawayLast)
+                processed = "no";
+            else
+                processed = "maybe";
+            finish({ kind: "failed", processed, code: "ERR_HTTP2_STREAM_ERROR", message: `HTTP/2 stream closed (code ${rst ?? "?"})` });
+        });
+        if (body !== undefined)
+            stream.end(body);
+    });
+    const active = new Set();
+    const cancelled = new Set();
+    const run = async (req) => {
+        if (idleTimer !== undefined) {
+            clearTimeout(idleTimer);
+            idleTimer = undefined;
+        }
+        running++;
+        active.add(req.id);
+        const got = init.trace === true ? hrNow() : 0;
+        const deadline = Date.now() + req.timeoutMs;
+        let resends = 0;
+        let replays = 0;
+        const back = () => { post({ t: "err", id: req.id, kind: "back", resends, replays }); };
+        for (;;) {
+            if (cancelled.has(req.id))
+                break;
+            const out = await attempt(req, deadline);
+            if (cancelled.has(req.id))
+                break;
+            if (out.kind === "res") {
+                const ab = out.body.buffer.slice(out.body.byteOffset, out.body.byteOffset + out.body.byteLength);
+                post({ t: "res", id: req.id, status: out.status, headers: out.headers, body: ab, replayed: replays > 0, ...(init.trace === true ? { w: [got, out.sent, out.head, out.end], conn: out.conn } : {}) }, [ab]);
+                break;
+            }
+            if (out.kind === "timeout") {
+                post({ t: "err", id: req.id, kind: "timeout" });
+                break;
+            }
+            if (out.unsent === true) {
+                back();
+                break;
+            }
+            if (out.processed === "no") {
+                if (++resends <= MAX_UNPROCESSED_RESENDS) {
+                    if (live().length > 0)
+                        continue;
+                    back();
+                    break;
+                }
+                post({ t: "err", id: req.id, kind: "failed", processed: "no", code: out.code, message: out.message });
+                break;
+            }
+            if (out.processed === "maybe" && req.replayable && replays < MAX_REPLAYS) {
+                replays++;
+                if (live().length > 0)
+                    continue;
+                back();
+                break;
+            }
+            post({ t: "err", id: req.id, kind: "failed", processed: out.processed, code: out.code, message: out.message });
+            break;
+        }
+        active.delete(req.id);
+        cancelled.delete(req.id);
+        running--;
+        if (running > 0 || closed)
+            return;
+        if (draining !== undefined)
+            end(draining);
+        else
+            armIdle(init.idleMs);
+    };
+    port.on("message", (m) => {
+        if (closed)
+            return;
+        if (m?.t === "req")
+            void run(m);
+        else if (m?.t === "drain")
+            drain("asked");
+        else if (m?.t === "cancel" && typeof m.id === "number") {
+            if (active.has(m.id))
+                cancelled.add(m.id);
+            unwait(m.id);
+            inflight.get(m.id)?.cancel();
+        }
+        else if (m?.t === "crash-for-test")
+            setImmediate(() => { throw new Error("transport thread crash (test)"); });
+    });
+    void open();
+}
+if (!wt.isMainThread && wt.workerData && typeof wt.workerData === "object" && wt.workerData.promigenceTransport === true) {
+    start(wt.workerData);
+}

package/dist/warm.d.ts

@@ -0,0 +1 @@
+export declare function warmUp(): void;

package/dist/warm.js

@@ -0,0 +1,40 @@
+import { isIP } from "node:net";
+import { DEFAULT_API_URL } from "./core.js";
+import { PromigenceClient, isKeyedCreate, newIdempotencyKey, serverAppMs } from "./client.js";
+import { warmTransport } from "./http2.js";
+import { Sandbox } from "./sandbox.js";
+import { untraced } from "./trace.js";
+function quietly(f) {
+    try {
+        const r = f();
+        if (r instanceof Promise)
+            r.catch(() => { });
+    }
+    catch {
+    }
+}
+export function warmUp() {
+    try {
+        untraced(() => {
+            quietly(() => newIdempotencyKey());
+            quietly(() => isKeyedCreate("POST", "/runs?wait_ms=1"));
+            quietly(() => serverAppMs("app;dur=1.00"));
+            quietly(() => warmTransport());
+            quietly(() => { isIP("a.b"); isIP("a.b"); });
+            let client;
+            quietly(() => { client = new PromigenceClient({ apiKey: "warm", apiUrl: DEFAULT_API_URL }); });
+            if (client === undefined)
+                return;
+            const c = client;
+            quietly(() => c.request(undefined));
+            quietly(() => c.runs.start(undefined));
+            quietly(() => c.sandboxes.exec("sbx_0", undefined));
+            quietly(() => Sandbox.create({ client: c, tier: "small" }));
+            quietly(() => Sandbox.forkHandlesWith("", undefined, {}));
+            const make = Sandbox;
+            quietly(() => new make({ sandboxId: "sbx_0", runId: "run_0", snapshot: "", client: c }).commands.run("", null));
+        });
+    }
+    catch {
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@promigence/sdk",
+  "version": "0.1.0-beta.12",
+  "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",
+  "bugs": {
+    "email": "support@promigence.ai",
+    "url": "https://www.promigence.ai/docs"
+  },
+  "author": "Promigence AI, Inc. <support@promigence.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "promigence",
+    "sandbox",
+    "sandboxes",
+    "agents",
+    "ai-agents",
+    "code-execution",
+    "sdk",
+    "evals",
+    "snapshots",
+    "fork",
+    "ci"
+  ]
+}