@promigence/sdk 0.1.0-beta.12 → 0.1.0-beta.14

package/dist/client.js

@@ -8,11 +8,11 @@ import { keychainReadCached, keychainStore, storeLabel } from "./credstore.js";
 import { CALLER_HEADER, resolveCaller, userAgentWithCaller } from "./caller.js";
 import { connectPty } from "./pty.js";
 import { connectSshTunnel } from "./ssh.js";
-import { H2Response, Http2Transport, http2Allowed, warmTls } from "./http2.js";
+import { H2Response, http2Allowed, sharedTransport, warmTls } from "./http2.js";
 import { CONTEXT_TAR_PREFIX } from "./context.js";
 import { proxyFetch, proxyFor, transportEnv } from "./proxy.js";
 import { mark, traceBegin, traceEvent } from "./trace.js";
-import { KEYED_CREATES } from "./keyed.gen.js";
+import { isKeyedCreate } from "./keyed.js";
 import { customDispatcher, longRequestDispatcher } from "./dispatcher.js";
 import { compromisedKeyCause, guardedFetchDispatcher } from "./ca-guard.js";
 import { hintArg } from "./hint.js";
@@ -262,15 +262,34 @@ export function keyOrigin(env = process.env) {
         return stored.store === "macos-keychain" ? "macOS Keychain" : stored.store === "secret-service" ? "Secret Service keyring" : "credentials file";
     return undefined;
 }
+function nonEmpty(v) {
+    return v ? v : undefined;
+}
+function withV1(u) {
+    const t = u.replace(/\/+$/, "");
+    return /^https?:\/\/[^/?#]+$/i.test(t) ? `${t}/v1` : t;
+}
+let credsLastInputs;
+let credsLast;
 function resolveCredentials(opts, env = process.env) {
-    const set = (v) => (v ? v : undefined);
-    const trim = (u) => {
-        const t = u.replace(/\/+$/, "");
-        return /^https?:\/\/[^/?#]+$/i.test(t) ? `${t}/v1` : t;
-    };
+    const set = nonEmpty;
+    const trim = withV1;
     const optKey = opts.apiKey?.trim();
     const envKey = optKey === undefined ? set(env["PROMIGENCE_API_KEY"]?.trim()) : undefined;
     const envUrl = optKey !== undefined && opts.apiUrl !== undefined ? undefined : set(env["PROMIGENCE_API_URL"]);
+    const inputs = optKey === undefined && envKey === undefined
+        ? undefined
+        : `${optKey ?? "\0"}\n${envKey ?? "\0"}\n${envUrl ?? "\0"}\n${opts.apiUrl ?? "\0"}`;
+    if (inputs !== undefined && inputs === credsLastInputs && credsLast !== undefined)
+        return { apiKey: credsLast.apiKey, apiUrl: credsLast.apiUrl };
+    const worked = resolveCredentialsFrom(opts, env, set, trim, optKey, envKey, envUrl);
+    if (inputs !== undefined && worked.refusal === undefined) {
+        credsLastInputs = inputs;
+        credsLast = { apiKey: worked.apiKey, apiUrl: worked.apiUrl };
+    }
+    return worked;
+}
+function resolveCredentialsFrom(opts, env, set, trim, optKey, envKey, envUrl) {
     const given = optKey !== undefined || envKey !== undefined;
     const { creds, store } = given
         ? { creds: {}, store: undefined }
@@ -671,28 +690,7 @@ export function errorFor(code, message, fix, extra = {}) {
             }));
     }
 }
