@sandboxrouter/sdk 0.2.0 → 0.3.0

package/dist/providers/freestyle.js

@@ -0,0 +1,261 @@
+import { createHash } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { dirname, toBytes, wrapCommand } from "../util.js";
+/**
+ * Freestyle VMs over the public REST API (no SDK needed). Auth: Authorization: Bearer
+ * <FREESTYLE_API_KEY>, base https://api.freestyle.sh. Errors are {code, message}.
+ *   POST   /v5/vms                {snapshotId, firewall:{rules}, ttlSeconds, metadata}  -> Vm (201, booting)
+ *   GET    /v5/vms/:id            -> Vm {id, state: starting|running|pausing|paused|stopped, resources}
+ *   POST   /v5/vms/:id/exec-await {command, env, timeoutMs} -> {statusCode|null, stdout, stderr}
+ *   PUT    /v5/vms/:id/fs/write?path=P&sha256=H   raw bytes, atomic (204)
+ *   GET    /v5/vms/:id/fs/read?path=P             raw bytes (404 when missing; works while paused)
+ *   POST   /v5/vms/:id/fs/mkdir   {path}  (creates parents)
+ *   POST   /v5/vms/:id/pause, POST /v5/vms/:id/start, POST /v5/vms/:id/resize {cpu, memory(MiB)}
+ *   DELETE /v5/vms/:id
+ * Long calls: with `x-freestyle-background-after-secs: N` a request still running after N s
+ * answers 202 {requestId} and GET /v5/background-requests/:id replays its response once done (202
+ * while pending). That is what lets exec run past the 5-minute inline cap (up to 24 h).
+ * Sizes come from the base snapshot (FREESTYLE_SIZES): the adapter boots the smallest
+ * freestyle/ubuntu-* that fits. A custom image.freestyle (snapshot id/slug) boots at its own size
+ * and is grown with resize when the spec asks for more. A VM gets no network unless allowed, so the
+ * adapter opens outbound Internet, like other providers' defaults. exec has no streaming (output
+ * streams only over PTY WebSockets), so onStdout/onStderr get the whole output once it finishes.
+ * pause() keeps memory and disk; connect() and a paused exec start the VM again.
+ * Docs: https://www.freestyle.sh/docs/vms, https://www.freestyle.sh/docs/vms/lifecycle,
+ *       https://www.freestyle.sh/docs/vms/files, https://www.freestyle.sh/docs/vms/base-snapshots,
+ *       https://www.freestyle.sh/docs/vms/pricing-and-limits, https://www.freestyle.sh/openapi.json
+ */
+const ID = "freestyle";
+const BACKGROUND_AFTER_SECS = "5";
+const READY_TIMEOUT_MS = 3 * 60_000;
+const MAX_EXEC_MS = 86_400_000;
+const OUTBOUND_INTERNET = { rules: [{ action: "allow", source: {}, destination: { public: true } }] };
+/**
+ * Freestyle's Ubuntu base snapshots (hardware is baked into each), from
+ * https://www.freestyle.sh/docs/vms/base-snapshots, priced at the list rates on
+ * https://www.freestyle.sh/docs/vms/pricing-and-limits ($0.04032/vCPU-h, $0.0129/GiB-h memory,
+ * $0.000086/GiB-h disk), checked 2026-11-04. Free tops out at `ubuntu`, Hobby at `ubuntu-lg`,
+ * Pro at `ubuntu-2xl`.
+ */
+export const FREESTYLE_SIZES = [
+    { snapshot: "freestyle/ubuntu-sm", vcpu: 2, memoryGb: 4, diskGb: 16 },
+    { snapshot: "freestyle/ubuntu", vcpu: 4, memoryGb: 8, diskGb: 32 },
+    { snapshot: "freestyle/ubuntu-lg", vcpu: 8, memoryGb: 16, diskGb: 64 },
+    { snapshot: "freestyle/ubuntu-xl", vcpu: 16, memoryGb: 32, diskGb: 128 },
+    { snapshot: "freestyle/ubuntu-2xl", vcpu: 32, memoryGb: 64, diskGb: 128 },
+].map((s) => ({ ...s, usdHour: round(s.vcpu * 0.04032 + s.memoryGb * 0.0129 + s.diskGb * 0.000086) }));
+/** Smallest Ubuntu base snapshot with at least the requested vCPU and memory, or undefined. */
+export function freestyleSize(vcpu, memoryGb) {
+    return FREESTYLE_SIZES.find((s) => s.vcpu >= vcpu && s.memoryGb >= memoryGb);
+}
+export class FreestyleProvider {
+    apiKey;
+    baseUrl;
+    pollMs;
+    id = ID;
+    constructor(apiKey = process.env.FREESTYLE_API_KEY, baseUrl = process.env.FREESTYLE_API_URL ?? "https://api.freestyle.sh", 
+    /** How often to poll a backgrounded request or a booting VM. */
+    pollMs = 2000) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.pollMs = pollMs;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /**
+     * @internal One API call. With `background`, a call still running after 5 s comes back as 202
+     * and is polled at /v5/background-requests/:id until its own response is ready.
+     */
+    async request(method, path, init = {}) {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "FREESTYLE_API_KEY is not set");
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        if (init.background)
+            headers["x-freestyle-background-after-secs"] = BACKGROUND_AFTER_SECS;
+        let body;
+        if (init.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(init.json);
+        }
+        else if (init.bytes) {
+            headers["Content-Type"] = "application/octet-stream";
+            body = init.bytes;
+        }
+        let res = await fetch(`${this.baseUrl}${path}`, { method, headers, body, signal: init.signal });
+        if (init.background && res.status === 202) {
+            const accepted = (await res.json().catch(() => ({})));
+            const requestId = res.headers.get("x-freestyle-background-request-id") ?? accepted.requestId;
+            const resultPath = accepted.resultUrl ?? (requestId ? `/v5/background-requests/${encodeURIComponent(requestId)}` : undefined);
+            if (!resultPath)
+                throw new ProviderError(ID, `${method} ${path.split("?")[0]} -> 202 without a background request id`, 202);
+            for (;;) {
+                await sleep(this.pollMs, init.signal);
+                res = await fetch(resultPath.startsWith("http") ? resultPath : `${this.baseUrl}${resultPath}`, {
+                    headers: { Authorization: `Bearer ${this.apiKey}` },
+                    signal: init.signal,
+                });
+                if (res.status !== 202)
+                    break;
+                await res.body?.cancel().catch(() => { });
+            }
+        }
+        if (!res.ok) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                if (j?.message)
+                    detail = `${j.code ? `${j.code}: ` : ""}${j.message}`;
+            }
+            catch {
+                /* plain-text body */
+            }
+            throw new ProviderError(ID, `${method} ${path.split("?")[0]} -> ${res.status} ${detail}`, res.status);
+        }
+        return res;
+    }
+    /** @internal JSON call. */
+    async json(method, path, init = {}) {
+        const text = await (await this.request(method, path, init)).text();
+        return (text ? JSON.parse(text) : {});
+    }
+    async create(spec) {
+        const vcpu = spec.vcpu ?? 2;
+        const memoryGb = spec.memoryGb ?? 4;
+        const custom = spec.image?.freestyle;
+        const size = freestyleSize(vcpu, memoryGb);
+        if (!custom && !size)
+            throw new ProviderError(ID, `no Freestyle size has ${vcpu} vCPU / ${memoryGb} GB (max ubuntu-2xl: 32 vCPU / 64 GiB)`);
+        const body = {
+            snapshotId: custom ?? size.snapshot,
+            firewall: OUTBOUND_INTERNET,
+            ttlSeconds: Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)),
+        };
+        if (spec.metadata)
+            body.metadata = spec.metadata;
+        const vm = await this.json("POST", "/v5/vms", { json: body, background: true });
+        const box = new FreestyleBox(this, vm.id, spec.env);
+        try {
+            const ready = await box.waitRunning();
+            // A custom snapshot boots at its own size; grow it (resize is grow-only) when the spec wants more.
+            const res = ready.resources;
+            if (custom && res && (res.cpu < Math.ceil(vcpu) || res.memory < Math.ceil(memoryGb * 1024))) {
+                await this.json("POST", `/v5/vms/${encodeURIComponent(vm.id)}/resize`, {
+                    json: { cpu: Math.max(res.cpu, Math.ceil(vcpu)), memory: Math.max(res.memory, Math.ceil(memoryGb * 1024)) },
+                    background: true,
+                });
+            }
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    /** Reattach by VM id (or slug); a paused or stopped VM is started again. */
+    async connect(nativeId) {
+        const box = new FreestyleBox(this, nativeId);
+        await box.waitRunning();
+        return box;
+    }
+    /** @internal */
+    get poll() {
+        return this.pollMs;
+    }
+}
+class FreestyleBox {
+    p;
+    nativeId;
+    env;
+    constructor(p, nativeId, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.env = env;
+    }
+    get path() {
+        return `/v5/vms/${encodeURIComponent(this.nativeId)}`;
+    }
+    /** Wait until the VM runs, starting it when it is paused or stopped. */
+    async waitRunning() {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        let started = false;
+        for (;;) {
+            const vm = await this.p.json("GET", this.path);
+            if (vm.state === "running")
+                return vm;
+            if ((vm.state === "paused" || vm.state === "stopped") && !started) {
+                await this.p.json("POST", `${this.path}/start`, { background: true });
+                started = true;
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `VM ${this.nativeId} still ${vm.state} after ${READY_TIMEOUT_MS / 1000}s`);
+            await sleep(Math.min(this.p.poll, 500));
+        }
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const body = {
+            command: wrapCommand(cmd, { cwd: opts.cwd }),
+            timeoutMs: Math.min(MAX_EXEC_MS, Math.max(1, Math.round(secs * 1000))),
+        };
+        const env = { ...this.env, ...opts.env };
+        if (Object.keys(env).length)
+            body.env = env;
+        let r;
+        try {
+            r = await this.p.json("POST", `${this.path}/exec-await`, { json: body, background: true });
+        }
+        catch (err) {
+            // 409 also means "stopped responding mid-command" (VM_NON_RESPONSIVE): never re-run that one.
+            if (!(err instanceof ProviderError) || err.status !== 409 || /VM_NON_RESPONSIVE/.test(err.message))
+                throw err;
+            const vm = await this.p.json("GET", this.path);
+            if (vm.state === "running")
+                throw err;
+            await this.waitRunning();
+            r = await this.p.json("POST", `${this.path}/exec-await`, { json: body, background: true });
+        }
+        if (r.statusCode === null || r.statusCode === undefined)
+            throw new ProviderError(ID, `command timed out after ${secs}s`);
+        const stdout = r.stdout ?? "";
+        const stderr = r.stderr ?? "";
+        if (stdout)
+            opts.onStdout?.(stdout);
+        if (stderr)
+            opts.onStderr?.(stderr);
+        return { exitCode: r.statusCode, stdout, stderr, durationMs: Date.now() - t0 };
+    }
+    async writeFile(path, content) {
+        const bytes = toBytes(content);
+        // Best effort (whether mkdir of an existing directory errors is not documented); the write
+        // itself reports any real problem.
+        const dir = dirname(path);
+        if (dir !== "/")
+            await this.p.request("POST", `${this.path}/fs/mkdir`, { json: { path: dir }, background: true }).catch(() => { });
+        const q = new URLSearchParams({ path, sha256: createHash("sha256").update(bytes).digest("hex") });
+        await this.p.request("PUT", `${this.path}/fs/write?${q}`, { bytes, background: true });
+    }
+    async readFile(path) {
+        const res = await this.p.request("GET", `${this.path}/fs/read?${new URLSearchParams({ path })}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    async pause() {
+        await this.p.request("POST", `${this.path}/pause`, { background: true });
+    }
+    async kill() {
+        await this.p.request("DELETE", this.path);
+    }
+}
+function round(n) {
+    return Math.round(n * 1e5) / 1e5;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        // Not unref'd: between polls nothing else may keep the process alive.
+        const t = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => (clearTimeout(t), reject(signal.reason)), { once: true });
+    });
+}

package/dist/providers/hopx.js

@@ -1,5 +1,5 @@
 import { ProviderError } from "../types.js";
-import { optionalImport, toBytes } from "../util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, optionalImport, timeoutError, toBytes } from "../util.js";
 /** Public template used when spec.image.hopx is not set. */
 const DEFAULT_TEMPLATE = "code-interpreter";
 /**
@@ -54,9 +54,11 @@ class HopxBox {
         if (opts.onStdout || opts.onStderr)
             return this.execStreaming(cmd, opts);
         const t0 = Date.now();
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
         try {
+            // The agent kills the command at `timeout` and reports it as an EXECUTION_TIMEOUT error.
             const r = await this.sbx.commands.run(cmd, {
-                timeout: opts.timeoutSeconds ?? 60,
+                timeout: seconds,
                 workingDir: opts.cwd,
                 env: opts.env,
             });
@@ -64,23 +66,23 @@ class HopxBox {
             return { exitCode: r.exit_code ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "", durationMs: Date.now() - t0 };
         }
         catch (err) {
-            throw fail(err);
+            throw fail(err, seconds);
         }
     }
     /** Streams over the agent's WebSocket (/execute/stream) with the code run as bash. */
     async execStreaming(cmd, opts) {
         const t0 = Date.now();
-        const seconds = opts.timeoutSeconds ?? 60;
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
         let stdout = "";
         let stderr = "";
         let exitCode;
+        const stream = this.sbx.runCodeStream(cmd, {
+            language: "bash",
+            timeout: seconds,
+            workingDir: opts.cwd,
+            env: opts.env,
+        });
         const run = async () => {
-            const stream = this.sbx.runCodeStream(cmd, {
-                language: "bash",
-                timeout: seconds,
-                workingDir: opts.cwd,
-                env: opts.env,
-            });
             for await (const m of stream) {
                 if (m.type === "stdout") {
                     stdout += m.data;
@@ -94,23 +96,27 @@ class HopxBox {
                     exitCode = m.exit_code;
                 }
                 else if (m.type === "error") {
-                    const msg = m.code === "EXECUTION_TIMEOUT" ? `command timed out after ${seconds}s` : m.error;
-                    throw new ProviderError("hopx", msg);
+                    throw m.code === "EXECUTION_TIMEOUT" ? timeoutError("hopx", seconds) : new ProviderError("hopx", m.error);
                 }
             }
         };
         try {
             // The agent enforces the timeout; the extra grace covers a stream that never closes.
-            const graceMs = (seconds + 30) * 1000;
-            const timedOut = await Promise.race([run().then(() => false), sleep(graceMs).then(() => true)]);
-            if (timedOut)
-                throw new ProviderError("hopx", `command timed out after ${seconds}s`);
+            const graceMs = (seconds + 15) * 1000;
+            const finished = run();
+            const timedOut = await Promise.race([finished.then(() => false), sleep(graceMs).then(() => true)]);
+            if (timedOut) {
+                // Close the stream (and its WebSocket) now that nobody will read it.
+                finished.catch(() => { });
+                await stream.return?.().catch(() => { });
+                throw timeoutError("hopx", seconds);
+            }
             if (exitCode === undefined)
                 throw new ProviderError("hopx", "stream closed before the command finished");
             return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
         }
         catch (err) {
-            throw fail(err);
+            throw fail(err, seconds);
         }
     }
     async writeFile(path, content) {
@@ -157,9 +163,12 @@ const STATUS_BY_NAME = {
     FileNotFoundError: 404,
     SandboxExpiredError: 410,
 };
-function fail(err) {
+/** Map an SDK error; with `timeoutSeconds`, the agent's execution-timeout errors become the contract's timeout error. */
+function fail(err, timeoutSeconds) {
     if (err instanceof ProviderError)
         return err;
+    if (timeoutSeconds !== undefined && (err?.code === "EXECUTION_TIMEOUT" || err?.name === "TimeoutError"))
+        return timeoutError("hopx", timeoutSeconds);
     const status = err?.statusCode ?? err?.response?.status ?? STATUS_BY_NAME[err?.name];
     return new ProviderError("hopx", err?.message ?? String(err), status);
 }

package/dist/providers/instabox.d.ts

@@ -0,0 +1,76 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** Sizes on api.instabox.sh (vCPUs / GiB); which ones an org may use depends on its plan. */
+export declare const INSTABOX_SIZES: readonly [{
+    readonly vcpu: 2;
+    readonly memoryGb: 4;
+}, {
+    readonly vcpu: 4;
+    readonly memoryGb: 8;
+}, {
+    readonly vcpu: 8;
+    readonly memoryGb: 16;
+}, {
+    readonly vcpu: 16;
+    readonly memoryGb: 32;
+}, {
+    readonly vcpu: 32;
+    readonly memoryGb: 64;
+}];
+/** The smallest size with at least the requested vCPUs and memory, or undefined if none fits. */
+export declare function instaboxSize(vcpu: number, memoryGb: number): {
+    readonly vcpu: 2;
+    readonly memoryGb: 4;
+} | {
+    readonly vcpu: 4;
+    readonly memoryGb: 8;
+} | {
+    readonly vcpu: 8;
+    readonly memoryGb: 16;
+} | {
+    readonly vcpu: 16;
+    readonly memoryGb: 32;
+} | {
+    readonly vcpu: 32;
+    readonly memoryGb: 64;
+} | undefined;
+interface Operation {
+    id?: string;
+    machineId?: string;
+    type?: string;
+    state?: string;
+    phase?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        retryable?: boolean;
+        retryAfterSeconds?: number;
+    } | null;
+}
+export declare class InstaboxProvider implements Provider {
+    private apiKey;
+    private baseUrl;
+    readonly id: "instabox";
+    constructor(apiKey?: string | undefined, baseUrl?: string);
+    configured(): boolean;
+    /** @internal Send a request; non-2xx answers throw InstaboxError. */
+    request(method: string, path: string, init?: {
+        json?: unknown;
+        body?: Uint8Array;
+        headers?: Record<string, string>;
+        idempotent?: boolean;
+        timeoutMs?: number;
+    }): Promise<Response>;
+    /** @internal */
+    json<T>(method: string, path: string, json?: unknown, opts?: {
+        idempotent?: boolean;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /** @internal Follow an operation until it succeeds; a failed one throws. */
+    waitOperation(op: Operation, what: string): Promise<Operation>;
+    /** @internal Wait until the machine runs and takes commands, starting or resuming it when it is stopped or paused. */
+    ensureRunning(id: string): Promise<void>;
+    private createMachine;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}
+export {};