@sandboxrouter/sdk 0.2.0 → 0.3.0

package/dist/providers/azure.js

@@ -0,0 +1,330 @@
+import { randomBytes } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { dirname, killedByTimeout, shq, timeoutError, toBytes, wrapCommand } from "../util.js";
+/**
+ * Azure Container Apps dynamic sessions, Shell session pools (plain REST, no Azure SDK).
+ *
+ * A Shell pool is a built-in ("code interpreter" type) pool whose sessions are Hyper-V isolated
+ * Linux shells. A session is addressed by an identifier you choose; the first request with a new
+ * identifier allocates a session from the pool's prewarmed set.
+ *
+ *   POST   {endpoint}/executions?api-version=2025-10-02-preview&identifier={id}
+ *          {"shellCommand": "...", "timeoutInSeconds": N, "outputStreamsMaxLength": N}
+ *          -> {"id", "identifier", "status": "0" | "Succeeded" | ..., "result": {"stdout", "stderr", "executionTimeInMilliseconds"}}
+ *   POST   {endpoint}/files?api-version=...&identifier={id}          multipart field "file" (lands in /mnt/data, 128 MB max)
+ *   GET    {endpoint}/files/{name}/content?api-version=...&identifier={id}
+ *   GET    {endpoint}/session?api-version=...&identifier={id}        -> {identifier, expireAt, createdAt, lastAccessedAt, etag}
+ *   DELETE {endpoint}/session?api-version=...&identifier={id}        -> 204
+ * Auth: Authorization: Bearer <Entra token with aud https://dynamicsessions.io>, from an identity holding
+ * "Azure ContainerApps Session Executor" on the pool.
+ *
+ * Docs:
+ *   https://learn.microsoft.com/en-us/azure/container-apps/sessions-tutorial-shell
+ *   https://learn.microsoft.com/en-us/azure/container-apps/session-pool
+ *   https://learn.microsoft.com/en-us/azure/container-apps/sessions-usage
+ *   https://learn.microsoft.com/en-us/rest/api/data-plane/containerapps/code-execution/execute?view=rest-data-plane-containerapps-2025-10-02-preview
+ *   https://learn.microsoft.com/en-us/rest/api/data-plane/containerapps/session-resource-files/upload?view=rest-data-plane-containerapps-2025-10-02-preview
+ *   https://learn.microsoft.com/en-us/rest/api/data-plane/containerapps/session-management/delete?view=rest-data-plane-containerapps-2025-10-02-preview
+ *   https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow
+ *   Billing: https://learn.microsoft.com/en-us/azure/container-apps/billing#dynamic-sessions
+ *
+ * Custom container pools are not supported: their exec surface is whatever HTTP server your image
+ * runs, so there is no API to adapt to.
+ *
+ * What the API does not let us honour, and how the adapter copes:
+ * - Session size is fixed by the platform (not published); vcpu/memoryGb are ignored, and the catalog
+ *   caps limits so bigger requests route elsewhere.
+ * - Lifetime is the pool's cooldown (300-3600 s idle), not per session; timeoutMinutes is ignored. kill()
+ *   deletes the session at once.
+ * - No env API: spec.env and opts.env are exported in front of each command.
+ * - stdout/stderr are capped per response (outputStreamsMaxLength, default 4096). exec writes output to
+ *   files in the session and returns it inline when it fits, otherwise downloads the files. No streaming:
+ *   onStdout/onStderr get the whole output once, at the end.
+ *
+ * ## Setup (once)
+ *
+ *   az extension add --name containerapp --upgrade --allow-preview true
+ *   az provider register --namespace Microsoft.App
+ *   # Shell pool via ARM (see the shell tutorial for deploy.json): "containerType": "Shell",
+ *   # "poolManagementType": "Dynamic", lifecycleConfiguration {"lifecycleType": "Timed",
+ *   # "cooldownPeriodInSeconds": 300}, sessionNetworkConfiguration {"status": "EgressEnabled"}
+ *   az deployment group create -g <rg> --template-file deploy.json
+ *   az containerapp sessionpool show -n <pool> -g <rg> --query properties.poolManagementEndpoint -o tsv
+ *   az role assignment create --role "Azure ContainerApps Session Executor" \
+ *     --assignee <principal-id> --scope <pool-resource-id>
+ *
+ * Then set AZURE_SESSIONS_POOL_ENDPOINT to the endpoint, and either AZURE_SESSIONS_TOKEN
+ * (`az account get-access-token --resource https://dynamicsessions.io --query accessToken -o tsv`,
+ * expires in about an hour) or a service principal: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET.
+ */
+const ID = "azure";
+const AUDIENCE = "https://dynamicsessions.io";
+const DEFAULT_API_VERSION = "2025-10-02-preview";
+/** Identifier: 4-128 chars; we only ever generate [a-z0-9-]. */
+const IDENTIFIER = /^[A-Za-z0-9|\-&^%$#(){}[\];<>]{4,128}$/;
+export class AzureSessionsProvider {
+    id = ID;
+    /** @internal */ endpoint;
+    /** @internal */ apiVersion;
+    /** @internal */ filesDir;
+    /** @internal */ outputCap;
+    staticToken;
+    tenantId;
+    clientId;
+    clientSecret;
+    authorityHost;
+    cached;
+    constructor(opts = {}) {
+        this.endpoint = (opts.endpoint ?? process.env.AZURE_SESSIONS_POOL_ENDPOINT)?.replace(/\/+$/, "");
+        this.staticToken = opts.token ?? process.env.AZURE_SESSIONS_TOKEN;
+        this.tenantId = opts.tenantId ?? process.env.AZURE_TENANT_ID;
+        this.clientId = opts.clientId ?? process.env.AZURE_CLIENT_ID;
+        this.clientSecret = opts.clientSecret ?? process.env.AZURE_CLIENT_SECRET;
+        this.authorityHost = (opts.authorityHost ?? process.env.AZURE_AUTHORITY_HOST ?? "https://login.microsoftonline.com").replace(/\/+$/, "");
+        this.apiVersion = opts.apiVersion ?? process.env.AZURE_SESSIONS_API_VERSION ?? DEFAULT_API_VERSION;
+        this.filesDir = (opts.filesDir ?? process.env.AZURE_SESSIONS_FILES_DIR ?? "/mnt/data").replace(/\/+$/, "");
+        this.outputCap = opts.outputCap ?? 4096;
+    }
+    configured() {
+        return !!this.endpoint && (!!this.staticToken || !!(this.tenantId && this.clientId && this.clientSecret));
+    }
+    /** @internal Bearer token: the static one, or a cached client-credentials token. */
+    async token() {
+        if (this.staticToken)
+            return this.staticToken;
+        if (!(this.tenantId && this.clientId && this.clientSecret)) {
+            throw new ProviderError(ID, "set AZURE_SESSIONS_TOKEN, or AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET");
+        }
+        if (this.cached && this.cached.expiresAt - 300_000 > Date.now())
+            return this.cached.token;
+        const res = await fetch(`${this.authorityHost}/${encodeURIComponent(this.tenantId)}/oauth2/v2.0/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "client_credentials",
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                scope: `${AUDIENCE}/.default`,
+            }),
+        });
+        const text = await res.text();
+        let j = {};
+        try {
+            j = JSON.parse(text);
+        }
+        catch {
+            /* not JSON */
+        }
+        if (!res.ok || !j.access_token) {
+            throw new ProviderError(ID, `Entra token -> ${res.status} ${j.error_description ?? j.error ?? text.slice(0, 200)}`, res.status);
+        }
+        this.cached = { token: j.access_token, expiresAt: Date.now() + Number(j.expires_in ?? 3600) * 1000 };
+        return j.access_token;
+    }
+    /** @internal One data-plane call. Throws ProviderError on non-2xx. */
+    async call(method, path, identifier, init = {}) {
+        if (!this.endpoint)
+            throw new ProviderError(ID, "AZURE_SESSIONS_POOL_ENDPOINT is not set (see src/providers/azure.ts for the pool setup)");
+        const qs = new URLSearchParams({ "api-version": this.apiVersion, identifier });
+        const headers = { Authorization: `Bearer ${await this.token()}` };
+        let body;
+        if (init.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        else if (init.form) {
+            body = init.form; // fetch sets the multipart boundary
+        }
+        let res;
+        try {
+            res = await fetch(`${this.endpoint}/${path}?${qs}`, {
+                method,
+                headers,
+                body,
+                signal: init.timeoutMs ? AbortSignal.timeout(init.timeoutMs) : undefined,
+            });
+        }
+        catch (err) {
+            throw new ProviderError(ID, `${method} ${path}: ${err.message}`);
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let code = "";
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                code = j?.error?.code ?? "";
+                detail = j?.error?.message ?? j?.message ?? detail;
+            }
+            catch {
+                /* plain text */
+            }
+            // An unknown or expired identifier answers 400 SessionWithIdentifierNotFound; surface it as 404.
+            const status = code === "SessionWithIdentifierNotFound" ? 404 : res.status;
+            throw new ProviderError(ID, `${method} ${path} -> ${res.status} ${code ? `${code}: ` : ""}${detail}`.trim(), status);
+        }
+        return res;
+    }
+    async create(spec) {
+        const box = new AzureSession(this, `sbr-${randomBytes(12).toString("hex")}`, spec.env);
+        // The first request with a new identifier allocates the session; prove it runs commands.
+        const r = await box.exec("true", { timeoutSeconds: 30 });
+        if (r.exitCode !== 0) {
+            await box.kill().catch(() => { });
+            throw new ProviderError(ID, `new session did not run a command (exit ${r.exitCode}): ${r.stderr.trim()}`);
+        }
+        return box;
+    }
+    async connect(nativeId) {
+        if (!IDENTIFIER.test(nativeId))
+            throw new ProviderError(ID, `invalid session identifier: ${nativeId}`);
+        // GET /session does not allocate; an unknown identifier fails instead of starting a fresh session.
+        await this.call("GET", "session", nativeId);
+        return new AzureSession(this, nativeId);
+    }
+}
+class AzureSession {
+    p;
+    nativeId;
+    env;
+    constructor(p, nativeId, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.env = env;
+    }
+    /** @internal One shellCommand execution, returned raw. */
+    async run(shellCommand, timeoutSeconds) {
+        const res = await this.p.call("POST", "executions", this.nativeId, {
+            json: { shellCommand, timeoutInSeconds: timeoutSeconds, outputStreamsMaxLength: this.p.outputCap },
+            timeoutMs: (timeoutSeconds + 60) * 1000,
+        });
+        const j = (await res.json());
+        if (j.status === "Failed" || j.status === "Canceled") {
+            const e = j.error;
+            throw new ProviderError(ID, `execution ${j.status.toLowerCase()}: ${e?.error?.message ?? e?.message ?? "no detail"}`);
+        }
+        return j;
+    }
+    /** Run a short helper script; throws with its stderr when it fails. */
+    async sh(script, what) {
+        const r = await this.run(script, 120);
+        const code = statusCode(r.status);
+        if (code !== undefined && code !== 0)
+            throw new ProviderError(ID, `${what}: ${(r.result?.stderr ?? "").trim() || `exit ${code}`}`);
+        return r.result?.stdout ?? "";
+    }
+    /**
+     * The command runs with stdout/stderr redirected to files under filesDir. A trailer on stdout
+     * reports the exit code and whether the output came inline (it fit under the response cap) or must
+     * be downloaded through the files API.
+     */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const timeout = Math.max(1, Math.round(opts.timeoutSeconds ?? 60));
+        const job = `sbr-${randomBytes(8).toString("hex")}`;
+        const fd = this.p.filesDir;
+        const base = `${fd}/${job}`;
+        const marker = `__SBR_DONE_${job}__`;
+        const full = wrapCommand(cmd, { cwd: opts.cwd, env: { ...this.env, ...opts.env } });
+        const b64 = Buffer.from(full).toString("base64");
+        const inlineMax = Math.max(0, this.p.outputCap - marker.length - 32);
+        const script = [
+            `mkdir -p ${shq(fd)} && echo ${b64} | base64 -d > ${shq(`${base}.sh`)} || exit 97`,
+            `timeout -k 5 ${timeout} bash ${shq(`${base}.sh`)} > ${shq(`${base}.out`)} 2> ${shq(`${base}.err`)} < /dev/null`,
+            `c=$?`,
+            `so=$(stat -c %s ${shq(`${base}.out`)}); se=$(stat -c %s ${shq(`${base}.err`)})`,
+            `if [ $((so + se)) -le ${inlineMax} ]; then`,
+            `  cat ${shq(`${base}.out`)}; cat ${shq(`${base}.err`)} >&2; rm -f ${shq(base)}.*; i=1`,
+            `else rm -f ${shq(`${base}.sh`)}; i=0; fi`,
+            `printf '\\n${marker} %d %d' "$c" "$i"`,
+            `exit 0`,
+        ].join("\n");
+        const r = await this.run(script, timeout + 30);
+        let stdout = r.result?.stdout ?? "";
+        let stderr = r.result?.stderr ?? "";
+        const m = new RegExp(`\\n${marker} (\\d+) ([01])$`).exec(stdout);
+        let exitCode;
+        if (!m) {
+            // The wrapper itself did not finish (killed, or the platform timed it out): report what came back.
+            exitCode = statusCode(r.status) ?? 1;
+            if (exitCode === 0)
+                exitCode = 1;
+        }
+        else {
+            exitCode = Number(m[1]);
+            stdout = stdout.slice(0, m.index);
+            if (m[2] === "0") {
+                stdout = new TextDecoder().decode(await this.download(`${job}.out`));
+                stderr = new TextDecoder().decode(await this.download(`${job}.err`));
+                await this.sh(`rm -f ${shq(base)}.*`, "cleanup").catch(() => { });
+            }
+        }
+        if (stdout)
+            opts.onStdout?.(stdout);
+        if (stderr)
+            opts.onStderr?.(stderr);
+        const durationMs = Date.now() - t0;
+        // `timeout -k 5` leaves exit 124 (or 137 after SIGKILL) when it had to stop the command.
+        if (killedByTimeout(exitCode, durationMs, timeout))
+            throw timeoutError(ID, timeout);
+        return { exitCode, stdout, stderr, durationMs };
+    }
+    /** GET files/{name}/content for a file directly under filesDir. */
+    async download(name) {
+        const res = await this.p.call("GET", `files/${encodeURIComponent(name)}/content`, this.nativeId);
+        const buf = new Uint8Array(await res.arrayBuffer());
+        // The reference example shows the content as a JSON string; unwrap it only when it is one.
+        if (res.headers.get("content-type")?.includes("application/json")) {
+            try {
+                const v = JSON.parse(new TextDecoder().decode(buf));
+                if (typeof v === "string")
+                    return new TextEncoder().encode(v);
+            }
+            catch {
+                /* raw bytes */
+            }
+        }
+        return buf;
+    }
+    /** Upload into filesDir through the files API, then move it into place. */
+    async writeFile(path, content) {
+        const name = `sbr-${randomBytes(8).toString("hex")}.upload`;
+        const form = new FormData();
+        form.append("file", new Blob([Buffer.from(toBytes(content))], { type: "application/octet-stream" }), name);
+        await this.p.call("POST", "files", this.nativeId, { form, timeoutMs: 300_000 });
+        const staged = `${this.p.filesDir}/${name}`;
+        await this.sh(`mkdir -p ${shq(dirname(path))} && mv -f ${shq(staged)} ${shq(path)}`, `writeFile ${path}`);
+    }
+    /** Copy into filesDir, download through the files API, then remove the copy. */
+    async readFile(path) {
+        const name = `sbr-${randomBytes(8).toString("hex")}.download`;
+        const staged = `${this.p.filesDir}/${name}`;
+        await this.sh(`mkdir -p ${shq(this.p.filesDir)} && cp -f -- ${shq(path)} ${shq(staged)}`, `readFile ${path}`);
+        try {
+            return await this.download(name);
+        }
+        finally {
+            await this.sh(`rm -f ${shq(staged)}`, "cleanup").catch(() => { });
+        }
+    }
+    async kill() {
+        try {
+            await this.p.call("DELETE", "session", this.nativeId);
+        }
+        catch (err) {
+            if (err instanceof ProviderError && err.status === 404)
+                return; // already gone
+            throw err;
+        }
+    }
+}
+/** Shell pools put the exit code in `status` ("0"); other pools use OperationState names. */
+function statusCode(status) {
+    if (status === undefined)
+        return undefined;
+    if (/^-?\d+$/.test(status))
+        return Number(status);
+    if (status === "Succeeded")
+        return 0;
+    return undefined;
+}

package/dist/providers/beam.d.ts

@@ -0,0 +1,11 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+export declare class BeamProvider implements Provider {
+    private token;
+    private workspaceId;
+    readonly id: "beam";
+    constructor(token?: string | undefined, workspaceId?: string | undefined);
+    configured(): boolean;
+    private beam;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/beam.js

@@ -0,0 +1,179 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { DEFAULT_EXEC_TIMEOUT_S, dirname, optionalImport, shq, timeoutError, toBytes } from "../util.js";
+/**
+ * Beam (beam.cloud) sandboxes via the official `@beamcloud/beam-js` SDK (checked against 1.1.6).
+ * Auth: BEAM_TOKEN and BEAM_WORKSPACE_ID (the TS SDK refuses requests without the workspace id).
+ *   new Sandbox({ name, cpu, memory: MiB, gpu?, image?, keepWarmSeconds, env }).create()
+ *       -> SandboxInstance (containerId is the sandbox id)
+ *   Sandbox.connect(id)                       reattach by id
+ *   instance.execShell(text, { cwd, env, wait })  start a process; .wait() -> exit code,
+ *       .stdout / .stderr are polled streams (async-iterable by line, or .read() for all so far)
+ *   instance.fs.writeBytes(path, buf) / fs.readBytes(path)
+ *   instance.terminate()
+ * keepWarmSeconds is the sandbox's TTL, not an idle timeout, so it carries timeoutMinutes.
+ * There is no pause: snapshot() + Sandbox.createFromSnapshot() restores into a NEW sandbox id, so
+ * it can't back router.get(); the pause/resume Beam documents is for its separate VM product.
+ * GPUs: spec.gpu is passed straight to Beam's `gpu` (e.g. "T4", "A10G", "A100-40", "H100",
+ * "RTX4090"). The catalog doesn't list "gpu" for beam because GPU sandboxes bill different rates.
+ * The SDK keeps its auth in a module-global (`beamOpts`) and caches its HTTP client on the first
+ * request, so one process can only talk to one Beam token/workspace.
+ * Docs: https://docs.beam.cloud/v2/reference/ts-sdk, https://docs.beam.cloud/v2/sandbox/configuration,
+ *       https://docs.beam.cloud/v2/getting-started/quickstart-sandbox, https://www.beam.cloud/pricing,
+ *       https://github.com/beam-cloud/beam-client/tree/master/js
+ */
+const ID = "beam";
+/** Beam groups sandboxes under an app name. */
+const APP_NAME = process.env.SANDBOXROUTER_BEAM_APP ?? "sandboxrouter";
+function fail(err, what) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = err?.response?.status;
+    const detail = err?.response?.data?.errorMsg || err?.response?.data?.message || err?.message || String(err);
+    return new ProviderError(ID, `${what}: ${detail}`, status);
+}
+export class BeamProvider {
+    token;
+    workspaceId;
+    id = ID;
+    constructor(token = process.env.BEAM_TOKEN, workspaceId = process.env.BEAM_WORKSPACE_ID) {
+        this.token = token;
+        this.workspaceId = workspaceId;
+    }
+    configured() {
+        return !!this.token && !!this.workspaceId;
+    }
+    async beam() {
+        if (!this.token || !this.workspaceId)
+            throw new ProviderError(ID, "BEAM_TOKEN and BEAM_WORKSPACE_ID must both be set");
+        const mod = await optionalImport("@beamcloud/beam-js", ID);
+        mod.beamOpts.token = this.token;
+        mod.beamOpts.workspaceId = this.workspaceId;
+        return mod;
+    }
+    async create(spec) {
+        const { Sandbox, Image } = await this.beam();
+        const image = spec.image?.beam;
+        const config = {
+            name: APP_NAME,
+            cpu: spec.vcpu ?? DEFAULT_VCPU,
+            memory: Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024), // MiB
+            keepWarmSeconds: Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)),
+            env: spec.env ?? {},
+        };
+        if (image)
+            config.image = Image.fromRegistry(image);
+        if (spec.gpu)
+            config.gpu = spec.gpu;
+        try {
+            const sb = await new Sandbox(config).create();
+            return new BeamBox(sb, spec.env);
+        }
+        catch (err) {
+            throw fail(err, "create");
+        }
+    }
+    async connect(nativeId) {
+        const { Sandbox } = await this.beam();
+        try {
+            return new BeamBox(await Sandbox.connect(nativeId));
+        }
+        catch (err) {
+            throw fail(err, `connect ${nativeId}`);
+        }
+    }
+}
+/** Drain a Beam output stream line by line, passing each line to `on`. */
+async function drain(stream, on) {
+    let out = "";
+    for await (const line of stream) {
+        out += line;
+        on?.(line);
+    }
+    return out;
+}
+class BeamBox {
+    sb;
+    env;
+    nativeId;
+    constructor(sb, env) {
+        this.sb = sb;
+        this.env = env;
+        this.nativeId = sb.containerId;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        const limit = seconds * 1000;
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        const env = this.env || opts.env ? { ...this.env, ...opts.env } : undefined;
+        let proc;
+        try {
+            // Never `wait: true`: that call returns only when the command exits, so the deadline below
+            // could not start until it was already too late to enforce.
+            proc = await this.sb.execShell(cmd, { cwd: opts.cwd, env, wait: false });
+        }
+        catch (err) {
+            throw fail(err, "exec");
+        }
+        const work = (async () => {
+            if (streaming) {
+                const [stdout, stderr] = await Promise.all([drain(proc.stdout, opts.onStdout), drain(proc.stderr, opts.onStderr)]);
+                return { exitCode: await proc.wait(), stdout, stderr };
+            }
+            const exitCode = await proc.wait();
+            const [stdout, stderr] = await Promise.all([proc.stdout.read(), proc.stderr.read()]);
+            return { exitCode, stdout, stderr };
+        })();
+        let timer;
+        const timeout = new Promise((resolve) => (timer = setTimeout(() => resolve("timeout"), limit)));
+        try {
+            const r = await Promise.race([work, timeout]);
+            if (r === "timeout") {
+                work.catch(() => { });
+                await proc.kill().catch(() => { });
+                throw timeoutError(ID, seconds);
+            }
+            return { ...r, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw fail(err, "exec");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async writeFile(path, content) {
+        const buf = Buffer.from(toBytes(content));
+        try {
+            await this.sb.fs.writeBytes(path, buf);
+        }
+        catch {
+            // Most likely a missing parent directory: create it and try once more.
+            try {
+                const p = await this.sb.execShell(`mkdir -p ${shq(dirname(path))}`, { wait: true });
+                await p.wait();
+                await this.sb.fs.writeBytes(path, buf);
+            }
+            catch (err) {
+                throw fail(err, `write ${path}`);
+            }
+        }
+    }
+    async readFile(path) {
+        try {
+            return new Uint8Array(await this.sb.fs.readBytes(path));
+        }
+        catch (err) {
+            throw fail(err, `read ${path}`);
+        }
+    }
+    async kill() {
+        try {
+            await this.sb.terminate();
+        }
+        catch (err) {
+            throw fail(err, "terminate");
+        }
+    }
+}

package/dist/providers/blaxel.d.ts

@@ -3,7 +3,9 @@ import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.
  * Blaxel sandboxes via `@blaxel/core`. Auth: BL_API_KEY + BL_WORKSPACE (or `bl login`).
  * Region: BL_REGION, else us-pdx-1. Blaxel sizes by memory only and gives 1 vCPU per 2 GB,
  * so memory is max(memoryGb, 2 × vcpu) GB. Idle sandboxes drop to standby on their own and
- * wake on the next call; pause() archives explicitly.
+ * wake on the next call. No pause(): archiving is a preview Blaxel enables per workspace (others
+ * get 403 "Archiving a sandbox is in preview and is not enabled for this workspace", 2026-11-05).
+ * kill() waits until the sandbox is gone, because Blaxel deletes asynchronously.
  */
 export declare class BlaxelProvider implements Provider {
     private apiKey;

package/dist/providers/blaxel.js

@@ -1,6 +1,6 @@
 import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
 import { ProviderError } from "../types.js";
-import { optionalImport, toBytes } from "../util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, optionalImport, timeoutError, toBytes } from "../util.js";
 /** Blaxel's public base image (the SDK's own default). Set image.blaxel for another image or a `bl deploy` template. */
 const DEFAULT_IMAGE = "blaxel/base-image:latest";
 /** Blaxel rejects a max-age ttl under 5 minutes. */
@@ -9,7 +9,9 @@ const MIN_TTL_MINUTES = 5;
  * Blaxel sandboxes via `@blaxel/core`. Auth: BL_API_KEY + BL_WORKSPACE (or `bl login`).
  * Region: BL_REGION, else us-pdx-1. Blaxel sizes by memory only and gives 1 vCPU per 2 GB,
  * so memory is max(memoryGb, 2 × vcpu) GB. Idle sandboxes drop to standby on their own and
- * wake on the next call; pause() archives explicitly.
+ * wake on the next call. No pause(): archiving is a preview Blaxel enables per workspace (others
+ * get 403 "Archiving a sandbox is in preview and is not enabled for this workspace", 2026-11-05).
+ * kill() waits until the sandbox is gone, because Blaxel deletes asynchronously.
  */
 export class BlaxelProvider {
     apiKey;
@@ -80,10 +82,11 @@ class BlaxelBox {
     }
     async exec(cmd, opts = {}) {
         const t0 = Date.now();
-        const timeoutSeconds = opts.timeoutSeconds ?? 60;
+        const timeoutSeconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
         let r;
         try {
             // With onStdout/onStderr the SDK streams logs from the same request as the command runs.
+            // The sandbox kills the command at `timeout` and reports it with status "killed".
             r = await this.sbx.process.exec({
                 command: cmd,
                 workingDir: opts.cwd,
@@ -94,13 +97,19 @@ class BlaxelBox {
                 onStderr: opts.onStderr,
             });
             if (r.status === "running")
-                r = await this.sbx.process.wait(r.pid, { maxWait: timeoutSeconds * 1000 });
+                r = await this.sbx.process.wait(r.pid, { maxWait: (timeoutSeconds + 15) * 1000 });
         }
         catch (err) {
-            throw wrap(err);
+            const e = wrap(err);
+            // A real account answers a command that passes its limit with 422 "process timed out after N seconds".
+            if (e.status === 422 && /timed out/i.test(e.message))
+                throw timeoutError("blaxel", timeoutSeconds);
+            throw e;
         }
         if (r.status === "killed" || r.status === "stopped") {
-            throw new ProviderError("blaxel", `command ${r.status} (timeout ${timeoutSeconds}s?)`);
+            if (Date.now() - t0 >= timeoutSeconds * 1000 - 250)
+                throw timeoutError("blaxel", timeoutSeconds);
+            throw new ProviderError("blaxel", `command ${r.status} before it finished`);
         }
         // A nonzero exit is a result (status "failed"), not an error.
         return { exitCode: r.exitCode, stdout: r.stdout ?? "", stderr: r.stderr ?? "", durationMs: Date.now() - t0 };
@@ -121,20 +130,6 @@ class BlaxelBox {
             throw wrap(err);
         }
     }
-    /**
-     * Archive: the filesystem is kept, memory and processes are lost. The max-age ttl is cleared
-     * first so the archive survives until kill(). router.get() unarchives it.
-     */
-    async pause() {
-        const { SandboxInstance } = await optionalImport("@blaxel/core", "blaxel");
-        try {
-            await SandboxInstance.updateTtl(this.nativeId, null);
-            await this.sbx.archive();
-        }
-        catch (err) {
-            throw wrap(err);
-        }
-    }
     async kill() {
         try {
             await this.sbx.delete();
@@ -142,11 +137,26 @@ class BlaxelBox {
         catch (err) {
             throw wrap(err);
         }
+        // Deletion is asynchronous: wait (up to 20 s) until the sandbox is gone or terminated.
+        const { SandboxInstance } = await optionalImport("@blaxel/core", "blaxel");
+        for (let i = 0; i < 40; i++) {
+            try {
+                const s = await SandboxInstance.get(this.nativeId);
+                if (s.status === "TERMINATED")
+                    return;
+            }
+            catch {
+                return;
+            }
+            await new Promise((r) => setTimeout(r, 500));
+        }
     }
 }
 function wrap(err) {
     if (err instanceof ProviderError)
         return err;
-    const status = typeof err?.status === "number" ? err.status : err?.response?.status;
-    return new ProviderError("blaxel", err?.message ?? String(err), status);
+    const status = typeof err?.status === "number" ? err.status : typeof err?.code === "number" ? err.code : err?.response?.status;
+    // The SDK sometimes throws the plain API body ({ code, error }), not an Error.
+    const message = err?.message ?? err?.error ?? (typeof err === "object" ? JSON.stringify(err) : String(err));
+    return new ProviderError("blaxel", message, status);
 }

package/dist/providers/boat.js

@@ -1,6 +1,6 @@
 import { BOAT_SIZES } from "../catalog.js";
 import { ProviderError } from "../types.js";
-import { dirname, shq, toBytes, wrapCommand } from "../util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, dirname, killedByTimeout, shq, timeoutError, toBytes, wrapCommand } from "../util.js";
 /**
  * Boat (boat.dev) over plain REST. One host, one key: Authorization: Bearer boat_... (BOAT_API_KEY).
  *   POST   /sandboxes                         create (202, state "provisioning"); poll GET until ready
@@ -158,9 +158,11 @@ class BoatSandbox {
     async exec(cmd, opts = {}) {
         const t0 = Date.now();
         const streaming = !!(opts.onStdout || opts.onStderr);
+        // Boat caps a command at 600 s; it stops the command at the deadline and flags it as timedOut.
+        const seconds = Math.min(600, Math.max(1, Math.round(opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S)));
         const res = await this.call("POST", "/commands", {
             command: wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }),
-            timeoutSeconds: Math.min(600, Math.max(1, Math.round(opts.timeoutSeconds ?? 60))),
+            timeoutSeconds: seconds,
             stream: streaming,
         });
         let result;
@@ -194,7 +196,10 @@ class BoatSandbox {
             if (result.stderr)
                 opts.onStderr?.(result.stderr);
         }
-        return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", durationMs: Date.now() - t0 };
+        const durationMs = Date.now() - t0;
+        if (result.timedOut || killedByTimeout(result.exitCode ?? -1, durationMs, seconds))
+            throw timeoutError(ID, seconds);
+        return { exitCode: result.exitCode ?? -1, stdout: result.stdout ?? "", stderr: result.stderr ?? "", durationMs };
     }
     async writeFile(path, content) {
         const b64 = Buffer.from(toBytes(content)).toString("base64");