-const KEYED_PATTERNS = KEYED_CREATES.map(([m, p]) => [m, p.split("/").filter(Boolean)]);
-const KEYED_METHODS = new Set(KEYED_CREATES.map(([m]) => m));
-export function isKeyedCreate(method, path) {
-    if (!KEYED_METHODS.has(method))
-        return false;
-    const segs = (path.split("?")[0] ?? "").split("/").filter(Boolean);
-    for (const [m, pat] of KEYED_PATTERNS) {
-        if (m !== method || pat.length !== segs.length)
-            continue;
-        let all = true;
-        for (let i = 0; i < pat.length; i++) {
-            const s = pat[i];
-            if (s.startsWith("{") ? (segs[i] ?? "").length === 0 : s !== segs[i]) {
-                all = false;
-                break;
-            }
-        }
-        if (all)
-            return true;
-    }
-    return false;
-}
+export { isKeyedCreate };
 function commandTimeoutMs(v) {
     if (v === undefined)
         return undefined;
@@ -773,6 +771,12 @@ export function serverAppMs(header) {
 function headerOf(res, name) {
     return res instanceof H2Response ? res.header(name) : res.headers.get(name);
 }
+function ownFetchDispatcherFor(timeoutMs) {
+    const guarded = customDispatcher() ? undefined : guardedFetchDispatcher();
+    if (guarded !== undefined)
+        return longRequestDispatcher(timeoutMs, guarded) ?? guarded;
+    return longRequestDispatcher(timeoutMs);
+}
 export class PromigenceClient {
     apiUrl;
     #apiKey;
@@ -804,7 +808,7 @@ export class PromigenceClient {
         this.fetchImpl = opts.fetch ?? (proxy ? proxyFetch(proxy) : globalThis.fetch);
         this.ownFetch = opts.fetch === undefined && proxy === undefined;
         this.h2 = env !== undefined && this.apiUrl.startsWith("https:") && http2Allowed(opts.http2, env)
-            ? new Http2Transport(this.fetchImpl)
+            ? sharedTransport(this.fetchImpl)
             : undefined;
         this.requestTimeoutMs = opts.requestTimeoutMs ?? 30_000;
         this.maxRetries = opts.maxRetries ?? 3;
@@ -903,11 +907,18 @@ export class PromigenceClient {
         return guardedFetchDispatcher();
     }
     dispatcherFor(timeoutMs) {
-        const guarded = this.guardDispatcher();
-        if (guarded !== undefined)
-            return longRequestDispatcher(timeoutMs, guarded) ?? guarded;
+        if (this.ownFetch)
+            return ownFetchDispatcherFor(timeoutMs);
         return longRequestDispatcher(timeoutMs);
     }
+    async againKeyed(attempt, signal) {
+        if (attempt >= this.maxRetries || signal?.aborted)
+            return false;
+        this.stats.retries++;
+        const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
+        await sleep(backoff * (0.5 + Math.random() * 0.5));
+        return true;
+    }
     async request(opts) {
         const tr = traceBegin(opts.method, opts.path);
         const url = `${this.apiUrl}${opts.path}`;
@@ -934,16 +945,8 @@ export class PromigenceClient {
         if (idempotencyKey)
             headers["idempotency-key"] = idempotencyKey;
         const replayable = opts.method === "GET" || opts.method === "DELETE" || (keyedCreate && Boolean(idempotencyKey));
-        const again = async (attempt) => {
-            if (!keyedCreate || !idempotencyKey || attempt >= this.maxRetries || opts.signal?.aborted)
-                return false;
-            this.stats.retries++;
-            const backoff = Math.min(MAX_RETRY_SLEEP_MS, this.retryBaseMs * 2 ** attempt);
-            await sleep(backoff * (0.5 + Math.random() * 0.5));
-            return true;
-        };
         const timeoutMs = opts.timeoutMs ?? this.requestTimeoutMs;
-        const dispatcher = this.dispatcherFor(timeoutMs);
+        let dispatcher;
         let resentDelete = false;
         for (let attempt = 0;; attempt++) {
             let res;
@@ -956,8 +959,7 @@ export class PromigenceClient {
                         init.signal = opts.signal;
                     if (opts.body !== undefined)
                         init.body = JSON.stringify(opts.body);
-                    if (dispatcher !== undefined)
-                        init.dispatcher = dispatcher;
+                    init.dispatcherFor = ownFetchDispatcherFor;
                     if (tr !== undefined) {
                         init.trace = tr;
                         mark(tr, "init");
@@ -973,7 +975,7 @@ export class PromigenceClient {
                         headers,
                         signal: signals.length === 1 ? signals[0] : AbortSignal.any(signals),
                         ...(opts.body === undefined ? {} : { body: JSON.stringify(opts.body) }),
-                        ...(dispatcher === undefined ? {} : { dispatcher }),
+                        ...((dispatcher ??= this.dispatcherFor(timeoutMs)) === undefined ? {} : { dispatcher }),
                     };
                     if (tr !== undefined)
                         mark(tr, "init");
@@ -991,7 +993,7 @@ export class PromigenceClient {
             }
             catch (err) {
                 const e = err;
-                if (await again(attempt))
+                if (keyedCreate && idempotencyKey && await this.againKeyed(attempt, opts.signal))
                     continue;
                 const cutOff = e?.cause?.code === "UND_ERR_HEADERS_TIMEOUT" || e?.cause?.code === "UND_ERR_BODY_TIMEOUT";
                 const timedOut = e?.name === "TimeoutError" || e?.name === "AbortError" || cutOff;
@@ -1302,316 +1304,332 @@ export class PromigenceClient {
             ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
         });
     }
-    templates = {
-        list: async (opts = {}) => {
-            const r = await this.request({
+    group_templates() {
+        return {
+            list: async (opts = {}) => {
+                const r = await this.request({
+                    method: "GET",
+                    path: "/templates",
+                    anonymous: true,
+                    ...(opts.signal ? { signal: opts.signal } : {}),
+                });
+                return r?.templates ?? [];
+            },
+            get: (name, opts = {}) => this.request({
                 method: "GET",
-                path: "/templates",
+                path: `/templates/${seg(name)}`,
                 anonymous: true,
                 ...(opts.signal ? { signal: opts.signal } : {}),
-            });
-            return r?.templates ?? [];
-        },
-        get: (name, opts = {}) => this.request({
-            method: "GET",
-            path: `/templates/${seg(name)}`,
-            anonymous: true,
-            ...(opts.signal ? { signal: opts.signal } : {}),
-        }),
-    };
+            }),
+        };
+    }
     me(opts = {}) {
         return this.request({ method: "GET", path: "/me", ...(opts.signal ? { signal: opts.signal } : {}) });
     }
     outcomes(opts = {}) {
         return this.request({ method: "GET", path: "/me/outcomes?period=month", ...(opts.signal ? { signal: opts.signal } : {}) });
     }
-    billing = {
-        usage: () => this.request({ method: "GET", path: "/billing" }),
-        ledger: async (limit = 100) => (await this.billing.ledgerPage({ limit })).items,
-        ledgerPage: async (opts = {}) => {
-            const limit = opts.limit ?? 100;
-            const r = await this.request({ method: "GET", path: `/me/ledger?${pageQuery(limit, 1000, opts.cursor)}` });
-            return pageOf(r, "entries", limit);
-        },
-        historyPage: async (opts = {}) => {
-            const limit = opts.limit ?? 50;
-            const q = new URLSearchParams(pageQuery(limit, 100, opts.cursor));
-            if (opts.kind !== undefined && opts.kind !== "all")
-                q.set("kind", opts.kind);
-            const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
-            return pageOf(r, "entries", limit);
-        },
-        checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
-        portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
-        referrals: () => this.request({ method: "GET", path: "/referrals" }),
-        applyReferral: (code) => this.request({ method: "POST", path: "/referrals/apply", body: { code } }),
-    };
-    keys = {
-        list: async (opts = {}) => {
-            const r = await this.request({ method: "GET", path: `/keys${opts.all ? "?all=1" : ""}` });
-            return r?.keys ?? [];
-        },
-        create: (opts = {}) => {
-            const body = { ...expiryFields(opts) };
-            if (opts.name !== undefined)
-                body["name"] = opts.name.slice(0, 64);
-            return this.request({ method: "POST", path: "/keys", body });
-        },
-        revoke: (keyId) => {
-            if (!keyId?.trim())
-                throw new InvalidArgumentError("keys.revoke needs a key id", "Pass a key_id from keys.list().");
-            return this.request({ method: "DELETE", path: `/keys/${encodeURIComponent(keyId)}` });
-        },
-    };
-    orgs = {
-        list: async () => {
-            const r = await this.request({ method: "GET", path: "/orgs" });
-            return r?.orgs ?? [];
-        },
-        setDefault: (org) => this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/default`, body: {} }),
-        createKey: (org, opts = {}) => {
-            const body = { ...expiryFields(opts) };
-            if (opts.name !== undefined)
-                body["name"] = opts.name.slice(0, 64);
-            if (opts.project !== undefined)
-                body["project"] = opts.project;
-            return this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/keys`, body });
-        },
-        members: async (org) => {
-            const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/members` });
-            return r?.members ?? [];
-        },
-        invites: async (org) => {
-            const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/invites` });
-            return r?.invites ?? [];
-        },
-        leave: (org) => this.request({ method: "DELETE", path: `/orgs/${orgSeg(org)}/members/me` }),
-        projects: {
-            list: async (org) => {
-                const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/projects` });
-                return r?.projects ?? [];
+    group_billing() {
+        return {
+            usage: () => this.request({ method: "GET", path: "/billing" }),
+            ledger: async (limit = 100) => (await this.billing.ledgerPage({ limit })).items,
+            ledgerPage: async (opts = {}) => {
+                const limit = opts.limit ?? 100;
+                const r = await this.request({ method: "GET", path: `/me/ledger?${pageQuery(limit, 1000, opts.cursor)}` });
+                return pageOf(r, "entries", limit);
+            },
+            historyPage: async (opts = {}) => {
+                const limit = opts.limit ?? 50;
+                const q = new URLSearchParams(pageQuery(limit, 100, opts.cursor));
+                if (opts.kind !== undefined && opts.kind !== "all")
+                    q.set("kind", opts.kind);
+                const r = await this.request({ method: "GET", path: `/billing/history?${q.toString()}` });
+                return pageOf(r, "entries", limit);
+            },
+            checkout: () => this.request({ method: "POST", path: "/billing/checkout", body: {} }),
+            portal: () => this.request({ method: "POST", path: "/billing/portal", body: {} }),
+            referrals: () => this.request({ method: "GET", path: "/referrals" }),
+            applyReferral: (code) => this.request({ method: "POST", path: "/referrals/apply", body: { code } }),
+        };
+    }
+    group_keys() {
+        return {
+            list: async (opts = {}) => {
+                const r = await this.request({ method: "GET", path: `/keys${opts.all ? "?all=1" : ""}` });
+                return r?.keys ?? [];
+            },
+            create: (opts = {}) => {
+                const body = { ...expiryFields(opts) };
+                if (opts.name !== undefined)
+                    body["name"] = opts.name.slice(0, 64);
+                return this.request({ method: "POST", path: "/keys", body });
+            },
+            revoke: (keyId) => {
+                if (!keyId?.trim())
+                    throw new InvalidArgumentError("keys.revoke needs a key id", "Pass a key_id from keys.list().");
+                return this.request({ method: "DELETE", path: `/keys/${encodeURIComponent(keyId)}` });
+            },
+        };
+    }
+    group_orgs() {
+        return {
+            list: async () => {
+                const r = await this.request({ method: "GET", path: "/orgs" });
+                return r?.orgs ?? [];
+            },
+            setDefault: (org) => this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/default`, body: {} }),
+            createKey: (org, opts = {}) => {
+                const body = { ...expiryFields(opts) };
+                if (opts.name !== undefined)
+                    body["name"] = opts.name.slice(0, 64);
+                if (opts.project !== undefined)
+                    body["project"] = opts.project;
+                return this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/keys`, body });
             },
-            create: (org, name) => this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/projects`, body: { name } }),
-            rename: (org, project, name) => this.request({
-                method: "PATCH", path: `/orgs/${orgSeg(org)}/projects/${encodeURIComponent(project)}`, body: { name },
+            members: async (org) => {
+                const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/members` });
+                return r?.members ?? [];
+            },
+            invites: async (org) => {
+                const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/invites` });
+                return r?.invites ?? [];
+            },
+            leave: (org) => this.request({ method: "DELETE", path: `/orgs/${orgSeg(org)}/members/me` }),
+            projects: {
+                list: async (org) => {
+                    const r = await this.request({ method: "GET", path: `/orgs/${orgSeg(org)}/projects` });
+                    return r?.projects ?? [];
+                },
+                create: (org, name) => this.request({ method: "POST", path: `/orgs/${orgSeg(org)}/projects`, body: { name } }),
+                rename: (org, project, name) => this.request({
+                    method: "PATCH", path: `/orgs/${orgSeg(org)}/projects/${encodeURIComponent(project)}`, body: { name },
+                }),
+            },
+        };
+    }
+    group_credits() {
+        return {
+            offer: () => this.request({ method: "GET", path: "/credits/offer" }),
+        };
+    }
+    group_github() {
+        return {
+            status: () => this.request({ method: "GET", path: "/integrations/github" }),
+            connect: () => this.request({ method: "POST", path: "/integrations/github/connect", body: {} }),
+            ticket: () => this.request({ method: "POST", path: "/integrations/github/requests", body: {} }),
+            request: (requestId) => this.request({
+                method: "GET",
+                path: `/integrations/github/requests/${encodeURIComponent(requestId)}`,
             }),
-        },
-    };
-    credits = {
-        offer: () => this.request({ method: "GET", path: "/credits/offer" }),
-    };
-    github = {
-        status: () => this.request({ method: "GET", path: "/integrations/github" }),
-        connect: () => this.request({ method: "POST", path: "/integrations/github/connect", body: {} }),
-        ticket: () => this.request({ method: "POST", path: "/integrations/github/requests", body: {} }),
-        request: (requestId) => this.request({
-            method: "GET",
-            path: `/integrations/github/requests/${encodeURIComponent(requestId)}`,
-        }),
-        disconnect: (installationId) => this.request({
-            method: "DELETE",
-            path: `/integrations/github/installations/${encodeURIComponent(String(installationId))}`,
-        }),
-        repos: (opts = {}) => {
-            const q = new URLSearchParams();
-            if (opts.page !== undefined)
-                q.set("page", String(Math.max(1, Math.floor(opts.page))));
-            if (opts.perPage !== undefined)
-                q.set("per_page", String(Math.min(100, Math.max(1, Math.floor(opts.perPage)))));
-            const qs = q.toString();
-            return this.request({ method: "GET", path: `/integrations/github/repos${qs ? `?${qs}` : ""}` });
-        },
-        untrack: (trackId) => this.request({ method: "DELETE", path: `/integrations/github/tracks/${encodeURIComponent(trackId)}` }),
-    };
-    gitlab = {
-        status: () => this.request({ method: "GET", path: "/integrations/gitlab" }),
-        connect: () => this.request({ method: "POST", path: "/integrations/gitlab/connect", body: {} }),
-        ticket: () => this.request({ method: "POST", path: "/integrations/gitlab/requests", body: {} }),
-        request: (requestId) => this.request({
-            method: "GET",
-            path: `/integrations/gitlab/requests/${encodeURIComponent(requestId)}`,
-        }),
-        disconnect: (connectionId) => this.request({
-            method: "DELETE",
-            path: `/integrations/gitlab/connections/${encodeURIComponent(connectionId)}`,
-        }),
-        repos: (opts = {}) => {
-            const q = new URLSearchParams();
-            if (opts.page !== undefined)
-                q.set("page", String(Math.max(1, Math.floor(opts.page))));
-            if (opts.perPage !== undefined)
-                q.set("per_page", String(Math.min(100, Math.max(1, Math.floor(opts.perPage)))));
-            if (opts.connectionId !== undefined)
-                q.set("connection_id", opts.connectionId);
-            const qs = q.toString();
-            return this.request({ method: "GET", path: `/integrations/gitlab/repos${qs ? `?${qs}` : ""}` });
-        },
-        untrack: (trackId) => this.request({ method: "DELETE", path: `/integrations/gitlab/tracks/${encodeURIComponent(trackId)}` }),
-    };
-    runs = {
-        start: (opts) => {
-            if (!opts.snapshot)
-                throw new InvalidArgumentError("runs.start needs a snapshot", "Pass { snapshot: 'snap_… | alias | alias@commit7' }.");
-            if (!Number.isInteger(opts.count) || opts.count < 1)
-                throw new InvalidArgumentError("runs.start needs count >= 1", "Pass { count: 1 } or more.");
-            const body = { snapshot: opts.snapshot, count: opts.count };
-            if (opts.timeoutMs !== undefined)
-                body["timeout_ms"] = opts.timeoutMs;
-            if (opts.spendCap !== undefined)
-                body["spend_cap"] = checkSpendCap(opts.spendCap);
-            if (opts.allowPartial !== undefined)
-                body["allow_partial"] = opts.allowPartial;
-            if (opts.verifyEach !== undefined)
-                body["verify_each"] = opts.verifyEach;
-            if (opts.network !== undefined)
-                body["network"] = opts.network;
-            if (opts.optimizeFor !== undefined)
-                body["optimize_for"] = opts.optimizeFor;
-            if (opts.secrets?.length)
-                body["secrets"] = opts.secrets;
-            if (opts.labels && Object.keys(opts.labels).length)
-                body["labels"] = opts.labels;
-            if (opts.exec) {
-                const e = {};
-                if (opts.exec.argv)
-                    e["argv"] = opts.exec.argv;
-                if (opts.exec.sh)
-                    e["sh"] = opts.exec.sh;
-                if (opts.exec.cwd)
-                    e["cwd"] = opts.exec.cwd;
-                if (opts.exec.env)
-                    e["env"] = opts.exec.env;
-                const t = commandTimeoutMs(opts.exec.timeoutMs);
-                if (t !== undefined)
-                    e["timeout_ms"] = t;
-                if (opts.exec.maxOutputBytes !== undefined)
-                    e["max_output_bytes"] = opts.exec.maxOutputBytes;
-                e["kill_on_exit"] = opts.exec.killOnExit ?? true;
-                body["exec"] = e;
-            }
-            if (opts.grade) {
-                if (!opts.grade.cmd)
-                    throw new InvalidArgumentError("runs.start grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
-                const g = { cmd: opts.grade.cmd };
-                if (opts.grade.holdoutCmd)
-                    g["holdout_cmd"] = opts.grade.holdoutCmd;
-                if (opts.grade.timeoutMs !== undefined)
-                    g["timeout_ms"] = opts.grade.timeoutMs;
-                if (opts.grade.score !== undefined)
-                    g["score"] = opts.grade.score;
-                body["grade"] = g;
-            }
-            if (opts.gradeOutput !== undefined)
-                body["grade_output"] = opts.gradeOutput;
-            const waitMs = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(opts.waitMs, WAIT_MS_CAP) : 0;
-            const req = { method: "POST", path: `/runs${waitQuery(waitMs)}`, body };
-            if (waitMs > 0)
-                req.timeoutMs = waitMs + this.requestTimeoutMs;
-            if (opts.idempotencyKey)
-                req.idempotencyKey = opts.idempotencyKey;
-            if (opts.signal)
-                req.signal = opts.signal;
-            return this.request(req);
-        },
-        get: (runId, opts = {}) => this.request({
-            method: "GET",
-            path: `/runs/${encodeURIComponent(runId)}${waitQuery(opts.waitMs)}`,
-            ...this.readExtras(opts),
-        }),
-        list: async (limit = 20) => (await this.runs.listPage({ limit })).items,
-        listPage: async (opts = {}) => {
-            const limit = opts.limit ?? 20;
-            const r = await this.request({ method: "GET", path: `/runs?${pageQuery(limit, 500, opts.cursor)}` });
-            return pageOf(r, "runs", limit);
-        },
-        status: (runId, opts = {}) => this.runs.get(runId, opts),
-        sandboxes: async (runId, opts = {}) => {
-            const r = await this.runs.sandboxesWithCapacity(runId, opts);
-            return r.sandboxes;
-        },
-        sandboxesWithCapacity: async (runId, opts = {}) => {
-            const r = await this.request({
+            disconnect: (installationId) => this.request({
+                method: "DELETE",
+                path: `/integrations/github/installations/${encodeURIComponent(String(installationId))}`,
+            }),
+            repos: (opts = {}) => {
+                const q = new URLSearchParams();
+                if (opts.page !== undefined)
+                    q.set("page", String(Math.max(1, Math.floor(opts.page))));
+                if (opts.perPage !== undefined)
+                    q.set("per_page", String(Math.min(100, Math.max(1, Math.floor(opts.perPage)))));
+                const qs = q.toString();
+                return this.request({ method: "GET", path: `/integrations/github/repos${qs ? `?${qs}` : ""}` });
+            },
+            untrack: (trackId) => this.request({ method: "DELETE", path: `/integrations/github/tracks/${encodeURIComponent(trackId)}` }),
+        };
+    }
+    group_gitlab() {
+        return {
+            status: () => this.request({ method: "GET", path: "/integrations/gitlab" }),
+            connect: () => this.request({ method: "POST", path: "/integrations/gitlab/connect", body: {} }),
+            ticket: () => this.request({ method: "POST", path: "/integrations/gitlab/requests", body: {} }),
+            request: (requestId) => this.request({
+                method: "GET",
+                path: `/integrations/gitlab/requests/${encodeURIComponent(requestId)}`,
+            }),
+            disconnect: (connectionId) => this.request({
+                method: "DELETE",
+                path: `/integrations/gitlab/connections/${encodeURIComponent(connectionId)}`,
+            }),
+            repos: (opts = {}) => {
+                const q = new URLSearchParams();
+                if (opts.page !== undefined)
+                    q.set("page", String(Math.max(1, Math.floor(opts.page))));
+                if (opts.perPage !== undefined)
+                    q.set("per_page", String(Math.min(100, Math.max(1, Math.floor(opts.perPage)))));
+                if (opts.connectionId !== undefined)
+                    q.set("connection_id", opts.connectionId);
+                const qs = q.toString();
+                return this.request({ method: "GET", path: `/integrations/gitlab/repos${qs ? `?${qs}` : ""}` });
+            },
+            untrack: (trackId) => this.request({ method: "DELETE", path: `/integrations/gitlab/tracks/${encodeURIComponent(trackId)}` }),
+        };
+    }
+    group_runs() {
+        return {
+            start: (opts) => {
+                if (!opts.snapshot)
+                    throw new InvalidArgumentError("runs.start needs a snapshot", "Pass { snapshot: 'snap_… | alias | alias@commit7' }.");
+                if (!Number.isInteger(opts.count) || opts.count < 1)
+                    throw new InvalidArgumentError("runs.start needs count >= 1", "Pass { count: 1 } or more.");
+                const body = { snapshot: opts.snapshot, count: opts.count };
+                if (opts.timeoutMs !== undefined)
+                    body["timeout_ms"] = opts.timeoutMs;
+                if (opts.spendCap !== undefined)
+                    body["spend_cap"] = checkSpendCap(opts.spendCap);
+                if (opts.allowPartial !== undefined)
+                    body["allow_partial"] = opts.allowPartial;
+                if (opts.verifyEach !== undefined)
+                    body["verify_each"] = opts.verifyEach;
+                if (opts.network !== undefined)
+                    body["network"] = opts.network;
+                if (opts.optimizeFor !== undefined)
+                    body["optimize_for"] = opts.optimizeFor;
+                if (opts.secrets?.length)
+                    body["secrets"] = opts.secrets;
+                if (opts.labels && Object.keys(opts.labels).length)
+                    body["labels"] = opts.labels;
+                if (opts.exec) {
+                    const e = {};
+                    if (opts.exec.argv)
+                        e["argv"] = opts.exec.argv;
+                    if (opts.exec.sh)
+                        e["sh"] = opts.exec.sh;
+                    if (opts.exec.cwd)
+                        e["cwd"] = opts.exec.cwd;
+                    if (opts.exec.env)
+                        e["env"] = opts.exec.env;
+                    const t = commandTimeoutMs(opts.exec.timeoutMs);
+                    if (t !== undefined)
+                        e["timeout_ms"] = t;
+                    if (opts.exec.maxOutputBytes !== undefined)
+                        e["max_output_bytes"] = opts.exec.maxOutputBytes;
+                    e["kill_on_exit"] = opts.exec.killOnExit ?? true;
+                    body["exec"] = e;
+                }
+                if (opts.grade) {
+                    if (!opts.grade.cmd)
+                        throw new InvalidArgumentError("runs.start grade needs a cmd", "Pass { grade: { cmd: 'pytest -q tests/' } }.");
+                    const g = { cmd: opts.grade.cmd };
+                    if (opts.grade.holdoutCmd)
+                        g["holdout_cmd"] = opts.grade.holdoutCmd;
+                    if (opts.grade.timeoutMs !== undefined)
+                        g["timeout_ms"] = opts.grade.timeoutMs;
+                    if (opts.grade.score !== undefined)
+                        g["score"] = opts.grade.score;
+                    body["grade"] = g;
+                }
+                if (opts.gradeOutput !== undefined)
+                    body["grade_output"] = opts.gradeOutput;
+                const waitMs = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(opts.waitMs, WAIT_MS_CAP) : 0;
+                const req = { method: "POST", path: `/runs${waitQuery(waitMs)}`, body };
+                if (waitMs > 0)
+                    req.timeoutMs = waitMs + this.requestTimeoutMs;
+                if (opts.idempotencyKey)
+                    req.idempotencyKey = opts.idempotencyKey;
+                if (opts.signal)
+                    req.signal = opts.signal;
+                return this.request(req);
+            },
+            get: (runId, opts = {}) => this.request({
                 method: "GET",
-                path: `/runs/${encodeURIComponent(runId)}/sandboxes${waitQuery(opts.waitMs)}`,
+                path: `/runs/${encodeURIComponent(runId)}${waitQuery(opts.waitMs)}`,
                 ...this.readExtras(opts),
-            });
-            if (Array.isArray(r))
-                return { sandboxes: r };
-            const sandboxes = r?.sandboxes ?? [];
-            return r?.capacity ? { sandboxes, capacity: r.capacity } : { sandboxes };
-        },
-        report: (runId) => this.request({ method: "GET", path: `/runs/${encodeURIComponent(runId)}/report` }),
-        cancel: (runId) => this.request({ method: "POST", path: `/runs/${encodeURIComponent(runId)}/cancel`, body: {} }),
-        kill: (runId) => this.request({ method: "DELETE", path: `/runs/${encodeURIComponent(runId)}` }),
-        quote: (opts) => {
-            if (!opts.snapshot)
-                throw new InvalidArgumentError("runs.quote needs a snapshot", "Pass { snapshot: 'snap_… | alias | alias@commit7' }.");
-            if (!Number.isInteger(opts.count) || opts.count < 1)
-                throw new InvalidArgumentError("runs.quote needs count >= 1", "Pass { count: 1 } or more.");
-            const body = { snapshot: opts.snapshot, count: opts.count };
-            if (opts.timeoutMs !== undefined)
-                body["timeout_ms"] = opts.timeoutMs;
-            if (opts.tier !== undefined)
-                body["tier"] = opts.tier;
-            if (opts.spendCap !== undefined)
-                body["spend_cap"] = checkSpendCap(opts.spendCap);
-            return this.request({ method: "POST", path: "/runs/quote", body });
-        },
-        replay: (runId, sandboxIds, opts = {}) => this.request({
-            method: "POST",
-            path: `/runs/${encodeURIComponent(runId)}/replay`,
-            body: {
-                ...(sandboxIds?.length ? { sandbox_ids: sandboxIds } : {}),
-                ...(opts.env && Object.keys(opts.env).length ? { env: opts.env } : {}),
+            }),
+            list: async (limit = 20) => (await this.runs.listPage({ limit })).items,
+            listPage: async (opts = {}) => {
+                const limit = opts.limit ?? 20;
+                const r = await this.request({ method: "GET", path: `/runs?${pageQuery(limit, 500, opts.cursor)}` });
+                return pageOf(r, "runs", limit);
             },
-        }),
-        captures: (runId) => this.request({
-            method: "GET",
-            path: `/runs/${encodeURIComponent(runId)}/captures`,
-        }),
-        open: (runId, opts = {}) => {
-            const body = {};
-            if (opts.sandboxId !== undefined)
-                body["sandbox_id"] = opts.sandboxId;
-            if (opts.spendCap !== undefined)
-                body["spend_cap"] = opts.spendCap;
-            if (opts.timeoutMs !== undefined)
-                body["timeout_ms"] = opts.timeoutMs;
-            return this.request({
+            status: (runId, opts = {}) => this.runs.get(runId, opts),
+            sandboxes: async (runId, opts = {}) => {
+                const r = await this.runs.sandboxesWithCapacity(runId, opts);
+                return r.sandboxes;
+            },
+            sandboxesWithCapacity: async (runId, opts = {}) => {
+                const r = await this.request({
+                    method: "GET",
+                    path: `/runs/${encodeURIComponent(runId)}/sandboxes${waitQuery(opts.waitMs)}`,
+                    ...this.readExtras(opts),
+                });
+                if (Array.isArray(r))
+                    return { sandboxes: r };
+                const sandboxes = r?.sandboxes ?? [];
+                return r?.capacity ? { sandboxes, capacity: r.capacity } : { sandboxes };
+            },
+            report: (runId) => this.request({ method: "GET", path: `/runs/${encodeURIComponent(runId)}/report` }),
+            cancel: (runId) => this.request({ method: "POST", path: `/runs/${encodeURIComponent(runId)}/cancel`, body: {} }),
+            kill: (runId) => this.request({ method: "DELETE", path: `/runs/${encodeURIComponent(runId)}` }),
+            quote: (opts) => {
+                if (!opts.snapshot)
+                    throw new InvalidArgumentError("runs.quote needs a snapshot", "Pass { snapshot: 'snap_… | alias | alias@commit7' }.");
+                if (!Number.isInteger(opts.count) || opts.count < 1)
+                    throw new InvalidArgumentError("runs.quote needs count >= 1", "Pass { count: 1 } or more.");
+                const body = { snapshot: opts.snapshot, count: opts.count };
+                if (opts.timeoutMs !== undefined)
+                    body["timeout_ms"] = opts.timeoutMs;
+                if (opts.tier !== undefined)
+                    body["tier"] = opts.tier;
+                if (opts.spendCap !== undefined)
+                    body["spend_cap"] = checkSpendCap(opts.spendCap);
+                return this.request({ method: "POST", path: "/runs/quote", body });
+            },
+            replay: (runId, sandboxIds, opts = {}) => this.request({
                 method: "POST",
-                path: `/runs/${encodeURIComponent(runId)}/open`,
-                body,
-            });
-        },
-        waitReady: async (runId, opts = {}) => {
-            const seen = new Set();
-            const progress = opts.onReady !== undefined || opts.onCapacity !== undefined;
-            const r = await this.waitLoop(opts, progress ? PROGRESS_POLL_MS : LONG_POLL_MS, [], async (read) => {
-                const { sandboxes, capacity } = await this.runs.sandboxesWithCapacity(runId, read);
-                if (capacity)
-                    opts.onCapacity?.(capacity);
-                return sandboxes;
-            }, (sandboxes) => {
-                for (const s of sandboxes) {
-                    if (!isWaiting(s.state) && !seen.has(s.sandbox_id)) {
-                        seen.add(s.sandbox_id);
-                        opts.onReady?.(s);
+                path: `/runs/${encodeURIComponent(runId)}/replay`,
+                body: {
+                    ...(sandboxIds?.length ? { sandbox_ids: sandboxIds } : {}),
+                    ...(opts.env && Object.keys(opts.env).length ? { env: opts.env } : {}),
+                },
+            }),
+            captures: (runId) => this.request({
+                method: "GET",
+                path: `/runs/${encodeURIComponent(runId)}/captures`,
+            }),
+            open: (runId, opts = {}) => {
+                const body = {};
+                if (opts.sandboxId !== undefined)
+                    body["sandbox_id"] = opts.sandboxId;
+                if (opts.spendCap !== undefined)
+                    body["spend_cap"] = opts.spendCap;
+                if (opts.timeoutMs !== undefined)
+                    body["timeout_ms"] = opts.timeoutMs;
+                return this.request({
+                    method: "POST",
+                    path: `/runs/${encodeURIComponent(runId)}/open`,
+                    body,
+                });
+            },
+            waitReady: async (runId, opts = {}) => {
+                const seen = new Set();
+                const progress = opts.onReady !== undefined || opts.onCapacity !== undefined;
+                const r = await this.waitLoop(opts, progress ? PROGRESS_POLL_MS : LONG_POLL_MS, [], async (read) => {
+                    const { sandboxes, capacity } = await this.runs.sandboxesWithCapacity(runId, read);
+                    if (capacity)
+                        opts.onCapacity?.(capacity);
+                    return sandboxes;
+                }, (sandboxes) => {
+                    for (const s of sandboxes) {
+                        if (!isWaiting(s.state) && !seen.has(s.sandbox_id)) {
+                            seen.add(s.sandbox_id);
+                            opts.onReady?.(s);
+                        }
                     }
-                }
-                return sandboxes.length > 0 && sandboxes.every((s) => !isWaiting(s.state));
-            });
-            return { sandboxes: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
-        },
-        waitDone: async (runId, opts = {}) => {
-            const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => {
-                const terminal = run.state === "completed" || run.state === "cap_killed" || run.state === "aborted";
-                const allDone = Array.isArray(run.sandboxes) && run.sandboxes.length > 0 &&
-                    run.sandboxes.every((s) => s.state === "ended" || s.command_outcome != null);
-                return terminal || allDone;
-            });
-            return { run: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
-        },
-    };
+                    return sandboxes.length > 0 && sandboxes.every((s) => !isWaiting(s.state));
+                });
+                return { sandboxes: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
+            },
+            waitDone: async (runId, opts = {}) => {
+                const r = await this.waitLoop(opts, LONG_POLL_MS, { run_id: runId, state: "running" }, (read) => this.runs.get(runId, read), (run) => {
+                    const terminal = run.state === "completed" || run.state === "cap_killed" || run.state === "aborted";
+                    const allDone = Array.isArray(run.sandboxes) && run.sandboxes.length > 0 &&
+                        run.sandboxes.every((s) => s.state === "ended" || s.command_outcome != null);
+                    return terminal || allDone;
+                });
+                return { run: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
+            },
+        };
+    }
     async waitLoop(opts, maxWaitMs, empty, read, done) {
         const bound = opts.waitTimeoutMs ?? WAIT_TIMEOUT_MS;
         const started = Date.now();
@@ -1665,720 +1683,722 @@ export class PromigenceClient {
             await sleep(Math.min(opts.pollMs ?? pollInterval(i), Math.max(1, bound - elapsed)));
         }
     }
-    sandboxes = {
-        exec: (sandboxId, opts) => {
-            if (!opts.argv?.length && !opts.sh) {
-                throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['bun','typecheck'] } or { sh: 'bun typecheck' }.");
-            }
-            const body = {};
-            if (opts.argv?.length)
-                body["argv"] = opts.argv;
-            if (opts.sh)
-                body["sh"] = opts.sh;
-            if (opts.cwd)
-                body["cwd"] = opts.cwd;
-            if (opts.env)
-                body["env"] = opts.env;
-            if (opts.user)
-                body["user"] = opts.user;
-            if (opts.secrets?.length)
-                body["secrets"] = opts.secrets;
-            if (opts.terminal)
-                body["terminal"] = true;
-            if (opts.killOnExit !== undefined)
-                body["kill_on_exit"] = opts.killOnExit;
-            const timeoutMs = commandTimeoutMs(opts.timeoutMs) ?? 15 * 60_000;
-            body["timeout_ms"] = timeoutMs;
-            body["max_output_bytes"] = opts.maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT;
-            if (opts.encoding === "base64")
-                body["encoding"] = "base64";
-            const req = {
-                method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
-                body,
-                timeoutMs: timeoutMs + 30_000,
-            };
-            if (opts.idempotencyKey)
-                req.idempotencyKey = opts.idempotencyKey;
-            if (opts.signal)
-                req.signal = opts.signal;
-            return this.request(req);
-        },
-        execStream: async (sandboxId, opts, on = {}) => {
-            if (!opts.argv?.length && !opts.sh) {
-                throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['bun','typecheck'] } or { sh: 'bun typecheck' }.");
-            }
-            if (opts.idempotencyKey) {
-                throw new InvalidArgumentError("a streamed exec cannot take an idempotencyKey (its output cannot be replayed)", "Use sandboxes.exec (buffered) or sandboxes.execBackground with the key, or stream without one.");
-            }
-            const body = {};
-            if (opts.argv?.length)
-                body["argv"] = opts.argv;
-            if (opts.sh)
-                body["sh"] = opts.sh;
-            if (opts.cwd)
-                body["cwd"] = opts.cwd;
-            if (opts.env)
-                body["env"] = opts.env;
-            if (opts.user)
-                body["user"] = opts.user;
-            if (opts.secrets?.length)
-                body["secrets"] = opts.secrets;
-            if (opts.terminal)
-                body["terminal"] = true;
-            if (opts.killOnExit !== undefined)
-                body["kill_on_exit"] = opts.killOnExit;
-            body["timeout_ms"] = commandTimeoutMs(opts.timeoutMs) ?? 15 * 60_000;
-            body["max_output_bytes"] = opts.maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT;
-            const url = `${this.apiUrl}/sandboxes/${encodeURIComponent(sandboxId)}/execs`;
-            const idle = new AbortController();
-            let silent = false;
-            let reader;
-            let timer;
-            const arm = () => {
-                clearTimeout(timer);
-                timer = setTimeout(() => {
-                    silent = true;
-                    idle.abort();
-                    reader?.cancel().catch(() => { });
-                }, STREAM_IDLE_MS);
-            };
-            let stream;
-            const bearer = `Bearer ${this.requireKey()}`;
-            const dispatcher = this.guardDispatcher();
-            for (let attempt = 0; stream === undefined; attempt++) {
-                let r;
-                this.stats.requests++;
-                arm();
-                try {
-                    r = await this.fetchImpl(url, {
-                        method: "POST",
-                        headers: {
-                            accept: "text/event-stream",
-                            "content-type": "application/json",
-                            "user-agent": this.userAgent,
-                            authorization: bearer,
-                            ...(this.caller ? { [CALLER_HEADER]: this.caller } : {}),
-                        },
-                        body: JSON.stringify(body),
-                        signal: opts.signal ? AbortSignal.any([opts.signal, idle.signal]) : idle.signal,
-                        ...(dispatcher === undefined ? {} : { dispatcher }),
-                    });
-                }
-                catch (err) {
-                    clearTimeout(timer);
-                    const e = err;
-                    const why = silent ? `no answer in ${STREAM_IDLE_MS / 1000} s` : transportDetail(e);
-                    throw new UnreachableError(`cannot reach ${url}: ${why}`);
-                }
-                if (r.ok && r.body) {
-                    stream = r.body;
-                    break;
+    group_sandboxes() {
+        return {
+            exec: (sandboxId, opts) => {
+                if (!opts.argv?.length && !opts.sh) {
+                    throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['bun','typecheck'] } or { sh: 'bun typecheck' }.");
                 }
-                clearTimeout(timer);
-                const text = await r.text().catch(() => "");
-                let payload = {};
-                try {
-                    payload = text ? JSON.parse(text) : {};
+                const body = {};
+                if (opts.argv?.length)
+                    body["argv"] = opts.argv;
+                if (opts.sh)
+                    body["sh"] = opts.sh;
+                if (opts.cwd)
+                    body["cwd"] = opts.cwd;
+                if (opts.env)
+                    body["env"] = opts.env;
+                if (opts.user)
+                    body["user"] = opts.user;
+                if (opts.secrets?.length)
+                    body["secrets"] = opts.secrets;
+                if (opts.terminal)
+                    body["terminal"] = true;
+                if (opts.killOnExit !== undefined)
+                    body["kill_on_exit"] = opts.killOnExit;
+                const timeoutMs = commandTimeoutMs(opts.timeoutMs) ?? 15 * 60_000;
+                body["timeout_ms"] = timeoutMs;
+                body["max_output_bytes"] = opts.maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT;
+                if (opts.encoding === "base64")
+                    body["encoding"] = "base64";
+                const req = {
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
+                    body,
+                    timeoutMs: timeoutMs + 30_000,
+                };
+                if (opts.idempotencyKey)
+                    req.idempotencyKey = opts.idempotencyKey;
+                if (opts.signal)
+                    req.signal = opts.signal;
+                return this.request(req);
+            },
+            execStream: async (sandboxId, opts, on = {}) => {
+                if (!opts.argv?.length && !opts.sh) {
+                    throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['bun','typecheck'] } or { sh: 'bun typecheck' }.");
                 }
-                catch { }
-                const retryAfterMs = parseRetryAfter(r.headers.get("retry-after"));
-                const wait = this.refusalBackoff(r.status, retryAfterMs, payload.error?.code, attempt, false, opts.signal);
-                if (wait !== undefined) {
-                    this.stats.retries++;
-                    await sleep(wait);
-                    continue;
+                if (opts.idempotencyKey) {
+                    throw new InvalidArgumentError("a streamed exec cannot take an idempotencyKey (its output cannot be replayed)", "Use sandboxes.exec (buffered) or sandboxes.execBackground with the key, or stream without one.");
                 }
-                const code = payload.error?.code ?? codeForStatus(r.status);
-                throw errorFor(code, payload.error?.message ?? `HTTP ${r.status} from POST /sandboxes/${sandboxId}/execs`, payload.error?.fix ?? "See the API response for details.", {
-                    status: r.status,
-                    ...bodyExtra(payload),
-                    ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
-                });
-            }
-            const out = [];
-            const errOut = [];
-            let exit;
-            let failure;
-            const dec = new TextDecoder();
-            let buf = "";
-            const lost = (how) => new UnreachableError(`the exec stream for sandbox ${sandboxId} ${how}`, "The connection dropped before the command finished; its result is unknown. " +
-                `Read it by id (\`promigence exec output <exec_id> --sandbox ${hintArg(sandboxId)}\`) or re-run.`);
-            reader = stream.getReader();
-            try {
-                for (;;) {
+                const body = {};
+                if (opts.argv?.length)
+                    body["argv"] = opts.argv;
+                if (opts.sh)
+                    body["sh"] = opts.sh;
+                if (opts.cwd)
+                    body["cwd"] = opts.cwd;
+                if (opts.env)
+                    body["env"] = opts.env;
+                if (opts.user)
+                    body["user"] = opts.user;
+                if (opts.secrets?.length)
+                    body["secrets"] = opts.secrets;
+                if (opts.terminal)
+                    body["terminal"] = true;
+                if (opts.killOnExit !== undefined)
+                    body["kill_on_exit"] = opts.killOnExit;
+                body["timeout_ms"] = commandTimeoutMs(opts.timeoutMs) ?? 15 * 60_000;
+                body["max_output_bytes"] = opts.maxOutputBytes ?? MAX_OUTPUT_BYTES_DEFAULT;
+                const url = `${this.apiUrl}/sandboxes/${encodeURIComponent(sandboxId)}/execs`;
+                const idle = new AbortController();
+                let silent = false;
+                let reader;
+                let timer;
+                const arm = () => {
+                    clearTimeout(timer);
+                    timer = setTimeout(() => {
+                        silent = true;
+                        idle.abort();
+                        reader?.cancel().catch(() => { });
+                    }, STREAM_IDLE_MS);
+                };
+                let stream;
+                const bearer = `Bearer ${this.requireKey()}`;
+                const dispatcher = this.guardDispatcher();
+                for (let attempt = 0; stream === undefined; attempt++) {
+                    let r;
+                    this.stats.requests++;
                     arm();
-                    let chunk;
                     try {
-                        chunk = await reader.read();
+                        r = await this.fetchImpl(url, {
+                            method: "POST",
+                            headers: {
+                                accept: "text/event-stream",
+                                "content-type": "application/json",
+                                "user-agent": this.userAgent,
+                                authorization: bearer,
+                                ...(this.caller ? { [CALLER_HEADER]: this.caller } : {}),
+                            },
+                            body: JSON.stringify(body),
+                            signal: opts.signal ? AbortSignal.any([opts.signal, idle.signal]) : idle.signal,
+                            ...(dispatcher === undefined ? {} : { dispatcher }),
+                        });
                     }
                     catch (err) {
-                        if (opts.signal?.aborted)
-                            throw err;
-                        if (silent)
-                            throw lost(`was silent for ${STREAM_IDLE_MS / 1000} s`);
+                        clearTimeout(timer);
                         const e = err;
-                        throw lost(`was cut off (${e?.cause?.code ?? e?.message ?? "connection lost"})`);
+                        const why = silent ? `no answer in ${STREAM_IDLE_MS / 1000} s` : transportDetail(e);
+                        throw new UnreachableError(`cannot reach ${url}: ${why}`);
                     }
-                    if (chunk.done)
+                    if (r.ok && r.body) {
+                        stream = r.body;
                         break;
-                    const value = chunk.value;
-                    buf += dec.decode(value, { stream: true });
-                    let sep;
-                    while ((sep = buf.indexOf("\n\n")) >= 0) {
-                        const block = buf.slice(0, sep);
-                        buf = buf.slice(sep + 2);
-                        let event = "";
-                        let data = "";
-                        for (const line of block.split("\n")) {
-                            if (line.startsWith("event:"))
-                                event = line.slice(6).trim();
-                            else if (line.startsWith("data:"))
-                                data = line.slice(5).replace(/^ /, "");
-                        }
-                        if (!event)
-                            continue;
-                        if (event === "heartbeat") {
-                            on.heartbeat?.();
-                            continue;
-                        }
-                        if (event === "reconnect") {
-                            reader.cancel().catch(() => { });
-                            throw new ServiceRestartError(`a service restart stopped the command on sandbox ${sandboxId} while its output was streaming`, "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe.");
-                        }
-                        let parsed = {};
+                    }
+                    clearTimeout(timer);
+                    const text = await r.text().catch(() => "");
+                    let payload = {};
+                    try {
+                        payload = text ? JSON.parse(text) : {};
+                    }
+                    catch { }
+                    const retryAfterMs = parseRetryAfter(r.headers.get("retry-after"));
+                    const wait = this.refusalBackoff(r.status, retryAfterMs, payload.error?.code, attempt, false, opts.signal);
+                    if (wait !== undefined) {
+                        this.stats.retries++;
+                        await sleep(wait);
+                        continue;
+                    }
+                    const code = payload.error?.code ?? codeForStatus(r.status);
+                    throw errorFor(code, payload.error?.message ?? `HTTP ${r.status} from POST /sandboxes/${sandboxId}/execs`, payload.error?.fix ?? "See the API response for details.", {
+                        status: r.status,
+                        ...bodyExtra(payload),
+                        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                    });
+                }
+                const out = [];
+                const errOut = [];
+                let exit;
+                let failure;
+                const dec = new TextDecoder();
+                let buf = "";
+                const lost = (how) => new UnreachableError(`the exec stream for sandbox ${sandboxId} ${how}`, "The connection dropped before the command finished; its result is unknown. " +
+                    `Read it by id (\`promigence exec output <exec_id> --sandbox ${hintArg(sandboxId)}\`) or re-run.`);
+                reader = stream.getReader();
+                try {
+                    for (;;) {
+                        arm();
+                        let chunk;
                         try {
-                            parsed = JSON.parse(data);
+                            chunk = await reader.read();
                         }
-                        catch { }
-                        if (event === "stdout" || event === "stderr") {
-                            const bytes = b64ToBytes(String(parsed["data"] ?? ""));
-                            if (event === "stdout") {
-                                out.push(bytes);
-                                on.stdout?.(bytes);
+                        catch (err) {
+                            if (opts.signal?.aborted)
+                                throw err;
+                            if (silent)
+                                throw lost(`was silent for ${STREAM_IDLE_MS / 1000} s`);
+                            const e = err;
+                            throw lost(`was cut off (${e?.cause?.code ?? e?.message ?? "connection lost"})`);
+                        }
+                        if (chunk.done)
+                            break;
+                        const value = chunk.value;
+                        buf += dec.decode(value, { stream: true });
+                        let sep;
+                        while ((sep = buf.indexOf("\n\n")) >= 0) {
+                            const block = buf.slice(0, sep);
+                            buf = buf.slice(sep + 2);
+                            let event = "";
+                            let data = "";
+                            for (const line of block.split("\n")) {
+                                if (line.startsWith("event:"))
+                                    event = line.slice(6).trim();
+                                else if (line.startsWith("data:"))
+                                    data = line.slice(5).replace(/^ /, "");
                             }
-                            else {
-                                errOut.push(bytes);
-                                on.stderr?.(bytes);
+                            if (!event)
+                                continue;
+                            if (event === "heartbeat") {
+                                on.heartbeat?.();
+                                continue;
+                            }
+                            if (event === "reconnect") {
+                                reader.cancel().catch(() => { });
+                                throw new ServiceRestartError(`a service restart stopped the command on sandbox ${sandboxId} while its output was streaming`, "Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe.");
+                            }
+                            let parsed = {};
+                            try {
+                                parsed = JSON.parse(data);
+                            }
+                            catch { }
+                            if (event === "stdout" || event === "stderr") {
+                                const bytes = b64ToBytes(String(parsed["data"] ?? ""));
+                                if (event === "stdout") {
+                                    out.push(bytes);
+                                    on.stdout?.(bytes);
+                                }
+                                else {
+                                    errOut.push(bytes);
+                                    on.stderr?.(bytes);
+                                }
+                            }
+                            else if (event === "exit") {
+                                exit = { ...(exit ?? {}), ...parsed };
+                            }
+                            else if (event === "error") {
+                                failure = parsed;
                             }
-                        }
-                        else if (event === "exit") {
-                            exit = { ...(exit ?? {}), ...parsed };
-                        }
-                        else if (event === "error") {
-                            failure = parsed;
                         }
                     }
                 }
-            }
-            finally {
-                clearTimeout(timer);
-            }
-            if (failure) {
-                throw errorFor(failure.code ?? "internal", failure.message ?? "the exec stream failed", failure.fix ?? "Re-run; if it repeats, include the exec_id.", { status: 200, ...bodyExtra({ error: failure }) });
-            }
-            if (!exit && silent)
-                throw lost(`was silent for ${STREAM_IDLE_MS / 1000} s`);
-            if (!exit) {
-                throw lost("ended without an exit event");
-            }
-            const rawCode = exit["exit_code"];
-            const signal = exit["signal"];
-            const exitCode = typeof rawCode === "number" && Number.isFinite(rawCode)
-                ? rawCode
-                : typeof signal === "number" && signal > 0 ? 128 + signal : null;
-            const join = (parts) => {
-                const n = parts.reduce((a, p) => a + p.length, 0);
-                const all = new Uint8Array(n);
-                let at = 0;
-                for (const p of parts) {
-                    all.set(p, at);
-                    at += p.length;
+                finally {
+                    clearTimeout(timer);
                 }
-                return new TextDecoder().decode(all);
-            };
-            return {
-                exec_id: String(exit["exec_id"] ?? ""),
-                sandbox_id: sandboxId,
-                exit_code: exitCode,
-                stdout: join(out),
-                stderr: join(errOut),
-                truncated: Boolean(exit["truncated"] ?? false),
-                ...(exit["timed_out"] === true ? { timed_out: true } : {}),
-                ...(exit["oom_killed"] === true ? { oom_killed: true } : {}),
-                ...(typeof exit["reason"] === "string" ? { reason: exit["reason"] } : {}),
-                ...(typeof signal === "number" ? { signal } : {}),
-            };
-        },
-        execBackground: (sandboxId, opts) => {
-            if (!opts.argv?.length && !opts.sh) {
-                throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['npm','run','dev'] } or { sh: 'npm run dev' }.");
-            }
-            const body = { background: true };
-            if (opts.argv?.length)
-                body["argv"] = opts.argv;
-            if (opts.sh)
-                body["sh"] = opts.sh;
-            if (opts.cwd)
-                body["cwd"] = opts.cwd;
-            if (opts.env)
-                body["env"] = opts.env;
-            if (opts.user)
-                body["user"] = opts.user;
-            if (opts.secrets?.length)
-                body["secrets"] = opts.secrets;
-            if (opts.stdin)
-                body["stdin"] = true;
-            if (opts.follow)
-                body["follow"] = true;
-            const timeoutMs = commandTimeoutMs(opts.timeoutMs);
-            if (timeoutMs !== undefined)
-                body["timeout_ms"] = timeoutMs;
-            if (opts.maxOutputBytes !== undefined)
-                body["max_output_bytes"] = opts.maxOutputBytes;
-            return this.request({
-                method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
-                body,
-                ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
-            });
-        },
-        execs: {
-            list: async (sandboxId) => {
-                const r = await this.request({
-                    method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
-                });
-                return r.execs ?? [];
-            },
-            get: (sandboxId, execId, opts = {}) => {
-                const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
-                return this.request({
-                    method: "GET",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}${wait ? `?wait_ms=${wait}` : ""}`,
-                    ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
-                    ...(opts.signal ? { signal: opts.signal } : {}),
-                });
-            },
-            read: async (sandboxId, execId, stream, opts = {}) => {
-                const q = [`stream=${stream}`, `offset=${Math.max(0, Math.floor(opts.offset ?? 0))}`];
-                if (opts.len !== undefined)
-                    q.push(`len=${Math.max(0, Math.floor(opts.len))}`);
-                const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
-                if (wait)
-                    q.push(`wait_ms=${wait}`);
-                if (wait && opts.untilOutput)
-                    q.push("until=output");
-                const r = await this.request({
-                    method: "GET",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}?${q.join("&")}`,
-                    ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
-                    ...(opts.signal ? { signal: opts.signal } : {}),
-                });
-                return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), skipped: r.skipped ?? 0, record: r };
-            },
-            stdin: (sandboxId, execId, opts = {}) => {
-                if (opts.data === undefined && !opts.eof) {
-                    throw new InvalidArgumentError("execs.stdin needs data, eof, or both", "Pass { data: 'y\\n' } to write, { eof: true } to close, or both to do each in one call.");
+                if (failure) {
+                    throw errorFor(failure.code ?? "internal", failure.message ?? "the exec stream failed", failure.fix ?? "Re-run; if it repeats, include the exec_id.", { status: 200, ...bodyExtra({ error: failure }) });
                 }
-                const bytes = typeof opts.data === "string" ? new TextEncoder().encode(opts.data) : opts.data;
-                return this.request({
-                    method: "POST",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}/stdin`,
-                    body: {
-                        ...(bytes === undefined ? {} : { data: bytesToB64(bytes) }),
-                        ...(opts.eof ? { eof: true } : {}),
-                    },
-                });
-            },
-            signal: (sandboxId, execId, signal = "SIGTERM") => this.request({
-                method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}/signal`,
-                body: { signal },
-            }),
-            forget: (sandboxId, execId) => this.request({
-                method: "DELETE",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}`,
-            }),
-        },
-        ports: {
-            expose: (sandboxId, port) => {
-                if (!Number.isInteger(port) || port < 1 || port > 65535) {
-                    throw new InvalidArgumentError(`port must be an integer 1..65535, got ${port}`, "Pass the port your process listens on inside the sandbox, e.g. 3000.");
+                if (!exit && silent)
+                    throw lost(`was silent for ${STREAM_IDLE_MS / 1000} s`);
+                if (!exit) {
+                    throw lost("ended without an exit event");
                 }
-                return withPreviewsFix(this.request({
-                    method: "POST", path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports`, body: { port },
-                }), sandboxId, port);
-            },
-            list: async (sandboxId) => {
-                const r = await withPreviewsFix(this.request({
-                    method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports`,
-                }), sandboxId);
-                return r.ports ?? [];
+                const rawCode = exit["exit_code"];
+                const signal = exit["signal"];
+                const exitCode = typeof rawCode === "number" && Number.isFinite(rawCode)
+                    ? rawCode
+                    : typeof signal === "number" && signal > 0 ? 128 + signal : null;
+                const join = (parts) => {
+                    const n = parts.reduce((a, p) => a + p.length, 0);
+                    const all = new Uint8Array(n);
+                    let at = 0;
+                    for (const p of parts) {
+                        all.set(p, at);
+                        at += p.length;
+                    }
+                    return new TextDecoder().decode(all);
+                };
+                return {
+                    exec_id: String(exit["exec_id"] ?? ""),
+                    sandbox_id: sandboxId,
+                    exit_code: exitCode,
+                    stdout: join(out),
+                    stderr: join(errOut),
+                    truncated: Boolean(exit["truncated"] ?? false),
+                    ...(exit["timed_out"] === true ? { timed_out: true } : {}),
+                    ...(exit["oom_killed"] === true ? { oom_killed: true } : {}),
+                    ...(typeof exit["reason"] === "string" ? { reason: exit["reason"] } : {}),
+                    ...(typeof signal === "number" ? { signal } : {}),
+                };
             },
-            revoke: (sandboxId, tokenOrPort) => this.request({
-                method: "DELETE",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${encodeURIComponent(String(tokenOrPort))}`,
-            }),
-        },
-        ssh: {
-            open: (sandboxId, opts) => {
-                if (!opts.publicKey?.trim()) {
-                    throw new InvalidArgumentError("publicKey is required", "Pass the contents of an ssh-ed25519 .pub file, or use `promigence sandbox ssh <id>`, which makes one.");
+            execBackground: (sandboxId, opts) => {
+                if (!opts.argv?.length && !opts.sh) {
+                    throw new InvalidArgumentError("exec needs argv or sh", "Pass { argv: ['npm','run','dev'] } or { sh: 'npm run dev' }.");
                 }
+                const body = { background: true };
+                if (opts.argv?.length)
+                    body["argv"] = opts.argv;
+                if (opts.sh)
+                    body["sh"] = opts.sh;
+                if (opts.cwd)
+                    body["cwd"] = opts.cwd;
+                if (opts.env)
+                    body["env"] = opts.env;
+                if (opts.user)
+                    body["user"] = opts.user;
+                if (opts.secrets?.length)
+                    body["secrets"] = opts.secrets;
+                if (opts.stdin)
+                    body["stdin"] = true;
+                if (opts.follow)
+                    body["follow"] = true;
+                const timeoutMs = commandTimeoutMs(opts.timeoutMs);
+                if (timeoutMs !== undefined)
+                    body["timeout_ms"] = timeoutMs;
+                if (opts.maxOutputBytes !== undefined)
+                    body["max_output_bytes"] = opts.maxOutputBytes;
                 return this.request({
                     method: "POST",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh`,
-                    body: {
-                        public_key: opts.publicKey.trim(),
-                        ...(opts.ttlS === undefined ? {} : { ttl_s: Math.floor(opts.ttlS) }),
-                        ...(opts.idleTimeoutS === undefined
-                            ? {}
-                            : { idle_timeout_s: Math.floor(opts.idleTimeoutS) }),
-                    },
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
+                    body,
+                    ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
                 });
             },
-            list: (sandboxId) => this.request({
-                method: "GET",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh`,
-            }),
-            revoke: (sandboxId, keyIdOrFingerprint) => this.request({
-                method: "DELETE",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh/${encodeURIComponent(keyIdOrFingerprint)}`,
-            }),
-            connect: (sandboxId, opts) => connectSshTunnel({
-                url: `${this.apiUrl}/sandboxes/${encodeURIComponent(sandboxId)}/ssh/connect`,
-                token: opts.token ?? this.requireKey(),
-                userAgent: this.userAgent,
-                ...(this.caller ? { caller: this.caller } : {}),
-                onData: opts.onData,
-                onClose: opts.onClose,
-                ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
-                refuse: (status, text) => {
-                    let payload = {};
-                    try {
-                        payload = text ? JSON.parse(text) : {};
-                    }
-                    catch { }
-                    const code = payload.error?.code ?? (status === 0 ? "unreachable" : codeForStatus(status));
-                    return errorFor(code, payload.error?.message ?? `HTTP ${status} from the SSH tunnel`, payload.error?.fix ?? "See the API response for details.", { status, ...bodyExtra(payload) });
+            execs: {
+                list: async (sandboxId) => {
+                    const r = await this.request({
+                        method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs`,
+                    });
+                    return r.execs ?? [];
                 },
-            }),
-        },
-        pty: (sandboxId, opts = {}) => {
-            const q = [];
-            if (opts.cols !== undefined)
-                q.push(`cols=${Math.floor(opts.cols)}`);
-            if (opts.rows !== undefined)
-                q.push(`rows=${Math.floor(opts.rows)}`);
-            const path = `/sandboxes/${encodeURIComponent(sandboxId)}/pty${q.length ? `?${q.join("&")}` : ""}`;
-            const open = () => connectPty({
-                url: `${this.apiUrl}${path}`,
-                apiKey: this.requireKey(),
-                userAgent: this.userAgent,
-                ...(this.caller ? { caller: this.caller } : {}),
-                ...(opts.cmd ? { command: opts.cmd } : {}),
-                ...(opts.secrets?.length ? { secrets: opts.secrets } : {}),
-                ...(opts.onData ? { onData: opts.onData } : {}),
-                ...(opts.onExit ? { onExit: opts.onExit } : {}),
-                ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
-                ...(opts.resume === undefined ? {} : { resume: opts.resume }),
-                ...(opts.reconnect === undefined ? {} : { reconnect: opts.reconnect }),
-                ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
-                refuse: (status, text, retryAfter) => {
-                    let payload = {};
-                    try {
-                        payload = text ? JSON.parse(text) : {};
-                    }
-                    catch { }
-                    const code = payload.error?.code ?? (status === 0 ? "unreachable" : codeForStatus(status));
-                    const retryAfterMs = parseRetryAfter(retryAfter ?? null);
-                    return errorFor(code, payload.error?.message ?? `HTTP ${status} from GET ${path}`, payload.error?.fix ?? "See the API response for details.", {
-                        status,
-                        ...bodyExtra(payload),
-                        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                get: (sandboxId, execId, opts = {}) => {
+                    const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
+                    return this.request({
+                        method: "GET",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}${wait ? `?wait_ms=${wait}` : ""}`,
+                        ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
+                        ...(opts.signal ? { signal: opts.signal } : {}),
                     });
                 },
-            });
-            return (async () => {
-                for (let attempt = 0;; attempt++) {
-                    try {
-                        return await open();
-                    }
-                    catch (err) {
-                        const e = err instanceof PromigenceError ? err : undefined;
-                        const wait = e ? this.refusalBackoff(e.status, e.retryAfterMs, e.code, attempt, false) : undefined;
-                        if (wait === undefined)
-                            throw err;
-                        this.stats.retries++;
-                        await sleep(wait);
+                read: async (sandboxId, execId, stream, opts = {}) => {
+                    const q = [`stream=${stream}`, `offset=${Math.max(0, Math.floor(opts.offset ?? 0))}`];
+                    if (opts.len !== undefined)
+                        q.push(`len=${Math.max(0, Math.floor(opts.len))}`);
+                    const wait = opts.waitMs !== undefined && opts.waitMs > 0 ? Math.min(Math.floor(opts.waitMs), WAIT_MS_CAP) : 0;
+                    if (wait)
+                        q.push(`wait_ms=${wait}`);
+                    if (wait && opts.untilOutput)
+                        q.push("until=output");
+                    const r = await this.request({
+                        method: "GET",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}?${q.join("&")}`,
+                        ...(wait ? { timeoutMs: wait + this.requestTimeoutMs } : {}),
+                        ...(opts.signal ? { signal: opts.signal } : {}),
+                    });
+                    return { data: b64ToBytes(r.data ?? ""), offset: r.offset ?? opts.offset ?? 0, eof: Boolean(r.eof), skipped: r.skipped ?? 0, record: r };
+                },
+                stdin: (sandboxId, execId, opts = {}) => {
+                    if (opts.data === undefined && !opts.eof) {
+                        throw new InvalidArgumentError("execs.stdin needs data, eof, or both", "Pass { data: 'y\\n' } to write, { eof: true } to close, or both to do each in one call.");
                     }
-                }
-            })();
-        },
-        get: (sandboxId) => {
-            checkSandboxId(sandboxId, "sandboxes.get");
-            return this.request({ method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}` });
-        },
-        pause: (sandboxId) => this.request({
-            method: "POST",
-            path: `/sandboxes/${encodeURIComponent(sandboxId)}/pause`,
-            body: {},
-            timeoutMs: 10 * 60_000,
-        }),
-        resume: (sandboxId, opts = {}) => this.request({
-            method: "POST",
-            path: `/sandboxes/${encodeURIComponent(sandboxId)}/resume`,
-            body: {
-                ...(opts.optimizeFor === undefined ? {} : { optimize_for: opts.optimizeFor }),
-                ...(opts.spendCap === undefined ? {} : { spend_cap: checkSpendCap(opts.spendCap) }),
+                    const bytes = typeof opts.data === "string" ? new TextEncoder().encode(opts.data) : opts.data;
+                    return this.request({
+                        method: "POST",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}/stdin`,
+                        body: {
+                            ...(bytes === undefined ? {} : { data: bytesToB64(bytes) }),
+                            ...(opts.eof ? { eof: true } : {}),
+                        },
+                    });
+                },
+                signal: (sandboxId, execId, signal = "SIGTERM") => this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}/signal`,
+                    body: { signal },
+                }),
+                forget: (sandboxId, execId) => this.request({
+                    method: "DELETE",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/execs/${encodeURIComponent(execId)}`,
+                }),
             },
-        }),
-        snapshot: (sandboxId, opts = {}) => this.request({
-            method: "POST",
-            path: `/sandboxes/${encodeURIComponent(sandboxId)}/snapshot`,
-            body: {
-                ...(opts.alias === undefined ? {} : { alias: opts.alias }),
-                ...(opts.force === undefined ? {} : { force: opts.force }),
-                ...(opts.moveAlias === undefined ? {} : { move_alias: opts.moveAlias }),
+            ports: {
+                expose: (sandboxId, port) => {
+                    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                        throw new InvalidArgumentError(`port must be an integer 1..65535, got ${port}`, "Pass the port your process listens on inside the sandbox, e.g. 3000.");
+                    }
+                    return withPreviewsFix(this.request({
+                        method: "POST", path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports`, body: { port },
+                    }), sandboxId, port);
+                },
+                list: async (sandboxId) => {
+                    const r = await withPreviewsFix(this.request({
+                        method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports`,
+                    }), sandboxId);
+                    return r.ports ?? [];
+                },
+                revoke: (sandboxId, tokenOrPort) => this.request({
+                    method: "DELETE",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ports/${encodeURIComponent(String(tokenOrPort))}`,
+                }),
             },
-            timeoutMs: 10 * 60_000,
-        }),
-        list: async (opts = 50) => (await this.sandboxes.listPage(opts)).items,
-        listPage: async (opts = 50) => {
-            const o = typeof opts === "number" ? { limit: opts } : opts;
-            const q = new URLSearchParams({ limit: String(Math.max(1, Math.trunc(o.limit ?? 50))) });
-            const pairs = Object.entries(o.labels ?? {});
-            if (pairs.length)
-                q.set("labels", pairs.map(([k, v]) => `${k}=${v}`).join(","));
-            if (o.state?.length)
-                q.set("state", o.state.join(","));
-            if (o.cursor)
-                q.set("cursor", o.cursor);
-            const r = await this.request({
-                method: "GET",
-                path: `/sandboxes?${q.toString()}`,
-            });
-            return { items: r.sandboxes ?? [], nextCursor: r.next_cursor ?? null, limit: r.limit ?? (o.limit ?? 50) };
-        },
-        probe: (sandboxId, opts = {}) => this.request({
-            method: "POST",
-            path: `/sandboxes/${encodeURIComponent(sandboxId)}/probe`,
-            body: opts.paths?.length ? { paths: opts.paths } : {},
-        }),
-        kill: (sandboxId) => this.request({ method: "DELETE", path: `/sandboxes/${encodeURIComponent(sandboxId)}` }),
-        network: (sandboxId) => this.request({ method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/network` }),
-        setNetworkNone: (sandboxId) => this.request({
-            method: "POST",
-            path: `/sandboxes/${encodeURIComponent(sandboxId)}/network`,
-            body: { network: "none" },
-        }),
-        patch: (sandboxId, opts) => {
-            const body = {};
-            if (opts.timeoutMs !== undefined) {
-                if (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs <= 0) {
-                    throw new InvalidArgumentError("sandboxes.patch needs a positive timeoutMs", "Pass { timeoutMs: 1_800_000 }.");
-                }
-                body["timeout_ms"] = opts.timeoutMs;
-            }
-            if (opts.autoPauseS !== undefined) {
-                if (!Number.isInteger(opts.autoPauseS) || opts.autoPauseS < 0) {
-                    throw new InvalidArgumentError("sandboxes.patch needs a non-negative whole number of seconds for autoPauseS", "Pass { autoPauseS: 900 } to pause it after 15 idle minutes, or { autoPauseS: 0 } to turn that off.");
-                }
-                body["auto_pause_s"] = opts.autoPauseS;
-            }
-            if (opts.autoPauseMode !== undefined) {
-                if (opts.autoPauseMode !== "requests" && opts.autoPauseMode !== "activity") {
-                    throw new InvalidArgumentError(`sandboxes.patch: autoPauseMode must be "requests" or "activity", got ${JSON.stringify(opts.autoPauseMode)}`, 'Pass { autoPauseMode: "activity" } for an agent that runs inside the sandbox.');
-                }
-                body["auto_pause_mode"] = opts.autoPauseMode;
-            }
-            if (Object.keys(body).length === 0) {
-                throw new InvalidArgumentError("sandboxes.patch was given nothing to change", "Pass { timeoutMs } to extend it, { autoPauseS } to set its idle rule, or both.");
-            }
-            return this.request({
-                method: "PATCH",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}`,
-                body,
-            });
-        },
-        files: {
-            list: (sandboxId, path = "/", opts = {}) => {
-                const q = [`path=${encodeURIComponent(path)}`];
-                if (opts.recursive)
-                    q.push("recursive=1");
-                if (opts.depth !== undefined)
-                    q.push(`depth=${Math.max(0, Math.floor(opts.depth))}`);
-                if (opts.limit !== undefined)
-                    q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
-                if (opts.hidden === false)
-                    q.push("hidden=0");
-                return this.request({
+            ssh: {
+                open: (sandboxId, opts) => {
+                    if (!opts.publicKey?.trim()) {
+                        throw new InvalidArgumentError("publicKey is required", "Pass the contents of an ssh-ed25519 .pub file, or use `promigence sandbox ssh <id>`, which makes one.");
+                    }
+                    return this.request({
+                        method: "POST",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh`,
+                        body: {
+                            public_key: opts.publicKey.trim(),
+                            ...(opts.ttlS === undefined ? {} : { ttl_s: Math.floor(opts.ttlS) }),
+                            ...(opts.idleTimeoutS === undefined
+                                ? {}
+                                : { idle_timeout_s: Math.floor(opts.idleTimeoutS) }),
+                        },
+                    });
+                },
+                list: (sandboxId) => this.request({
                     method: "GET",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/list?${q.join("&")}`,
-                });
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh`,
+                }),
+                revoke: (sandboxId, keyIdOrFingerprint) => this.request({
+                    method: "DELETE",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/ssh/${encodeURIComponent(keyIdOrFingerprint)}`,
+                }),
+                connect: (sandboxId, opts) => connectSshTunnel({
+                    url: `${this.apiUrl}/sandboxes/${encodeURIComponent(sandboxId)}/ssh/connect`,
+                    token: opts.token ?? this.requireKey(),
+                    userAgent: this.userAgent,
+                    ...(this.caller ? { caller: this.caller } : {}),
+                    onData: opts.onData,
+                    onClose: opts.onClose,
+                    ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                    refuse: (status, text) => {
+                        let payload = {};
+                        try {
+                            payload = text ? JSON.parse(text) : {};
+                        }
+                        catch { }
+                        const code = payload.error?.code ?? (status === 0 ? "unreachable" : codeForStatus(status));
+                        return errorFor(code, payload.error?.message ?? `HTTP ${status} from the SSH tunnel`, payload.error?.fix ?? "See the API response for details.", { status, ...bodyExtra(payload) });
+                    },
+                }),
             },
-            search: (sandboxId, path, opts = {}) => {
-                if (!opts.pattern && !opts.contains) {
-                    throw new InvalidArgumentError("files.search needs `pattern`, `contains`, or both", "Pass { pattern: '*.py' } for a name glob, { contains: 'TODO' } for text inside files.");
-                }
-                const q = [`path=${encodeURIComponent(path)}`];
-                if (opts.pattern)
-                    q.push(`pattern=${encodeURIComponent(opts.pattern)}`);
-                if (opts.contains)
-                    q.push(`contains=${encodeURIComponent(opts.contains)}`);
-                if (opts.ignoreCase)
-                    q.push("ignore_case=1");
-                if (opts.limit !== undefined)
-                    q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
-                if (opts.hidden === false)
-                    q.push("hidden=0");
-                return this.request({
-                    method: "GET",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/search?${q.join("&")}`,
+            pty: (sandboxId, opts = {}) => {
+                const q = [];
+                if (opts.cols !== undefined)
+                    q.push(`cols=${Math.floor(opts.cols)}`);
+                if (opts.rows !== undefined)
+                    q.push(`rows=${Math.floor(opts.rows)}`);
+                const path = `/sandboxes/${encodeURIComponent(sandboxId)}/pty${q.length ? `?${q.join("&")}` : ""}`;
+                const open = () => connectPty({
+                    url: `${this.apiUrl}${path}`,
+                    apiKey: this.requireKey(),
+                    userAgent: this.userAgent,
+                    ...(this.caller ? { caller: this.caller } : {}),
+                    ...(opts.cmd ? { command: opts.cmd } : {}),
+                    ...(opts.secrets?.length ? { secrets: opts.secrets } : {}),
+                    ...(opts.onData ? { onData: opts.onData } : {}),
+                    ...(opts.onExit ? { onExit: opts.onExit } : {}),
+                    ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+                    ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+                    ...(opts.reconnect === undefined ? {} : { reconnect: opts.reconnect }),
+                    ...(opts.onReconnected ? { onReconnected: opts.onReconnected } : {}),
+                    refuse: (status, text, retryAfter) => {
+                        let payload = {};
+                        try {
+                            payload = text ? JSON.parse(text) : {};
+                        }
+                        catch { }
+                        const code = payload.error?.code ?? (status === 0 ? "unreachable" : codeForStatus(status));
+                        const retryAfterMs = parseRetryAfter(retryAfter ?? null);
+                        return errorFor(code, payload.error?.message ?? `HTTP ${status} from GET ${path}`, payload.error?.fix ?? "See the API response for details.", {
+                            status,
+                            ...bodyExtra(payload),
+                            ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                        });
+                    },
                 });
+                return (async () => {
+                    for (let attempt = 0;; attempt++) {
+                        try {
+                            return await open();
+                        }
+                        catch (err) {
+                            const e = err instanceof PromigenceError ? err : undefined;
+                            const wait = e ? this.refusalBackoff(e.status, e.retryAfterMs, e.code, attempt, false) : undefined;
+                            if (wait === undefined)
+                                throw err;
+                            this.stats.retries++;
+                            await sleep(wait);
+                        }
+                    }
+                })();
             },
-            mkdir: (sandboxId, path, opts = {}) => this.request({
+            get: (sandboxId) => {
+                checkSandboxId(sandboxId, "sandboxes.get");
+                return this.request({ method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}` });
+            },
+            pause: (sandboxId) => this.request({
                 method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/mkdir`,
-                body: {
-                    path,
-                    ...(opts.mode === undefined ? {} : { mode: modeParam(opts.mode) }),
-                    ...(opts.parents === undefined ? {} : { parents: opts.parents }),
-                },
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/pause`,
+                body: {},
+                timeoutMs: 10 * 60_000,
             }),
-            move: (sandboxId, from, to, opts = {}) => this.request({
+            resume: (sandboxId, opts = {}) => this.request({
                 method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/move`,
-                body: { from, to, ...(opts.overwrite === undefined ? {} : { overwrite: opts.overwrite }) },
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/resume`,
+                body: {
+                    ...(opts.optimizeFor === undefined ? {} : { optimize_for: opts.optimizeFor }),
+                    ...(opts.spendCap === undefined ? {} : { spend_cap: checkSpendCap(opts.spendCap) }),
+                },
             }),
-            copy: (sandboxId, from, to, opts = {}) => this.request({
+            snapshot: (sandboxId, opts = {}) => this.request({
                 method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/copy`,
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/snapshot`,
                 body: {
-                    from, to,
-                    ...(opts.recursive === undefined ? {} : { recursive: opts.recursive }),
-                    ...(opts.overwrite === undefined ? {} : { overwrite: opts.overwrite }),
+                    ...(opts.alias === undefined ? {} : { alias: opts.alias }),
+                    ...(opts.force === undefined ? {} : { force: opts.force }),
+                    ...(opts.moveAlias === undefined ? {} : { move_alias: opts.moveAlias }),
                 },
+                timeoutMs: 10 * 60_000,
+            }),
+            list: async (opts = 50) => (await this.sandboxes.listPage(opts)).items,
+            listPage: async (opts = 50) => {
+                const o = typeof opts === "number" ? { limit: opts } : opts;
+                const q = new URLSearchParams({ limit: String(Math.max(1, Math.trunc(o.limit ?? 50))) });
+                const pairs = Object.entries(o.labels ?? {});
+                if (pairs.length)
+                    q.set("labels", pairs.map(([k, v]) => `${k}=${v}`).join(","));
+                if (o.state?.length)
+                    q.set("state", o.state.join(","));
+                if (o.cursor)
+                    q.set("cursor", o.cursor);
+                const r = await this.request({
+                    method: "GET",
+                    path: `/sandboxes?${q.toString()}`,
+                });
+                return { items: r.sandboxes ?? [], nextCursor: r.next_cursor ?? null, limit: r.limit ?? (o.limit ?? 50) };
+            },
+            probe: (sandboxId, opts = {}) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/probe`,
+                body: opts.paths?.length ? { paths: opts.paths } : {},
+            }),
+            kill: (sandboxId) => this.request({ method: "DELETE", path: `/sandboxes/${encodeURIComponent(sandboxId)}` }),
+            network: (sandboxId) => this.request({ method: "GET", path: `/sandboxes/${encodeURIComponent(sandboxId)}/network` }),
+            setNetworkNone: (sandboxId) => this.request({
+                method: "POST",
+                path: `/sandboxes/${encodeURIComponent(sandboxId)}/network`,
+                body: { network: "none" },
             }),
-            chmod: (sandboxId, path, opts) => {
-                if (opts.mode === undefined && opts.uid === undefined && opts.gid === undefined) {
-                    throw new InvalidArgumentError("files.chmod needs one of mode, uid or gid", "Pass { mode: 0o755 }, { uid: 1000 }, { gid: 1000 }, or any combination.");
+            patch: (sandboxId, opts) => {
+                const body = {};
+                if (opts.timeoutMs !== undefined) {
+                    if (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs <= 0) {
+                        throw new InvalidArgumentError("sandboxes.patch needs a positive timeoutMs", "Pass { timeoutMs: 1_800_000 }.");
+                    }
+                    body["timeout_ms"] = opts.timeoutMs;
+                }
+                if (opts.autoPauseS !== undefined) {
+                    if (!Number.isInteger(opts.autoPauseS) || opts.autoPauseS < 0) {
+                        throw new InvalidArgumentError("sandboxes.patch needs a non-negative whole number of seconds for autoPauseS", "Pass { autoPauseS: 900 } to pause it after 15 idle minutes, or { autoPauseS: 0 } to turn that off.");
+                    }
+                    body["auto_pause_s"] = opts.autoPauseS;
+                }
+                if (opts.autoPauseMode !== undefined) {
+                    if (opts.autoPauseMode !== "requests" && opts.autoPauseMode !== "activity") {
+                        throw new InvalidArgumentError(`sandboxes.patch: autoPauseMode must be "requests" or "activity", got ${JSON.stringify(opts.autoPauseMode)}`, 'Pass { autoPauseMode: "activity" } for an agent that runs inside the sandbox.');
+                    }
+                    body["auto_pause_mode"] = opts.autoPauseMode;
+                }
+                if (Object.keys(body).length === 0) {
+                    throw new InvalidArgumentError("sandboxes.patch was given nothing to change", "Pass { timeoutMs } to extend it, { autoPauseS } to set its idle rule, or both.");
                 }
                 return this.request({
+                    method: "PATCH",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}`,
+                    body,
+                });
+            },
+            files: {
+                list: (sandboxId, path = "/", opts = {}) => {
+                    const q = [`path=${encodeURIComponent(path)}`];
+                    if (opts.recursive)
+                        q.push("recursive=1");
+                    if (opts.depth !== undefined)
+                        q.push(`depth=${Math.max(0, Math.floor(opts.depth))}`);
+                    if (opts.limit !== undefined)
+                        q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
+                    if (opts.hidden === false)
+                        q.push("hidden=0");
+                    return this.request({
+                        method: "GET",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/list?${q.join("&")}`,
+                    });
+                },
+                search: (sandboxId, path, opts = {}) => {
+                    if (!opts.pattern && !opts.contains) {
+                        throw new InvalidArgumentError("files.search needs `pattern`, `contains`, or both", "Pass { pattern: '*.py' } for a name glob, { contains: 'TODO' } for text inside files.");
+                    }
+                    const q = [`path=${encodeURIComponent(path)}`];
+                    if (opts.pattern)
+                        q.push(`pattern=${encodeURIComponent(opts.pattern)}`);
+                    if (opts.contains)
+                        q.push(`contains=${encodeURIComponent(opts.contains)}`);
+                    if (opts.ignoreCase)
+                        q.push("ignore_case=1");
+                    if (opts.limit !== undefined)
+                        q.push(`limit=${Math.max(1, Math.floor(opts.limit))}`);
+                    if (opts.hidden === false)
+                        q.push("hidden=0");
+                    return this.request({
+                        method: "GET",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/search?${q.join("&")}`,
+                    });
+                },
+                mkdir: (sandboxId, path, opts = {}) => this.request({
                     method: "POST",
-                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/chmod`,
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/mkdir`,
                     body: {
                         path,
                         ...(opts.mode === undefined ? {} : { mode: modeParam(opts.mode) }),
-                        ...(opts.uid === undefined ? {} : { uid: opts.uid }),
-                        ...(opts.gid === undefined ? {} : { gid: opts.gid }),
+                        ...(opts.parents === undefined ? {} : { parents: opts.parents }),
+                    },
+                }),
+                move: (sandboxId, from, to, opts = {}) => this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/move`,
+                    body: { from, to, ...(opts.overwrite === undefined ? {} : { overwrite: opts.overwrite }) },
+                }),
+                copy: (sandboxId, from, to, opts = {}) => this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/copy`,
+                    body: {
+                        from, to,
                         ...(opts.recursive === undefined ? {} : { recursive: opts.recursive }),
+                        ...(opts.overwrite === undefined ? {} : { overwrite: opts.overwrite }),
                     },
-                });
-            },
-            archive: (sandboxId, path, opts = {}) => this.request({
-                method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/archive`,
-                body: {
-                    path,
-                    ...(opts.out === undefined ? {} : { out: opts.out }),
-                    ...(opts.exclude?.length ? { exclude: opts.exclude } : {}),
-                },
-            }),
-            extract: (sandboxId, archive, into, opts = {}) => this.request({
-                method: "POST",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/extract`,
-                body: { archive, into, ...(opts.strip === undefined ? {} : { strip: Math.max(0, Math.floor(opts.strip)) }) },
-            }),
-            stat: (sandboxId, path) => this.request({
-                method: "GET",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/stat?path=${encodeURIComponent(path)}`,
-            }),
-            get: (sandboxId, path, opts = {}) => this.bytes("GET", `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, undefined, opts),
-            download: (sandboxId, path, onChunk, opts = {}) => this.stream(`/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, onChunk, opts),
-            text: async (sandboxId, path, opts = {}) => new TextDecoder().decode(await this.sandboxes.files.get(sandboxId, path, opts)),
-            put: async (sandboxId, path, data, opts = {}) => {
-                const body = typeof data === "string" ? new TextEncoder().encode(data) : data;
-                return this.sandboxes.files.putFrom(sandboxId, path, {
-                    size: body.length,
-                    read: (offset, len) => body.subarray(offset, offset + len),
-                }, opts);
-            },
-            putFrom: async (sandboxId, path, source, opts = {}) => {
-                const mode = opts.mode === undefined ? "" : `&mode=${opts.mode.toString(8)}`;
-                const base = `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}${mode}`;
-                let sent = 0;
-                let chunks = 0;
-                let last;
-                do {
-                    const slice = await source.read(sent, Math.min(FILE_PUT_CHUNK_BYTES, source.size - sent));
-                    if (slice.length === 0 && sent < source.size) {
-                        throw new InvalidArgumentError(`the source of ${path} ended at ${sent} of ${source.size} bytes`, "The file shrank while it was being sent; send it again once nothing is writing it.");
+                }),
+                chmod: (sandboxId, path, opts) => {
+                    if (opts.mode === undefined && opts.uid === undefined && opts.gid === undefined) {
+                        throw new InvalidArgumentError("files.chmod needs one of mode, uid or gid", "Pass { mode: 0o755 }, { uid: 1000 }, { gid: 1000 }, or any combination.");
                     }
-                    const raw = await this.bytes("PUT", sent === 0 ? base : `${base}&offset=${sent}`, slice, opts);
-                    last = JSON.parse(new TextDecoder().decode(raw));
-                    sent += slice.length;
-                    chunks += 1;
-                } while (sent < source.size);
-                return { ...last, bytes: source.size, chunks };
+                    return this.request({
+                        method: "POST",
+                        path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/chmod`,
+                        body: {
+                            path,
+                            ...(opts.mode === undefined ? {} : { mode: modeParam(opts.mode) }),
+                            ...(opts.uid === undefined ? {} : { uid: opts.uid }),
+                            ...(opts.gid === undefined ? {} : { gid: opts.gid }),
+                            ...(opts.recursive === undefined ? {} : { recursive: opts.recursive }),
+                        },
+                    });
+                },
+                archive: (sandboxId, path, opts = {}) => this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/archive`,
+                    body: {
+                        path,
+                        ...(opts.out === undefined ? {} : { out: opts.out }),
+                        ...(opts.exclude?.length ? { exclude: opts.exclude } : {}),
+                    },
+                }),
+                extract: (sandboxId, archive, into, opts = {}) => this.request({
+                    method: "POST",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/extract`,
+                    body: { archive, into, ...(opts.strip === undefined ? {} : { strip: Math.max(0, Math.floor(opts.strip)) }) },
+                }),
+                stat: (sandboxId, path) => this.request({
+                    method: "GET",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files/stat?path=${encodeURIComponent(path)}`,
+                }),
+                get: (sandboxId, path, opts = {}) => this.bytes("GET", `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, undefined, opts),
+                download: (sandboxId, path, onChunk, opts = {}) => this.stream(`/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`, onChunk, opts),
+                text: async (sandboxId, path, opts = {}) => new TextDecoder().decode(await this.sandboxes.files.get(sandboxId, path, opts)),
+                put: async (sandboxId, path, data, opts = {}) => {
+                    const body = typeof data === "string" ? new TextEncoder().encode(data) : data;
+                    return this.sandboxes.files.putFrom(sandboxId, path, {
+                        size: body.length,
+                        read: (offset, len) => body.subarray(offset, offset + len),
+                    }, opts);
+                },
+                putFrom: async (sandboxId, path, source, opts = {}) => {
+                    const mode = opts.mode === undefined ? "" : `&mode=${opts.mode.toString(8)}`;
+                    const base = `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}${mode}`;
+                    let sent = 0;
+                    let chunks = 0;
+                    let last;
+                    do {
+                        const slice = await source.read(sent, Math.min(FILE_PUT_CHUNK_BYTES, source.size - sent));
+                        if (slice.length === 0 && sent < source.size) {
+                            throw new InvalidArgumentError(`the source of ${path} ended at ${sent} of ${source.size} bytes`, "The file shrank while it was being sent; send it again once nothing is writing it.");
+                        }
+                        const raw = await this.bytes("PUT", sent === 0 ? base : `${base}&offset=${sent}`, slice, opts);
+                        last = JSON.parse(new TextDecoder().decode(raw));
+                        sent += slice.length;
+                        chunks += 1;
+                    } while (sent < source.size);
+                    return { ...last, bytes: source.size, chunks };
+                },
+                delete: (sandboxId, path, opts = {}) => this.request({
+                    method: "DELETE",
+                    path: `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`
+                        + (opts.recursive ? "&recursive=1" : ""),
+                }),
             },
-            delete: (sandboxId, path, opts = {}) => this.request({
-                method: "DELETE",
-                path: `/sandboxes/${encodeURIComponent(sandboxId)}/files?path=${encodeURIComponent(path)}`
-                    + (opts.recursive ? "&recursive=1" : ""),
-            }),
-        },
-        output: async (execId, opts = {}) => {
-            if (!execId)
-                throw new InvalidArgumentError("exec output needs an exec_id", "Pass the `exec_id` the exec envelope printed.");
-            let runId = opts.runId;
-            const fromSandbox = async (sid) => {
-                const rec = await this.request({
-                    method: "GET", path: `/sandboxes/${encodeURIComponent(sid)}`,
-                });
-                const hit = (rec?.execs ?? []).find((e) => e.exec_id === execId);
-                if (hit && rec?.run_id)
-                    runId ??= rec.run_id;
-                return hit;
-            };
-            let found;
-            let sandboxId = opts.sandboxId;
-            let routeMissing = false;
-            try {
-                found = await this.request({ method: "GET", path: `/execs/${encodeURIComponent(execId)}` });
-            }
-            catch (err) {
-                if (!(err instanceof NotFoundError))
-                    throw err;
-                found = undefined;
-                routeMissing = true;
-            }
-            if (found && opts.runId && found.run_id && found.run_id !== opts.runId)
-                found = undefined;
-            let otherSandbox = false;
-            if (found && opts.sandboxId && found.sandbox_id && found.sandbox_id !== opts.sandboxId) {
-                found = undefined;
-                otherSandbox = true;
-            }
-            if (found)
-                runId ??= found.run_id;
-            if (!found && (routeMissing || otherSandbox) && opts.sandboxId) {
+            output: async (execId, opts = {}) => {
+                if (!execId)
+                    throw new InvalidArgumentError("exec output needs an exec_id", "Pass the `exec_id` the exec envelope printed.");
+                let runId = opts.runId;
+                const fromSandbox = async (sid) => {
+                    const rec = await this.request({
+                        method: "GET", path: `/sandboxes/${encodeURIComponent(sid)}`,
+                    });
+                    const hit = (rec?.execs ?? []).find((e) => e.exec_id === execId);
+                    if (hit && rec?.run_id)
+                        runId ??= rec.run_id;
+                    return hit;
+                };
+                let found;
+                let sandboxId = opts.sandboxId;
+                let routeMissing = false;
                 try {
-                    found = await fromSandbox(opts.sandboxId);
+                    found = await this.request({ method: "GET", path: `/execs/${encodeURIComponent(execId)}` });
                 }
                 catch (err) {
                     if (!(err instanceof NotFoundError))
                         throw err;
                     found = undefined;
+                    routeMissing = true;
                 }
-            }
-            sandboxId ??= found?.sandbox_id;
-            if (!found) {
-                throw new NotFoundError(`exec ${execId} not found${sandboxId ? ` in sandbox ${sandboxId}` : opts.runId ? ` in run ${opts.runId}` : ""}`, "Check the `exec_id` from the exec envelope, and that the sandbox it ran in still exists (`promigence run report <run_id>`).");
-            }
-            return sliceOutput(found, sandboxId, runId, opts.range);
-        },
-    };
+                if (found && opts.runId && found.run_id && found.run_id !== opts.runId)
+                    found = undefined;
+                let otherSandbox = false;
+                if (found && opts.sandboxId && found.sandbox_id && found.sandbox_id !== opts.sandboxId) {
+                    found = undefined;
+                    otherSandbox = true;
+                }
+                if (found)
+                    runId ??= found.run_id;
+                if (!found && (routeMissing || otherSandbox) && opts.sandboxId) {
+                    try {
+                        found = await fromSandbox(opts.sandboxId);
+                    }
+                    catch (err) {
+                        if (!(err instanceof NotFoundError))
+                            throw err;
+                        found = undefined;
+                    }
+                }
+                sandboxId ??= found?.sandbox_id;
+                if (!found) {
+                    throw new NotFoundError(`exec ${execId} not found${sandboxId ? ` in sandbox ${sandboxId}` : opts.runId ? ` in run ${opts.runId}` : ""}`, "Check the `exec_id` from the exec envelope, and that the sandbox it ran in still exists (`promigence run report <run_id>`).");
+                }
+                return sliceOutput(found, sandboxId, runId, opts.range);
+            },
+        };
+    }
     sandbox(id) {
         return {
             id,
@@ -2398,142 +2418,174 @@ export class PromigenceClient {
             probe: (opts = {}) => this.sandboxes.probe(id, opts),
         };
     }
-    secrets = {
-        set: (name, value, opts = {}) => {
-            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name ?? "")) {
-                throw new InvalidArgumentError(`secrets.set: ${JSON.stringify(name ?? null)} is not usable as an environment variable`, "Use letters, digits and underscores, not starting with a digit: OPENAI_API_KEY.");
-            }
-            if (!value) {
-                throw new InvalidArgumentError(`secrets.set: ${name} has an empty value`, `To remove it, call secrets.delete(${JSON.stringify(name)}).`);
-            }
-            const body = { name, value };
-            if (opts.hosts !== undefined)
-                body.hosts = opts.hosts;
-            if (opts.headers !== undefined)
-                body.headers = opts.headers;
-            if (opts.raw !== undefined)
-                body.raw = opts.raw;
-            if (opts.scanResponses !== undefined)
-                body.scan_responses = opts.scanResponses;
-            return this.request({ method: "POST", path: "/secrets", body });
-        },
-        list: () => this.request({ method: "GET", path: "/secrets" }),
-        delete: (name) => this.request({
-            method: "DELETE",
-            path: `/secrets/${encodeURIComponent(name)}`,
-        }),
-    };
-    images = {
-        resolve: (image, opts = {}) => {
-            if (!image?.trim()) {
-                throw new InvalidArgumentError("images.resolve needs an image reference", "Pass a name like 'python:3.12' or 'ghcr.io/org/app:v1'.");
-            }
-            const body = { image: image.trim() };
-            if (opts.registrySecret)
-                body["registry_secret"] = opts.registrySecret;
-            return this.request({ method: "POST", path: "/images/resolve", body });
-        },
-    };
-    captures = {
-        delete: (snapshotId) => this.request({
-            method: "DELETE",
-            path: `/captures/${encodeURIComponent(snapshotId)}`,
-        }),
-    };
-    snapshots = {
-        create: (opts) => {
-            const body = snapshotCreateBody(opts);
-            return this.request({
-                method: "POST", path: "/snapshots", body,
-                ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
-            });
-        },
-        status: (buildId, opts = {}) => this.request({
-            method: "GET",
-            path: `/snapshots/builds/${encodeURIComponent(buildId)}${waitQuery(opts.waitMs)}`,
-            ...this.readExtras(opts),
-        }),
-        buildLog: async (buildId, tail = 200) => {
-            const r = await this.request({
-                method: "GET",
-                path: `/snapshots/builds/${encodeURIComponent(buildId)}/build-log?tail=${Math.max(1, Math.floor(tail))}`,
-            });
-            return r?.log ?? [];
-        },
-        builds: async (limit = 20) => (await this.snapshots.buildsPage({ limit })).items,
-        buildsPage: async (opts = {}) => {
-            const limit = opts.limit ?? 20;
-            const r = await this.request({ method: "GET", path: `/snapshots/builds?${pageQuery(limit, 500, opts.cursor)}` });
-            return pageOf(r, "builds", limit);
-        },
-        get: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}` }),
-        list: async (opts = {}) => (await this.snapshots.listPage(opts)).items,
-        listPage: async (opts = {}) => {
-            const q = new URLSearchParams();
-            if (opts.limit !== undefined)
-                q.set("limit", String(Math.max(1, Math.trunc(opts.limit))));
-            if (opts.cursor)
-                q.set("cursor", opts.cursor);
-            const qs = q.toString();
-            const r = await this.request({
-                method: "GET", path: `/snapshots${qs ? `?${qs}` : ""}`, ...(this.authenticated ? {} : { anonymous: true }),
-            });
-            if (Array.isArray(r))
-                return { items: r, nextCursor: null, limit: opts.limit ?? r.length };
-            return { items: r?.snapshots ?? [], nextCursor: r?.next_cursor ?? null, limit: r?.limit ?? (opts.limit ?? 0) };
-        },
-        public: async (limit = 20) => {
-            const r = await this.request({
+    group_secrets() {
+        return {
+            set: (name, value, opts = {}) => {
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name ?? "")) {
+                    throw new InvalidArgumentError(`secrets.set: ${JSON.stringify(name ?? null)} is not usable as an environment variable`, "Use letters, digits and underscores, not starting with a digit: OPENAI_API_KEY.");
+                }
+                if (!value) {
+                    throw new InvalidArgumentError(`secrets.set: ${name} has an empty value`, `To remove it, call secrets.delete(${JSON.stringify(name)}).`);
+                }
+                const body = { name, value };
+                if (opts.hosts !== undefined)
+                    body.hosts = opts.hosts;
+                if (opts.headers !== undefined)
+                    body.headers = opts.headers;
+                if (opts.raw !== undefined)
+                    body.raw = opts.raw;
+                if (opts.scanResponses !== undefined)
+                    body.scan_responses = opts.scanResponses;
+                return this.request({ method: "POST", path: "/secrets", body });
+            },
+            list: () => this.request({ method: "GET", path: "/secrets" }),
+            delete: (name) => this.request({
+                method: "DELETE",
+                path: `/secrets/${encodeURIComponent(name)}`,
+            }),
+        };
+    }
+    group_images() {
+        return {
+            resolve: (image, opts = {}) => {
+                if (!image?.trim()) {
+                    throw new InvalidArgumentError("images.resolve needs an image reference", "Pass a name like 'python:3.12' or 'ghcr.io/org/app:v1'.");
+                }
+                const body = { image: image.trim() };
+                if (opts.registrySecret)
+                    body["registry_secret"] = opts.registrySecret;
+                return this.request({ method: "POST", path: "/images/resolve", body });
+            },
+        };
+    }
+    group_captures() {
+        return {
+            delete: (snapshotId) => this.request({
+                method: "DELETE",
+                path: `/captures/${encodeURIComponent(snapshotId)}`,
+            }),
+        };
+    }
+    group_snapshots() {
+        return {
+            create: (opts) => {
+                const body = snapshotCreateBody(opts);
+                return this.request({
+                    method: "POST", path: "/snapshots", body,
+                    ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+                });
+            },
+            status: (buildId, opts = {}) => this.request({
                 method: "GET",
-                path: `/snapshots?limit=${Math.max(1, Math.floor(limit))}`,
-                anonymous: true,
-            });
-            const all = Array.isArray(r) ? r : (r?.snapshots ?? []);
-            return all.filter((s) => s.visibility === undefined || s.visibility === "public").slice(0, limit);
-        },
-        delete: (idOrAlias) => {
-            if (!idOrAlias)
-                throw new InvalidArgumentError("snapshots.delete needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
-            return this.request({ method: "DELETE", path: `/snapshots/${seg(idOrAlias)}` });
-        },
-        alias: (idOrAlias, alias) => this.request({
-            method: "PUT",
-            path: `/snapshots/${seg(idOrAlias)}/alias`,
-            body: { alias },
-        }),
-        waitBuild: async (buildId, opts = {}) => {
-            const r = await this.waitLoop(opts, BUILD_POLL_MS, { build_id: buildId, state: "running" }, (read) => this.snapshots.status(buildId, read), (b) => b.state !== "running" && b.state !== "queued");
-            return { build: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
-        },
-        verify: (id, opts = {}) => {
-            if (!id)
-                throw new InvalidArgumentError("snapshots.verify needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
-            const body = {};
-            if (opts.timeoutMs !== undefined)
-                body["timeout_ms"] = opts.timeoutMs;
-            if (opts.spendCap !== undefined)
-                body["spend_cap"] = opts.spendCap;
-            return this.request({
-                method: "POST",
-                path: `/snapshots/${encodeURIComponent(id)}/verify`,
-                body,
-            });
-        },
-        manifest: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}/manifest` }),
-        bundle: async (idOrAlias, opts = {}) => {
-            const [record, m] = await Promise.all([
-                this.snapshots.get(idOrAlias).catch(() => undefined),
-                this.snapshots.manifest(idOrAlias),
-            ]);
-            if (!m?.manifest || typeof m.manifest !== "object") {
-                throw new NotFoundError(`snapshot ${idOrAlias} has no manifest to export`, "Only a verified snapshot has one: check 'promigence snapshot inspect' first.");
-            }
-            const alias = opts.alias ?? record?.alias ?? undefined;
-            const bundle = buildBundle(m.manifest, { ...(alias ? { alias } : {}) });
-            return { bundle, served_by: "client", ...(record ? { record } : {}) };
-        },
-    };
+                path: `/snapshots/builds/${encodeURIComponent(buildId)}${waitQuery(opts.waitMs)}`,
+                ...this.readExtras(opts),
+            }),
+            buildLog: async (buildId, tail = 200) => {
+                const r = await this.request({
+                    method: "GET",
+                    path: `/snapshots/builds/${encodeURIComponent(buildId)}/build-log?tail=${Math.max(1, Math.floor(tail))}`,
+                });
+                return r?.log ?? [];
+            },
+            builds: async (limit = 20) => (await this.snapshots.buildsPage({ limit })).items,
+            buildsPage: async (opts = {}) => {
+                const limit = opts.limit ?? 20;
+                const r = await this.request({ method: "GET", path: `/snapshots/builds?${pageQuery(limit, 500, opts.cursor)}` });
+                return pageOf(r, "builds", limit);
+            },
+            get: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}` }),
+            list: async (opts = {}) => (await this.snapshots.listPage(opts)).items,
+            listPage: async (opts = {}) => {
+                const q = new URLSearchParams();
+                if (opts.limit !== undefined)
+                    q.set("limit", String(Math.max(1, Math.trunc(opts.limit))));
+                if (opts.cursor)
+                    q.set("cursor", opts.cursor);
+                const qs = q.toString();
+                const r = await this.request({
+                    method: "GET", path: `/snapshots${qs ? `?${qs}` : ""}`, ...(this.authenticated ? {} : { anonymous: true }),
+                });
+                if (Array.isArray(r))
+                    return { items: r, nextCursor: null, limit: opts.limit ?? r.length };
+                return { items: r?.snapshots ?? [], nextCursor: r?.next_cursor ?? null, limit: r?.limit ?? (opts.limit ?? 0) };
+            },
+            public: async (limit = 20) => {
+                const r = await this.request({
+                    method: "GET",
+                    path: `/snapshots?limit=${Math.max(1, Math.floor(limit))}`,
+                    anonymous: true,
+                });
+                const all = Array.isArray(r) ? r : (r?.snapshots ?? []);
+                return all.filter((s) => s.visibility === undefined || s.visibility === "public").slice(0, limit);
+            },
+            delete: (idOrAlias) => {
+                if (!idOrAlias)
+                    throw new InvalidArgumentError("snapshots.delete needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
+                return this.request({ method: "DELETE", path: `/snapshots/${seg(idOrAlias)}` });
+            },
+            alias: (idOrAlias, alias) => this.request({
+                method: "PUT",
+                path: `/snapshots/${seg(idOrAlias)}/alias`,
+                body: { alias },
+            }),
+            waitBuild: async (buildId, opts = {}) => {
+                const r = await this.waitLoop(opts, BUILD_POLL_MS, { build_id: buildId, state: "running" }, (read) => this.snapshots.status(buildId, read), (b) => b.state !== "running" && b.state !== "queued");
+                return { build: r.value, timedOut: r.timedOut, waitedMs: r.waitedMs };
+            },
+            verify: (id, opts = {}) => {
+                if (!id)
+                    throw new InvalidArgumentError("snapshots.verify needs a snapshot", "Pass a snap_ id, an alias, or alias@commit7.");
+                const body = {};
+                if (opts.timeoutMs !== undefined)
+                    body["timeout_ms"] = opts.timeoutMs;
+                if (opts.spendCap !== undefined)
+                    body["spend_cap"] = opts.spendCap;
+                return this.request({
+                    method: "POST",
+                    path: `/snapshots/${encodeURIComponent(id)}/verify`,
+                    body,
+                });
+            },
+            manifest: (idOrAlias) => this.request({ method: "GET", path: `/snapshots/${seg(idOrAlias)}/manifest` }),
+            bundle: async (idOrAlias, opts = {}) => {
+                const [record, m] = await Promise.all([
+                    this.snapshots.get(idOrAlias).catch(() => undefined),
+                    this.snapshots.manifest(idOrAlias),
+                ]);
+                if (!m?.manifest || typeof m.manifest !== "object") {
+                    throw new NotFoundError(`snapshot ${idOrAlias} has no manifest to export`, "Only a verified snapshot has one: check 'promigence snapshot inspect' first.");
+                }
+                const alias = opts.alias ?? record?.alias ?? undefined;
+                const bundle = buildBundle(m.manifest, { ...(alias ? { alias } : {}) });
+                return { bundle, served_by: "client", ...(record ? { record } : {}) };
+            },
+        };
+    }
+}
+const API_GROUPS = ["templates", "billing", "keys", "orgs", "credits", "github", "gitlab", "runs", "sandboxes", "secrets", "images", "captures", "snapshots"];
+function installLazyGroups(proto) {
+    for (const name of API_GROUPS) {
+        const build = `group_${name}`;
+        const own = (self, value) => {
+            Object.defineProperty(self, name, { value, writable: true, enumerable: true, configurable: true });
+        };
+        Object.defineProperty(proto, name, {
+            configurable: true,
+            enumerable: false,
+            get() {
+                const value = this[build].call(this);
+                own(this, value);
+                return value;
+            },
+            set(value) {
+                own(this, value);
+            },
+        });
+    }
 }
+installLazyGroups(PromigenceClient.prototype);
+const lazyGroupTypesMatch = [true, true, true, true, true, true, true, true, true, true, true, true, true];
+void lazyGroupTypesMatch;
 const POLL_LADDER_MS = [10, 25, 25, 25, 25, 25, 25, 25, 25, 50, 50, 50, 100, 100, 100, 200];
 function pollInterval(iteration) {
     const step = POLL_LADDER_MS[iteration];