@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/dist/providers/morph.js

@@ -0,0 +1,181 @@
+import { ProviderError } from "../types.js";
+import { dirname, optionalImport, shq, toBytes, wrapCommand } from "../util.js";
+/** Base image for the default snapshot (Morph's minimal Ubuntu VM). */
+const BASE_IMAGE = "morphvm-minimal";
+const DISK_MB = 8192;
+/** spec.env lives here inside the VM so it survives connect(); every exec sources it. */
+const ENV_FILE = "/etc/sandboxrouter.env";
+const READY_TIMEOUT_S = 300;
+/**
+ * Morph Cloud via `morphcloud`. Instances start from snapshots: by default a cached snapshot of
+ * morphvm-minimal sized to spec.vcpu / spec.memoryGb; set image.morph to a snapshot id to start
+ * from your own (its resources come from the snapshot).
+ */
+export class MorphProvider {
+    apiKey;
+    id = "morph";
+    client;
+    constructor(apiKey = process.env.MORPH_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async morph() {
+        if (!this.client) {
+            const { MorphCloudClient } = await optionalImport("morphcloud", "morph");
+            this.client = new MorphCloudClient({ apiKey: this.apiKey });
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const m = await this.morph();
+        try {
+            const snapshotId = spec.image?.morph ?? (await this.baseSnapshot(m, spec));
+            const inst = await m.instances.start({
+                snapshotId,
+                metadata: spec.metadata,
+                ttlSeconds: Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)),
+                ttlAction: "stop",
+                timeout: READY_TIMEOUT_S,
+            });
+            const box = new MorphBox(inst);
+            if (spec.env && Object.keys(spec.env).length) {
+                try {
+                    await box.writeFile(ENV_FILE, envFile(spec.env));
+                }
+                catch (err) {
+                    await inst.stop().catch(() => { });
+                    throw err;
+                }
+            }
+            return box;
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reattach; a paused instance is resumed. */
+    async connect(nativeId) {
+        const m = await this.morph();
+        try {
+            const inst = await m.instances.get({ instanceId: nativeId });
+            if (String(inst.status) === "paused")
+                await inst.resume();
+            if (String(inst.status) !== "ready")
+                await inst.waitUntilReady(READY_TIMEOUT_S);
+            return new MorphBox(inst);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reuse (or create once) a morphvm-minimal snapshot with this shape, keyed by digest. */
+    async baseSnapshot(m, spec) {
+        const vcpus = spec.vcpu ?? 2;
+        const memory = Math.round((spec.memoryGb ?? 4) * 1024);
+        const digest = `sandboxrouter-${BASE_IMAGE}-${vcpus}c-${memory}m-${DISK_MB}d`;
+        const existing = (await m.snapshots.list({ digest })).find((s) => String(s.status) === "ready");
+        if (existing)
+            return existing.id;
+        let snap = await m.snapshots.create({ imageId: BASE_IMAGE, vcpus, memory, diskSize: DISK_MB, digest });
+        const t0 = Date.now();
+        while (String(snap.status) === "pending") {
+            if (Date.now() - t0 > READY_TIMEOUT_S * 1000)
+                throw new ProviderError("morph", `snapshot ${snap.id} not ready`);
+            await sleep(1000);
+            snap = await m.snapshots.get({ snapshotId: snap.id });
+        }
+        if (String(snap.status) !== "ready")
+            throw new ProviderError("morph", `snapshot ${snap.id} is ${snap.status}`);
+        return snap.id;
+    }
+}
+class MorphBox {
+    inst;
+    nativeId;
+    constructor(inst) {
+        this.inst = inst;
+        this.nativeId = inst.id;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const script = `[ -r ${ENV_FILE} ] && . ${ENV_FILE}; ${wrapCommand(cmd, { cwd: opts.cwd, env: opts.env })}`;
+        try {
+            // With callbacks the SDK switches to its SSE endpoint and streams; otherwise one request.
+            const r = await this.inst.exec(["sh", "-c", script], {
+                timeout: opts.timeoutSeconds ?? 60,
+                onStdout: opts.onStdout,
+                onStderr: opts.onStderr,
+            });
+            return { exitCode: r.exit_code, stdout: r.stdout ?? "", stderr: r.stderr ?? "", durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Over SSH: base64 on stdin, decoded in the VM (parent dirs created). */
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        const r = await this.ssh((s) => s.execCommand(`mkdir -p ${shq(dirname(path))} && base64 -d > ${shq(path)}${path === ENV_FILE ? ` && chmod 600 ${ENV_FILE}` : ""}`, { stdin: b64 }));
+        if (r.code !== 0)
+            throw new ProviderError("morph", `writeFile ${path}: ${r.stderr || `exit ${r.code}`}`);
+    }
+    async readFile(path) {
+        const r = await this.ssh((s) => s.execCommand(`base64 < ${shq(path)}`));
+        if (r.code !== 0)
+            throw new ProviderError("morph", `readFile ${path}: ${r.stderr || `exit ${r.code}`}`);
+        return new Uint8Array(Buffer.from(r.stdout, "base64"));
+    }
+    /** Snapshot memory and disk. router.get() resumes it. */
+    async pause() {
+        try {
+            await this.inst.pause();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.inst.stop();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** One SSH connection per call so no socket keeps the process alive. */
+    async ssh(fn) {
+        let s;
+        try {
+            s = await this.inst.ssh();
+            return await fn(s);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+        finally {
+            s?.dispose();
+        }
+    }
+}
+function envFile(env) {
+    return Object.entries(env)
+        .map(([k, v]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k))
+            throw new Error(`invalid env var name: ${k}`);
+        return `export ${k}=${shq(v)}\n`;
+    })
+        .join("");
+}
+/** The SDK throws plain Errors whose message starts "HTTP <status> ...". */
+function wrap(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const msg = err?.message ?? String(err);
+    const status = /^HTTP (\d{3})/.exec(msg)?.[1];
+    return new ProviderError("morph", msg, status ? Number(status) : undefined);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/northflank.d.ts

@@ -0,0 +1,21 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Northflank sandboxes via `@northflank/js-client`. Auth: NORTHFLANK_API_TOKEN plus
+ * NORTHFLANK_PROJECT_ID (the project every sandbox is created in; its region is fixed at
+ * project creation). A sandbox is a deployment service (microVM-isolated on Northflank cloud)
+ * kept alive by `tail -f /dev/null`; commands run over Northflank's exec API. Default image
+ * ubuntu:22.04; set image.northflank to any public image path (e.g. "python:3.13-slim"). The
+ * image's entrypoint is replaced, and it needs `sh` and `base64` on PATH for file transfer.
+ */
+export declare class NorthflankProvider implements Provider {
+    private token;
+    private projectId;
+    readonly id: "northflank";
+    private client?;
+    constructor(token?: string | undefined, projectId?: string | undefined);
+    configured(): boolean;
+    private northflank;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach to a running sandbox by service id. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/northflank.js

@@ -0,0 +1,261 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { dirname, optionalImport, shq, toBytes, wrapCommand } from "../util.js";
+const DEFAULT_IMAGE = "ubuntu:22.04";
+/** Northflank's createOptions.expiryTime bounds: 5 minutes to 7 days. */
+const MIN_EXPIRY_SECONDS = 300;
+const MAX_EXPIRY_SECONDS = 604_800;
+const READY_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Northflank sandboxes via `@northflank/js-client`. Auth: NORTHFLANK_API_TOKEN plus
+ * NORTHFLANK_PROJECT_ID (the project every sandbox is created in; its region is fixed at
+ * project creation). A sandbox is a deployment service (microVM-isolated on Northflank cloud)
+ * kept alive by `tail -f /dev/null`; commands run over Northflank's exec API. Default image
+ * ubuntu:22.04; set image.northflank to any public image path (e.g. "python:3.13-slim"). The
+ * image's entrypoint is replaced, and it needs `sh` and `base64` on PATH for file transfer.
+ */
+export class NorthflankProvider {
+    token;
+    projectId;
+    id = "northflank";
+    client;
+    constructor(token = process.env.NORTHFLANK_API_TOKEN, projectId = process.env.NORTHFLANK_PROJECT_ID) {
+        this.token = token;
+        this.projectId = projectId;
+    }
+    configured() {
+        return !!this.token && !!this.projectId;
+    }
+    async northflank() {
+        if (!this.client) {
+            if (!this.token || !this.projectId) {
+                throw new ProviderError("northflank", "NORTHFLANK_API_TOKEN and NORTHFLANK_PROJECT_ID must both be set");
+            }
+            const { ApiClient, ApiClientInMemoryContextProvider } = await optionalImport("@northflank/js-client", "northflank");
+            const ctx = new ApiClientInMemoryContextProvider();
+            ctx.addContext({ name: "sandboxrouter", token: this.token, project: this.projectId });
+            this.client = new ApiClient(ctx);
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const nf = await this.northflank();
+        const projectId = this.projectId;
+        const name = `sbr-${randomBytes(5).toString("hex")}`;
+        const expiry = Math.round((spec.timeoutMinutes ?? 30) * 60);
+        const svc = await call(() => nf.create.service.deployment({
+            parameters: { projectId },
+            data: {
+                name,
+                description: "sandboxrouter sandbox",
+                billing: { deploymentPlan: plan(spec.vcpu ?? DEFAULT_VCPU, spec.memoryGb ?? DEFAULT_MEMORY_GB) },
+                deployment: {
+                    instances: 1,
+                    external: { imagePath: spec.image?.northflank ?? DEFAULT_IMAGE },
+                    docker: { configType: "customEntrypointCustomCommand", customEntrypoint: "/bin/sh", customCommand: "-c 'tail -f /dev/null'" },
+                },
+                runtimeEnvironment: spec.env,
+                // At expiry Northflank pauses the service (compute billing stops) and schedules its deletion.
+                createOptions: { expiryTime: Math.min(MAX_EXPIRY_SECONDS, Math.max(MIN_EXPIRY_SECONDS, expiry)) },
+            },
+        }));
+        const box = new NorthflankBox(nf, projectId, svc?.id ?? name);
+        try {
+            await box.waitReady();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    /** Reattach to a running sandbox by service id. */
+    async connect(nativeId) {
+        const box = new NorthflankBox(await this.northflank(), this.projectId, nativeId);
+        const { expiredAt } = await box.info();
+        if (expiredAt)
+            throw new ProviderError("northflank", `sandbox ${nativeId} expired at ${expiredAt}`);
+        await box.waitReady();
+        return box;
+    }
+}
+class NorthflankBox {
+    nf;
+    projectId;
+    nativeId;
+    constructor(nf, projectId, nativeId) {
+        this.nf = nf;
+        this.projectId = projectId;
+        this.nativeId = nativeId;
+    }
+    get params() {
+        return { projectId: this.projectId, serviceId: this.nativeId };
+    }
+    /** The deployment-service fields this adapter reads (GetServiceResult is a union over service types). */
+    async info() {
+        return (await call(() => this.nf.get.service({ parameters: this.params })));
+    }
+    /**
+     * Poll until the deployment is COMPLETED (container running), then until exec is accepted:
+     * the exec endpoint can refuse briefly while the instance comes up.
+     */
+    async waitReady() {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        for (;;) {
+            const status = (await this.info())?.status?.deployment?.status;
+            if (status === "FAILED")
+                throw new ProviderError("northflank", `sandbox ${this.nativeId} failed to deploy`);
+            if (status === "COMPLETED")
+                break;
+            if (Date.now() > deadline)
+                throw new ProviderError("northflank", `sandbox ${this.nativeId} not ready after ${READY_TIMEOUT_MS / 1000}s`);
+            await sleep(1000);
+        }
+        for (;;) {
+            try {
+                const r = await this.run(["/bin/sh", "-c", "true"], 30_000);
+                if (r.exitCode === 0)
+                    return;
+            }
+            catch (err) {
+                if (Date.now() > deadline)
+                    throw err;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError("northflank", `sandbox ${this.nativeId} not accepting exec`);
+            await sleep(1000);
+        }
+    }
+    /**
+     * Exec has no cwd/env/timeout, so cwd/env are wrapped into the command, the command runs
+     * under `timeout` when the image has it, and the deadline is also enforced here.
+     */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const script = shq(wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }));
+        const guarded = `if command -v timeout >/dev/null 2>&1; then exec timeout ${secs} /bin/sh -c ${script}; else exec /bin/sh -c ${script}; fi`;
+        const r = await this.run(["/bin/sh", "-c", guarded], secs * 1000 + 10_000, opts);
+        const durationMs = Date.now() - t0;
+        if (durationMs >= secs * 1000 && [124, 137, 143].includes(r.exitCode)) {
+            throw new ProviderError("northflank", `command timed out after ${secs}s`);
+        }
+        return { ...r, durationMs };
+    }
+    /** Stream base64 over stdin and decode in the sandbox. */
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        const r = await this.run(["/bin/sh", "-c", `mkdir -p ${shq(dirname(path))} && base64 -d > ${shq(path)}`], 120_000 + b64.length / 100, {}, b64);
+        if (r.exitCode !== 0)
+            throw new ProviderError("northflank", `write ${path} failed: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+    }
+    async readFile(path) {
+        const r = await this.run(["/bin/sh", "-c", `base64 < ${shq(path)}`], 120_000);
+        if (r.exitCode !== 0)
+            throw new ProviderError("northflank", `read ${path} failed: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+        return new Uint8Array(Buffer.from(r.stdout, "base64"));
+    }
+    async kill() {
+        await call(() => this.nf.delete.service({ parameters: this.params }));
+    }
+    /** One exec session: optional stdin, streamed stdout/stderr, exit code. */
+    async run(command, limitMs, opts = {}, stdin) {
+        const t0 = Date.now();
+        let session;
+        try {
+            session = await this.nf.exec.execServiceSession(this.params, { command, shell: "none", tty: false });
+        }
+        catch (err) {
+            throw new ProviderError("northflank", err?.message ?? String(err), err?.status);
+        }
+        let stdout = "";
+        let stderr = "";
+        session.stdOut.setEncoding("utf8");
+        session.stdErr.setEncoding("utf8");
+        session.stdOut.on("data", (c) => {
+            stdout += c;
+            opts.onStdout?.(c);
+        });
+        session.stdErr.on("data", (c) => {
+            stderr += c;
+            opts.onStderr?.(c);
+        });
+        const failed = new Promise((_, reject) => session.on("error", (e) => reject(e)));
+        failed.catch(() => { });
+        // Send stdin (if any) and close it so commands that read stdin don't hang.
+        const CHUNK = 64 * 1024;
+        if (stdin)
+            for (let i = 0; i < stdin.length; i += CHUNK)
+                session.stdIn.write(stdin.slice(i, i + CHUNK));
+        session.stdIn.end();
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timeout"), limitMs);
+            timer.unref();
+        });
+        try {
+            const res = await Promise.race([session.waitForCommandResult(), failed, timedOut]);
+            if (res === "timeout")
+                throw new ProviderError("northflank", `command timed out after ${Math.round((Date.now() - t0) / 1000)}s`);
+            return { exitCode: typeof res.exitCode === "number" ? res.exitCode : -1, stdout, stderr };
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("northflank", err?.message ?? String(err), err?.status);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Unwrap a Northflank API response, turning an `error` body into a ProviderError with its HTTP status. */
+async function call(fn) {
+    let res;
+    try {
+        res = await fn();
+    }
+    catch (err) {
+        throw new ProviderError("northflank", err?.message ?? String(err), err?.status);
+    }
+    if (res.error)
+        throw new ProviderError("northflank", res.error.message || `HTTP ${res.error.status}`, res.error.status);
+    return res.data;
+}
+/**
+ * Northflank deployment plans (vCPU, GB), from
+ * https://northflank.com/docs/v1/application/billing/resource-plans-and-quotas. Northflank bills
+ * per vCPU-hour and GB-hour, so the cheapest plan that fits is the one with the least of both.
+ */
+const PLANS = [
+    ["nf-compute-10", 0.1, 0.25],
+    ["nf-compute-20", 0.2, 0.5],
+    ["nf-compute-50", 0.5, 1],
+    ["nf-compute-100-1", 1, 1],
+    ["nf-compute-100-2", 1, 2],
+    ["nf-compute-100-4", 1, 4],
+    ["nf-compute-200", 2, 4],
+    ["nf-compute-200-8", 2, 8],
+    ["nf-compute-200-16", 2, 16],
+    ["nf-compute-400", 4, 8],
+    ["nf-compute-400-16", 4, 16],
+    ["nf-compute-800-8", 8, 8],
+    ["nf-compute-800-16", 8, 16],
+    ["nf-compute-800-24", 8, 24],
+    ["nf-compute-800-32", 8, 32],
+    ["nf-compute-800-40", 8, 40],
+    ["nf-compute-1200-24", 12, 24],
+    ["nf-compute-1600-32", 16, 32],
+    ["nf-compute-2000-40", 20, 40],
+    ["nf-compute-32-131072", 32, 128],
+];
+/** Smallest plan with at least the requested vCPU and memory; the largest plan if none fits. */
+function plan(vcpu, memoryGb) {
+    const cost = ([, c, g]) => c * 0.01667 + g * 0.00833;
+    const fits = PLANS.filter(([, c, g]) => c >= vcpu && g >= memoryGb).sort((a, b) => cost(a) - cost(b));
+    return (fits[0] ?? PLANS[PLANS.length - 1])[0];
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms).unref());
+}

package/dist/providers/runloop.d.ts

@@ -0,0 +1,16 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Runloop devboxes via `@runloop/api-client`. Auth: RUNLOOP_API_KEY. Default Runloop image;
+ * set image.runloop to a blueprint name (or a `bpt_` blueprint id) to start from your own.
+ */
+export declare class RunloopProvider implements Provider {
+    private apiKey;
+    readonly id: "runloop";
+    private client?;
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    private runloop;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; a suspended devbox is resumed. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/runloop.js

@@ -0,0 +1,145 @@
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes, wrapCommand } from "../util.js";
+/** Longest lifetime Runloop accepts for keep_alive_time_seconds (48 h). */
+const MAX_KEEP_ALIVE_SECONDS = 172_800;
+/**
+ * Runloop devboxes via `@runloop/api-client`. Auth: RUNLOOP_API_KEY. Default Runloop image;
+ * set image.runloop to a blueprint name (or a `bpt_` blueprint id) to start from your own.
+ */
+export class RunloopProvider {
+    apiKey;
+    id = "runloop";
+    client;
+    constructor(apiKey = process.env.RUNLOOP_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async runloop() {
+        if (!this.client) {
+            const { RunloopSDK } = await optionalImport("@runloop/api-client", "runloop");
+            this.client = new RunloopSDK({ bearerToken: this.apiKey });
+        }
+        return this.client;
+    }
+    async create(spec) {
+        const rl = await this.runloop();
+        const { cpu, memory } = size(spec.vcpu ?? DEFAULT_VCPU, spec.memoryGb ?? DEFAULT_MEMORY_GB);
+        const image = spec.image?.runloop;
+        try {
+            const box = await rl.devbox.create({
+                ...(image ? (image.startsWith("bpt_") ? { blueprint_id: image } : { blueprint_name: image }) : {}),
+                environment_variables: spec.env,
+                metadata: spec.metadata,
+                launch_parameters: {
+                    resource_size_request: "CUSTOM_SIZE",
+                    custom_cpu_cores: cpu,
+                    custom_gb_memory: memory,
+                    keep_alive_time_seconds: Math.min(MAX_KEEP_ALIVE_SECONDS, Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60))),
+                },
+            });
+            return new RunloopBox(box);
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    /** Reattach; a suspended devbox is resumed. */
+    async connect(nativeId) {
+        const box = (await this.runloop()).devbox.fromId(nativeId);
+        try {
+            const { status } = await box.getInfo();
+            if (status === "suspending")
+                await box.awaitSuspended();
+            if (status === "suspending" || status === "suspended")
+                await box.resume();
+            else if (status === "resuming" || status === "provisioning" || status === "initializing" || status === "queued" || status === "scheduled") {
+                await box.awaitRunning();
+            }
+            else if (status === "shutdown" || status === "failure") {
+                throw new ProviderError("runloop", `devbox ${nativeId} is ${status}`);
+            }
+            return new RunloopBox(box);
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+}
+class RunloopBox {
+    box;
+    nativeId;
+    constructor(box) {
+        this.box = box;
+        this.nativeId = box.id;
+    }
+    /** Runloop's exec has no cwd/env/timeout, so cwd/env are wrapped into the command and the timeout is enforced here. */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const limit = (opts.timeoutSeconds ?? 60) * 1000;
+        let execution;
+        try {
+            execution = await this.box.cmd.execAsync(wrapCommand(cmd, { cwd: opts.cwd, env: opts.env }), {
+                stdout: opts.onStdout,
+                stderr: opts.onStderr,
+            });
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+        try {
+            const r = await execution.result({ longPoll: { timeoutMs: limit } });
+            // Read the output from the result, not the stream, so a dropped stream can't lose output.
+            const [stdout, stderr] = await Promise.all([r.stdout(), r.stderr()]);
+            return { exitCode: r.exitCode ?? -1, stdout, stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            if (Date.now() - t0 >= limit) {
+                await execution.kill().catch(() => { });
+                throw new ProviderError("runloop", `command timed out after ${limit / 1000}s`);
+            }
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    async writeFile(path, content) {
+        const { toFile } = await optionalImport("@runloop/api-client", "runloop");
+        const name = path.slice(path.lastIndexOf("/") + 1) || "file";
+        try {
+            await this.box.file.upload({ path, file: await toFile(Buffer.from(toBytes(content)), name) });
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    async readFile(path) {
+        try {
+            const res = await this.box.file.download({ path });
+            return new Uint8Array(await res.arrayBuffer());
+        }
+        catch (err) {
+            throw new ProviderError("runloop", err?.message ?? String(err), err?.status);
+        }
+    }
+    /** Suspend and snapshot the disk. router.get() resumes it. */
+    async pause() {
+        await this.box.suspend();
+        await this.box.awaitSuspended();
+    }
+    async kill() {
+        await this.box.shutdown();
+    }
+}
+/**
+ * Snap a request to Runloop's CUSTOM_SIZE grid: CPU 0.5, 1 or a multiple of 2 (max 16);
+ * memory 1 or a multiple of 2 GiB (max 64); memory between 2x and 8x the CPU count.
+ */
+function size(vcpu, memoryGb) {
+    const cpu = vcpu <= 0.5 ? 0.5 : vcpu <= 1 ? 1 : Math.min(16, 2 * Math.ceil(vcpu / 2));
+    const m = Math.min(8 * cpu, Math.max(2 * cpu, memoryGb));
+    const memory = Math.min(64, m <= 1 ? 1 : 2 * Math.ceil(m / 2));
+    return { cpu, memory };
+}

package/dist/providers/sprites.d.ts

@@ -0,0 +1,15 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * Fly.io Sprites via `@fly/sprites`. A sprite is a persistent machine named by the caller, so the
+ * name is the native id. Sprites idle on their own and have no lifetime knob: kill() deletes it.
+ */
+export declare class SpritesProvider implements Provider {
+    private token;
+    readonly id: "sprites";
+    private client?;
+    constructor(token?: string | undefined);
+    configured(): boolean;
+    private sprites;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}