@sandboxrouter/sdk 0.2.0 → 0.3.0

package/dist/providers/upstash.js

@@ -0,0 +1,258 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU, UPSTASH_SIZES, upstashSize } from "../catalog.js";
+export { UPSTASH_SIZES, upstashSize };
+import { ProviderError } from "../types.js";
+import { dirname, shq, toBytes, wrapCommand } from "../util.js";
+/**
+ * Upstash Box over plain HTTPS (no SDK). Each sandbox is an *ephemeral* box: exec + files only,
+ * ready on the create response (no polling), deleted automatically after `ttl` seconds.
+ *
+ * Upstash documents the Box API through its SDKs (`@upstash/box`, `upstash-box`). The ephemeral
+ * create body is documented; the other routes and field names below are the ones the official
+ * TypeScript SDK (@upstash/box 0.7.10, MIT) sends, so they are not invented but are not in the
+ * public docs either.
+ *   base     https://us-east-1.box.upstash.com (UPSTASH_BOX_BASE_URL), header X-Box-Api-Key
+ *   POST   /v2/box                    {ephemeral:true, ttl, size, runtime?, env_vars?}  (documented)
+ *   GET    /v2/box/{id}               box data ({id, status, size, expires_at, ...})
+ *   POST   /v2/box/{id}/exec          {command:["sh","-c",cmd]} -> {output, error, exit_code}
+ *   POST   /v2/box/{id}/exec-stream   same body; raw output, then "event: exit\ndata: {exit_code}"
+ *                                     (or "event: error\ndata: {error}")
+ *   GET    /v2/box/{id}/files/read?path=P&encoding=base64 -> {content}
+ *   POST   /v2/box/{id}/files/write   {path, content, encoding:"base64"}
+ *   DELETE /v2/box/{id}
+ *   errors: JSON {error: "..."} with the HTTP status
+ * Sizes are fixed: small 2 vCPU / 4 GB, medium 4 / 8, large 8 / 16; the smallest that fits the
+ * spec is used. TTL max 259 200 s (3 days). image.upstash = runtime: node, python, golang, ruby,
+ * rust or their -alpine variants (Debian by default); custom images are "coming soon".
+ * No pause: ephemeral boxes don't expose it (an idle one is auto-paused by Upstash and resumed by
+ * the next exec or file call). Commands get no per-request timeout from the API, so they run
+ * under `timeout`, as the docs recommend.
+ * exec-stream does not say whether stderr is included or how, so streaming commands send stderr to
+ * a temp file and deliver it (onStderr) once the command ends; stdout streams live.
+ * Pricing: active CPU only (memory free), see https://upstash.com/pricing/box.
+ *
+ * Docs: https://upstash.com/docs/box/overall/ephemeral-box.md
+ *       https://upstash.com/docs/box/overall/how-it-works.md (sizes, lifecycle, runtimes)
+ *       https://upstash.com/docs/box/overall/shell.md
+ *       https://upstash.com/docs/box/overall/files.md
+ *       https://upstash.com/docs/box/overall/quickstart.md (UPSTASH_BOX_API_KEY)
+ *       https://upstash.com/pricing/box.md
+ *       https://github.com/upstash/box (SDK source the routes above come from)
+ */
+const ID = "upstash";
+const MAX_TTL_SECONDS = 259_200;
+const RUNTIME = /^(node|python|golang|ruby|rust)(-alpine)?$/;
+export class UpstashProvider {
+    apiKey;
+    baseUrl;
+    id = ID;
+    constructor(apiKey = process.env.UPSTASH_BOX_API_KEY, baseUrl = (process.env.UPSTASH_BOX_BASE_URL ?? "https://us-east-1.box.upstash.com").replace(/\/$/, "")) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /** @internal One API call; JSON in and out. Non-2xx becomes a ProviderError with the status. */
+    async request(method, path, body, timeoutMs = 600_000, raw = false) {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "UPSTASH_BOX_API_KEY is not set");
+        const headers = { "X-Box-Api-Key": this.apiKey };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            const what = err?.name === "TimeoutError" ? `timed out after ${timeoutMs / 1000}s` : (err?.message ?? String(err));
+            throw new ProviderError(ID, `${method} ${path.split("?")[0]}: ${what}`);
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let detail = text.slice(0, 300) || res.statusText;
+            try {
+                const j = JSON.parse(text);
+                if (typeof j?.error === "string")
+                    detail = j.error;
+            }
+            catch {
+                /* not JSON */
+            }
+            throw new ProviderError(ID, `${method} ${path.split("?")[0]} -> ${res.status} ${detail}`, res.status);
+        }
+        if (raw)
+            return res;
+        const text = await res.text();
+        return text ? JSON.parse(text) : {};
+    }
+    async create(spec) {
+        const { size } = upstashSize(spec.vcpu ?? DEFAULT_VCPU, spec.memoryGb ?? DEFAULT_MEMORY_GB);
+        const ttl = Math.min(MAX_TTL_SECONDS, Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)));
+        const body = { ephemeral: true, ttl, size };
+        const runtime = spec.image?.upstash;
+        if (runtime) {
+            if (!RUNTIME.test(runtime))
+                throw new ProviderError(ID, `unknown runtime "${runtime}" (node, python, golang, ruby, rust, optionally -alpine)`);
+            body.runtime = runtime;
+        }
+        if (spec.env && Object.keys(spec.env).length)
+            body.env_vars = spec.env;
+        const data = (await this.request("POST", "/v2/box", body));
+        if (!data?.id)
+            throw new ProviderError(ID, "create returned no box id");
+        if (data.status === "error")
+            throw new ProviderError(ID, `box ${data.id} failed to start`);
+        return new UpstashBox(this, data.id);
+    }
+    async connect(nativeId) {
+        const data = (await this.request("GET", `/v2/box/${encodeURIComponent(nativeId)}`));
+        if (data.status === "deleted" || data.status === "error")
+            throw new ProviderError(ID, `box ${nativeId} is ${data.status}`, 404);
+        return new UpstashBox(this, data.id ?? nativeId);
+    }
+}
+class UpstashBox {
+    p;
+    nativeId;
+    constructor(p, nativeId) {
+        this.p = p;
+        this.nativeId = nativeId;
+    }
+    get base() {
+        return `/v2/box/${encodeURIComponent(this.nativeId)}`;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = Math.max(1, Math.round(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 timeout ${secs} sh -c ${script}; else sh -c ${script}; fi`;
+        const requestMs = (secs + 30) * 1000;
+        let r;
+        if (opts.onStdout || opts.onStderr) {
+            r = await this.stream(guarded, requestMs, opts, t0);
+        }
+        else {
+            const j = await this.p.request("POST", `${this.base}/exec`, { command: ["sh", "-c", guarded] }, requestMs);
+            r = { exitCode: Number(j.exit_code ?? 0), stdout: j.output ?? "", stderr: j.error ?? "", durationMs: Date.now() - t0 };
+        }
+        if (r.exitCode === 124 && r.durationMs >= secs * 1000)
+            throw new ProviderError(ID, `command timed out after ${secs}s`);
+        return r;
+    }
+    /** exec-stream with stderr parked in a temp file, so the stream carries stdout only. */
+    async stream(guarded, requestMs, opts, t0) {
+        const errFile = `/tmp/.sbr-err-${randomBytes(6).toString("hex")}`;
+        const res = await this.p.request("POST", `${this.base}/exec-stream`, { command: ["sh", "-c", `{ ${guarded} ; } 2>${errFile}`] }, requestMs, true);
+        let stdout = "";
+        let exitCode;
+        for await (const ev of parseExecStream(res)) {
+            if (ev.type === "output") {
+                stdout += ev.data;
+                opts.onStdout?.(ev.data);
+            }
+            else if (ev.type === "error") {
+                throw new ProviderError(ID, `exec-stream: ${ev.message}`);
+            }
+            else {
+                exitCode = ev.exitCode;
+            }
+        }
+        if (exitCode === undefined)
+            throw new ProviderError(ID, "exec-stream ended without an exit code");
+        const e = await this.p.request("POST", `${this.base}/exec`, { command: ["sh", "-c", `cat ${errFile} 2>/dev/null; rm -f ${errFile}`] });
+        const stderr = e.output ?? "";
+        if (stderr)
+            opts.onStderr?.(stderr);
+        return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+    }
+    async writeFile(path, content) {
+        const parent = dirname(path);
+        if (parent !== "/") {
+            const m = await this.p.request("POST", `${this.base}/exec`, { command: ["mkdir", "-p", parent] });
+            if (Number(m.exit_code ?? 0) !== 0)
+                throw new ProviderError(ID, `writeFile ${path}: ${m.error || m.output || `mkdir exit ${m.exit_code}`}`);
+        }
+        await this.p.request("POST", `${this.base}/files/write`, {
+            path,
+            content: Buffer.from(toBytes(content)).toString("base64"),
+            encoding: "base64",
+        });
+    }
+    async readFile(path) {
+        const j = await this.p.request("GET", `${this.base}/files/read?path=${encodeURIComponent(path)}&encoding=base64`);
+        if (typeof j?.content !== "string")
+            throw new ProviderError(ID, `readFile ${path}: no content in response`);
+        return new Uint8Array(Buffer.from(j.content, "base64"));
+    }
+    async kill() {
+        await this.p.request("DELETE", this.base);
+    }
+}
+const EXIT = "event: exit\n";
+const ERROR = "event: error\n";
+/** Longest tail of `buf` that could be the start of an event marker split across reads. */
+function heldBack(buf) {
+    // Hold back up to one character short of the longer marker, so a read ending inside either one waits.
+    for (let n = Math.min(buf.length, Math.max(EXIT.length, ERROR.length) - 1); n > 0; n--) {
+        const tail = buf.slice(-n);
+        if (EXIT.startsWith(tail) || ERROR.startsWith(tail))
+            return n;
+    }
+    return 0;
+}
+/**
+ * The exec-stream body as the official SDK reads it: raw output text, then a trailing SSE event
+ * `event: exit\ndata: {"exit_code":N,...}` (or `event: error\ndata: {"error":"..."}`).
+ * @internal exported for tests
+ */
+export async function* parseExecStream(res) {
+    if (!res.body)
+        throw new ProviderError(ID, "exec-stream response has no body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    let done = false;
+    while (!done) {
+        const chunk = await reader.read();
+        done = chunk.done;
+        buf += done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+        for (const marker of [ERROR, EXIT]) {
+            const i = buf.indexOf(marker);
+            if (i === -1)
+                continue;
+            if (i > 0)
+                yield { type: "output", data: buf.slice(0, i) };
+            buf = buf.slice(i);
+            const m = buf.slice(marker.length).match(/^data:\s*(.+?)\r?(\n|$)/);
+            // Wait for the whole data line (it can arrive in a later read).
+            if (!m || (!m[2] && !done))
+                break;
+            let payload = {};
+            try {
+                payload = JSON.parse(m[1]);
+            }
+            catch {
+                /* keep defaults */
+            }
+            await reader.cancel().catch(() => { });
+            if (marker === ERROR)
+                yield { type: "error", message: typeof payload.error === "string" ? payload.error : "stream error" };
+            else
+                yield { type: "exit", exitCode: Number(payload.exit_code ?? 0) };
+            return;
+        }
+        if (buf.includes(EXIT) || buf.includes(ERROR))
+            continue;
+        const keep = done ? 0 : heldBack(buf);
+        if (buf.length > keep) {
+            yield { type: "output", data: buf.slice(0, buf.length - keep) };
+            buf = buf.slice(buf.length - keep);
+        }
+    }
+}

package/dist/providers/vercel.js

@@ -1,6 +1,6 @@
 import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
 import { ProviderError } from "../types.js";
-import { optionalImport, toBytes, wrapCommand } from "../util.js";
+import { DEFAULT_EXEC_TIMEOUT_S, killedByTimeout, optionalImport, timeoutError, toBytes, wrapCommand } from "../util.js";
 /**
  * Vercel Sandbox via `@vercel/sandbox`. Auth: VERCEL_OIDC_TOKEN (from `vercel env pull`), or
  * VERCEL_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID. Memory is fixed at 2 GB per vCPU.
@@ -44,9 +44,12 @@ class VercelBox {
     }
     async exec(cmd, opts = {}) {
         const t0 = Date.now();
-        const signal = AbortSignal.timeout((opts.timeoutSeconds ?? 60) * 1000);
+        const seconds = opts.timeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_S;
+        // `timeoutMs` makes the sandbox SIGKILL the process at the deadline. The abort signal only
+        // guards this client's wait, so it runs a little longer and never ends a healthy command.
+        const signal = AbortSignal.timeout((seconds + 15) * 1000);
         try {
-            const params = { cmd: "sh", args: ["-c", wrapCommand(cmd)], cwd: opts.cwd, env: opts.env, signal };
+            const params = { cmd: "sh", args: ["-c", wrapCommand(cmd)], cwd: opts.cwd, env: opts.env, signal, timeoutMs: seconds * 1000 };
             if (opts.onStdout || opts.onStderr) {
                 const running = await this.sbx.runCommand({ ...params, detached: true });
                 let stdout = "";
@@ -62,13 +65,21 @@ class VercelBox {
                     }
                 }
                 const done = await running.wait({ signal });
+                if (killedByTimeout(done.exitCode, Date.now() - t0, seconds))
+                    throw timeoutError("vercel", seconds);
                 return { exitCode: done.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
             }
             const r = await this.sbx.runCommand(params);
+            if (killedByTimeout(r.exitCode, Date.now() - t0, seconds))
+                throw timeoutError("vercel", seconds);
             const [stdout, stderr] = await Promise.all([r.stdout(), r.stderr()]);
             return { exitCode: r.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
         }
         catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            if (err?.name === "TimeoutError" || err?.name === "AbortError")
+                throw timeoutError("vercel", seconds);
             throw new ProviderError("vercel", err?.message ?? String(err));
         }
     }

package/dist/providers/workspaces.d.ts

@@ -0,0 +1,60 @@
+import type { ComputerOs, ComputerProvider, ComputerSpec, ProviderComputer } from "../computers.js";
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface WorkspacesAgentOptions {
+    region?: string;
+    stack?: string;
+    fleet?: string;
+    os?: string;
+    /** Default AppStream user id when a spec has no externalUserId. Omitted: the server uses your IAM identity. */
+    userId?: string;
+    /** Override the MCP endpoint (tests). Default https://agentaccess-mcp.{region}.api.aws/mcp. */
+    endpoint?: string;
+    /** Static credentials or a provider; default is the standard AWS chain. */
+    credentials?: AwsCredentials | (() => Promise<AwsCredentials>);
+    /** Per HTTP exchange. The first tools/list can wait for a desktop to boot or a profile to load. */
+    httpTimeoutMs?: number;
+    /** How long createComputer waits for the desktop tools to appear. */
+    readyTimeoutMs?: number;
+    pollMs?: number;
+}
+interface Signer {
+    sign(req: unknown): Promise<{
+        headers: Record<string, string>;
+    }>;
+}
+export declare class WorkspacesAgentProvider implements ComputerProvider {
+    readonly id = "aws-workspaces";
+    readonly computerOs: ComputerOs[];
+    readonly region?: string;
+    readonly stack?: string;
+    readonly fleet?: string;
+    readonly os: "windows" | "linux";
+    /** @internal */ readonly opts: WorkspacesAgentOptions;
+    private signer?;
+    constructor(opts?: WorkspacesAgentOptions);
+    configured(): boolean;
+    /** @internal */
+    get endpoint(): string;
+    /** @internal */
+    requireConfig(): {
+        region: string;
+        stack: string;
+        fleet: string;
+    };
+    /** @internal SigV4 signer for service agentaccess-mcp, built on first use. */
+    getSigner(): Promise<Signer>;
+    /** The user id for a spec: externalUserId as-is when AppStream accepts it, else a stable hash of it. */
+    private userIdFor;
+    createComputer(spec: ComputerSpec): Promise<ProviderComputer>;
+    connectComputer(nativeId: string): Promise<ProviderComputer>;
+    /** @internal Uses @aws-sdk/client-appstream CreateStreamingURL. */
+    createStreamingUrl(userId: string, validitySeconds: number): Promise<{
+        url: string;
+        expiresAt: string | null;
+    }>;
+}
+export {};