@sandboxrouter/sdk 0.2.0 → 0.3.1

package/dist/providers/lambda.js

@@ -0,0 +1,467 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, writeFile as fsWriteFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ProviderError } from "../types.js";
+import { timeoutError, wrapCommand } from "../util.js";
+import { AwsClient, awsCredentialsHinted } from "./agentcore.js";
+/**
+ * AWS Lambda MicroVMs (launched 2026-06-22): Firecracker VMs started from a snapshot of an image you
+ * build, each with its own HTTPS endpoint, suspend/resume and up to 8 hours of life.
+ *
+ * Control plane (SigV4, signing name "lambda", host https://lambda.{region}.amazonaws.com, rest-json):
+ *   POST   /2025-09-09/microvms                          RunMicrovm {imageIdentifier, imageVersion?, idlePolicy, maximumDurationInSeconds,
+ *                                                        ingressNetworkConnectors, egressNetworkConnectors, executionRoleArn?, clientToken}
+ *                                                        -> {microvmId, endpoint, state, ...}
+ *   GET    /2025-09-09/microvms/{id}                     GetMicrovm -> {state: PENDING|RUNNING|SUSPENDING|SUSPENDED|TERMINATING|TERMINATED, endpoint, ...}
+ *   POST   /2025-09-09/microvms/{id}/auth-token          CreateMicrovmAuthToken {expirationInMinutes, allowedPorts:[{port}]} -> {authToken: {"X-aws-proxy-auth": jwe}}
+ *   POST   /2025-09-09/microvms/{id}/suspend | /resume   SuspendMicrovm / ResumeMicrovm
+ *   DELETE /2025-09-09/microvms/{id}                     TerminateMicrovm
+ * Data plane: https://{endpoint}/... with the auth-token entries as headers and X-aws-proxy-port.
+ *
+ * Lambda gives a MicroVM no exec or file API of its own: the endpoint reaches whatever server your image
+ * runs. So the image must run the small server in LAMBDA_MICROVM_SERVER below (Node.js, no deps), which
+ * speaks this adapter's protocol on port 8080:
+ *   POST /sbr/v1/exec   {cmd, cwd?, env?, timeoutSeconds}  -> NDJSON {"stdout":b64} | {"stderr":b64} ... {"exitCode":N} | {"error":msg}
+ *   PUT  /sbr/v1/files?path=/abs   raw body -> 204
+ *   GET  /sbr/v1/files?path=/abs   -> raw bytes | 404
+ *   GET  /sbr/v1/health            -> 200
+ * It also answers the lifecycle hooks under /aws/lambda-microvms/runtime/v1/ with 200.
+ *
+ * Docs:
+ *   https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html
+ *   https://docs.aws.amazon.com/lambda/latest/dg/microvms-launching.html
+ *   https://docs.aws.amazon.com/lambda/latest/dg/microvms-images.html     (sizes, base images)
+ *   https://docs.aws.amazon.com/lambda/latest/dg/microvms-getting-started.html
+ *   https://docs.aws.amazon.com/lambda/latest/microvm-api/API_Operations.html
+ *   https://github.com/boto/botocore/blob/develop/botocore/data/lambda-microvms/2025-09-09/service-2.json (signing name, paths)
+ *   https://aws.amazon.com/lambda/pricing/
+ *   https://aws.amazon.com/about-aws/whats-new/2026/06/aws-lambda-microvms/
+ *
+ * Mapping:
+ * - Size is a property of the image (resources[].minimumMemoryInMiB, 2 GB per vCPU, bursts to 4x), not
+ *   of a run. Set LAMBDA_MICROVM_MEMORY_GB to the image's baseline and create() refuses specs above the
+ *   4x burst so the router falls back; otherwise vcpu/memoryGb are not enforced.
+ * - spec.image.lambda: run that image ARN/ID instead of LAMBDA_MICROVM_IMAGE ("custom-image").
+ * - timeoutMinutes -> maximumDurationInSeconds (max 28800). pause() -> SuspendMicrovm (memory and disk
+ *   kept); the next call resumes it.
+ * - env: exported in front of each command (images take env only at build time).
+ *
+ * ## Setup (once per region; ARM64 only)
+ *
+ * 1. Write the server bundle and zip it:
+ *      import { writeLambdaMicrovmBundle } from "./src/providers/lambda.js"; await writeLambdaMicrovmBundle("sbr-mvm")
+ *      cd sbr-mvm && zip -r ../sbr-mvm.zip . && aws s3 cp ../sbr-mvm.zip s3://<bucket>/sbr-mvm.zip
+ *    (Dockerfile: FROM public.ecr.aws/docker/library/node:22-bookworm-slim, CMD node /opt/sbr/server.mjs.
+ *    Add whatever tools your agents need.)
+ * 2. A build role Lambda can assume (lambda.amazonaws.com) with s3:GetObject on the zip.
+ * 3. aws lambda-microvms list-managed-microvm-images   # base image ARN, e.g. arn:aws:lambda:<region>:aws:microvm-image:al2023-1
+ *    aws lambda-microvms create-microvm-image --name sbr-sandbox \
+ *      --code-artifact uri=s3://<bucket>/sbr-mvm.zip --base-image-arn <base-arn> --build-role-arn <role-arn> \
+ *      --resources '[{"minimumMemoryInMiB":4096}]' --cpu-configurations '[{"architecture":"ARM_64"}]'
+ *    Wait for the image state CREATED, then set LAMBDA_MICROVM_IMAGE=<image arn>, AWS_REGION, and
+ *    LAMBDA_MICROVM_MEMORY_GB=4 (the baseline you chose). The caller needs lambda:RunMicrovm, GetMicrovm,
+ *    CreateMicrovmAuthToken, SuspendMicrovm, ResumeMicrovm and TerminateMicrovm.
+ */
+const ID = "lambda";
+const API = "/2025-09-09/microvms";
+const PORT = 8080;
+const MICROVM_ID = /^[A-Za-z0-9._:-]{1,256}$/;
+export class LambdaMicrovmProvider {
+    id = ID;
+    region;
+    image;
+    /** @internal */ opts;
+    client;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.region = opts.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+        this.image = opts.image ?? process.env.LAMBDA_MICROVM_IMAGE;
+    }
+    configured() {
+        return !!(this.region && this.image) && (!!this.opts.credentials || awsCredentialsHinted());
+    }
+    /** @internal */
+    aws() {
+        if (!this.region)
+            throw new ProviderError(ID, "set AWS_REGION");
+        this.client ??= new AwsClient(ID, "lambda", this.region, this.opts.credentials);
+        return this.client;
+    }
+    /** @internal */
+    url(path = "") {
+        const base = this.opts.endpoint ?? `https://lambda.${this.region}.amazonaws.com`;
+        return new URL(`${base.replace(/\/+$/, "")}${API}${path}`);
+    }
+    /** @internal */
+    get pollMs() {
+        return this.opts.pollMs ?? 1000;
+    }
+    /** @internal GetMicrovm until it settles in RUNNING (or fails). */
+    async waitRunning(id) {
+        const deadline = Date.now() + (this.opts.readyTimeoutMs ?? 180_000);
+        for (;;) {
+            const vm = await this.aws().json("GET", this.url(`/${encodeURIComponent(id)}`));
+            if (vm.state === "RUNNING")
+                return vm;
+            if (vm.state === "TERMINATING" || vm.state === "TERMINATED")
+                throw new ProviderError(ID, `MicroVM ${id} is ${vm.state}${vm.stateReason ? `: ${vm.stateReason}` : ""}`, 404);
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `MicroVM ${id} still ${vm.state} after ${(this.opts.readyTimeoutMs ?? 180_000) / 1000}s`);
+            await sleep(this.pollMs);
+        }
+    }
+    async create(spec) {
+        const image = spec.image?.lambda ?? this.image;
+        if (!image)
+            throw new ProviderError(ID, "set LAMBDA_MICROVM_IMAGE (see src/providers/lambda.ts for the one-time image build)");
+        const base = this.opts.memoryGb ?? (process.env.LAMBDA_MICROVM_MEMORY_GB ? Number(process.env.LAMBDA_MICROVM_MEMORY_GB) : undefined);
+        if (base) {
+            const peakMem = base * 4;
+            const peakCpu = (base / 2) * 4;
+            if ((spec.memoryGb ?? 0) > peakMem || (spec.vcpu ?? 0) > peakCpu) {
+                throw new ProviderError(ID, `image baseline ${base} GB bursts to ${peakCpu} vCPU / ${peakMem} GB; asked for ${spec.vcpu ?? "-"} vCPU / ${spec.memoryGb ?? "-"} GB`, 400);
+            }
+        }
+        const maxDuration = Math.min(28_800, Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60)));
+        const egress = this.opts.egressConnectors ??
+            (process.env.LAMBDA_MICROVM_EGRESS_CONNECTORS !== undefined
+                ? process.env.LAMBDA_MICROVM_EGRESS_CONNECTORS.split(",").map((s) => s.trim()).filter(Boolean)
+                : [connector(this.region, "INTERNET_EGRESS")]);
+        const idle = Math.max(60, this.opts.idleSeconds ?? 900);
+        const body = {
+            imageIdentifier: image,
+            ingressNetworkConnectors: [connector(this.region, "HTTP_INGRESS")],
+            egressNetworkConnectors: egress,
+            maximumDurationInSeconds: maxDuration,
+            idlePolicy: { autoResumeEnabled: true, maxIdleDurationSeconds: idle, suspendedDurationSeconds: maxDuration },
+            clientToken: randomBytes(16).toString("hex"),
+        };
+        const version = this.opts.imageVersion ?? process.env.LAMBDA_MICROVM_IMAGE_VERSION;
+        if (version && !spec.image?.lambda)
+            body.imageVersion = version;
+        const role = this.opts.executionRoleArn ?? process.env.LAMBDA_MICROVM_EXECUTION_ROLE_ARN;
+        if (role)
+            body.executionRoleArn = role;
+        const run = await this.aws().json("POST", this.url(), { json: body });
+        if (!run.microvmId)
+            throw new ProviderError(ID, "RunMicrovm returned no microvmId");
+        const box = new LambdaMicrovm(this, run.microvmId, run.endpoint, spec.env);
+        try {
+            const vm = run.state === "RUNNING" && run.endpoint ? run : await this.waitRunning(run.microvmId);
+            box.setEndpoint(vm.endpoint);
+            await box.waitHealthy();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    async connect(nativeId) {
+        if (!MICROVM_ID.test(nativeId))
+            throw new ProviderError(ID, `invalid MicroVM id: ${nativeId}`);
+        const box = new LambdaMicrovm(this, nativeId);
+        await box.resumeIfNeeded();
+        return box;
+    }
+}
+class LambdaMicrovm {
+    p;
+    nativeId;
+    endpoint;
+    env;
+    token;
+    paused = false;
+    constructor(p, nativeId, endpoint, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.endpoint = endpoint;
+        this.env = env;
+    }
+    /** @internal */
+    setEndpoint(e) {
+        if (e)
+            this.endpoint = e;
+    }
+    base() {
+        if (!this.endpoint)
+            throw new ProviderError(ID, `MicroVM ${this.nativeId} has no endpoint`);
+        return /^https?:\/\//.test(this.endpoint) ? this.endpoint.replace(/\/+$/, "") : `https://${this.endpoint.replace(/\/+$/, "")}`;
+    }
+    /** @internal Resume a suspended VM (and learn its endpoint). */
+    async resumeIfNeeded() {
+        const vm = await this.p.aws().json("GET", this.p.url(`/${encodeURIComponent(this.nativeId)}`));
+        if (vm.state === "TERMINATING" || vm.state === "TERMINATED")
+            throw new ProviderError(ID, `MicroVM ${this.nativeId} is ${vm.state}`, 404);
+        if (vm.state === "SUSPENDED" || vm.state === "SUSPENDING") {
+            await this.p.aws().json("POST", this.p.url(`/${encodeURIComponent(this.nativeId)}/resume`), { json: {} });
+        }
+        this.setEndpoint((vm.state === "RUNNING" ? vm : await this.p.waitRunning(this.nativeId)).endpoint);
+        this.paused = false;
+    }
+    /** Auth headers from CreateMicrovmAuthToken, cached until 5 minutes before they expire. */
+    async auth() {
+        if (this.paused)
+            await this.resumeIfNeeded();
+        if (!this.endpoint)
+            await this.resumeIfNeeded();
+        if (this.token && this.token.expiresAt > Date.now())
+            return this.token.headers;
+        const minutes = 60;
+        const r = await this.p.aws().json("POST", this.p.url(`/${encodeURIComponent(this.nativeId)}/auth-token`), {
+            json: { expirationInMinutes: minutes, allowedPorts: [{ port: PORT }] },
+        });
+        if (!r.authToken || !Object.keys(r.authToken).length)
+            throw new ProviderError(ID, "CreateMicrovmAuthToken returned no token");
+        this.token = { headers: { ...r.authToken, "X-aws-proxy-port": String(PORT) }, expiresAt: Date.now() + (minutes - 5) * 60_000 };
+        return this.token.headers;
+    }
+    async vmFetch(method, path, init = {}) {
+        const headers = { ...(await this.auth()), ...init.headers };
+        try {
+            return await fetch(`${this.base()}${path}`, {
+                method,
+                headers,
+                body: init.body,
+                signal: init.timeoutMs ? AbortSignal.timeout(init.timeoutMs) : undefined,
+            });
+        }
+        catch (err) {
+            throw new ProviderError(ID, `${method} ${path}: ${err.message}`);
+        }
+    }
+    async fail(res, what) {
+        const text = (await res.text().catch(() => "")).slice(0, 300);
+        let detail = text;
+        try {
+            detail = JSON.parse(text)?.error ?? text;
+        }
+        catch {
+            /* plain text */
+        }
+        throw new ProviderError(ID, `${what} -> ${res.status} ${detail}`.trim(), res.status);
+    }
+    /** @internal The endpoint answers 502/503 until the server is up (and the /run hook has returned). */
+    async waitHealthy(timeoutMs = 120_000) {
+        const deadline = Date.now() + timeoutMs;
+        let last = "";
+        for (;;) {
+            try {
+                const res = await this.vmFetch("GET", "/sbr/v1/health", { timeoutMs: 10_000 });
+                if (res.ok)
+                    return;
+                if (res.status === 404)
+                    throw new ProviderError(ID, "the MicroVM image does not run the sandboxrouter server (GET /sbr/v1/health -> 404); see src/providers/lambda.ts", 404);
+                last = `HTTP ${res.status}`;
+                await res.body?.cancel().catch(() => { });
+            }
+            catch (err) {
+                if (err instanceof ProviderError && err.status === 404)
+                    throw err;
+                last = err.message;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `MicroVM ${this.nativeId} server not healthy after ${timeoutMs / 1000}s (${last})`);
+            await sleep(this.p.pollMs);
+        }
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const timeout = Math.max(1, Math.round(opts.timeoutSeconds ?? 60));
+        // cwd/env go through the shell wrapper so the server stays a dumb `bash -c`.
+        const full = wrapCommand(cmd, { cwd: opts.cwd, env: { ...this.env, ...opts.env } });
+        const res = await this.vmFetch("POST", "/sbr/v1/exec", {
+            body: JSON.stringify({ cmd: full, timeoutSeconds: timeout }),
+            headers: { "content-type": "application/json", accept: "application/x-ndjson" },
+            timeoutMs: (timeout + 60) * 1000,
+        });
+        if (!res.ok)
+            await this.fail(res, "exec");
+        const outDec = new TextDecoder();
+        const errDec = new TextDecoder();
+        let stdout = "";
+        let stderr = "";
+        let exitCode;
+        for await (const line of readLines(res)) {
+            const j = JSON.parse(line);
+            if (j.timedOut)
+                throw timeoutError(ID, timeout);
+            if (j.stdout !== undefined) {
+                const s = outDec.decode(Buffer.from(j.stdout, "base64"), { stream: true });
+                if (s)
+                    (stdout += s), opts.onStdout?.(s);
+            }
+            if (j.stderr !== undefined) {
+                const s = errDec.decode(Buffer.from(j.stderr, "base64"), { stream: true });
+                if (s)
+                    (stderr += s), opts.onStderr?.(s);
+            }
+            if (j.error !== undefined)
+                throw new ProviderError(ID, `exec: ${j.error}`);
+            if (j.exitCode !== undefined)
+                exitCode = j.exitCode;
+        }
+        const o = outDec.decode();
+        const e = errDec.decode();
+        if (o)
+            (stdout += o), opts.onStdout?.(o);
+        if (e)
+            (stderr += e), opts.onStderr?.(e);
+        if (exitCode === undefined)
+            throw new ProviderError(ID, "exec: stream ended without an exit code");
+        return { exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+    }
+    async writeFile(path, content) {
+        const res = await this.vmFetch("PUT", `/sbr/v1/files?path=${encodeURIComponent(absolute(path))}`, {
+            body: typeof content === "string" ? new TextEncoder().encode(content) : content,
+            headers: { "content-type": "application/octet-stream" },
+            timeoutMs: 300_000,
+        });
+        if (!res.ok)
+            await this.fail(res, `writeFile ${path}`);
+        await res.body?.cancel().catch(() => { });
+    }
+    async readFile(path) {
+        const res = await this.vmFetch("GET", `/sbr/v1/files?path=${encodeURIComponent(absolute(path))}`, { timeoutMs: 300_000 });
+        if (!res.ok)
+            await this.fail(res, `readFile ${path}`);
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /** SuspendMicrovm: memory and disk are kept, compute billing stops; the next call resumes. */
+    async pause() {
+        await this.p.aws().json("POST", this.p.url(`/${encodeURIComponent(this.nativeId)}/suspend`), { json: {} });
+        this.paused = true;
+    }
+    async kill() {
+        try {
+            await this.p.aws().json("DELETE", this.p.url(`/${encodeURIComponent(this.nativeId)}`));
+        }
+        catch (err) {
+            if (err instanceof ProviderError && err.status === 404)
+                return;
+            throw err;
+        }
+    }
+}
+function connector(region, name) {
+    return `arn:aws:lambda:${region}:aws:network-connector:aws-network-connector:${name}`;
+}
+function absolute(path) {
+    if (!path.startsWith("/"))
+        throw new ProviderError(ID, `paths must be absolute: ${path}`);
+    return path;
+}
+async function* readLines(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (line)
+                yield line;
+        }
+        if (done) {
+            if (buffer.trim())
+                yield buffer.trim();
+            return;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** The in-VM server the MicroVM image must run (Node.js >= 18, built-ins only). */
+export const LAMBDA_MICROVM_SERVER = String.raw `// sandboxrouter MicroVM server: exec + files over HTTP for src/providers/lambda.ts.
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const PORT = Number(process.env.SBR_PORT || 8080);
+const json = (res, status, obj) => { res.writeHead(status, { "content-type": "application/json" }); res.end(JSON.stringify(obj)); };
+const body = async (req) => { const c = []; for await (const x of req) c.push(x); return Buffer.concat(c); };
+
+createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url, "http://localhost");
+    const p = url.pathname;
+    if (p.startsWith("/aws/lambda-microvms/runtime/v1/")) return json(res, 200, {});
+    if (p === "/sbr/v1/health") return json(res, 200, { ok: true });
+    if (p === "/sbr/v1/files") {
+      const path = url.searchParams.get("path");
+      if (!path || !path.startsWith("/")) return json(res, 400, { error: "absolute path required" });
+      if (req.method === "PUT") {
+        const data = await body(req);
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = path + ".sbr-" + process.pid + "-" + Date.now();
+        await writeFile(tmp, data);
+        await rename(tmp, path);
+        res.writeHead(204);
+        return res.end();
+      }
+      if (req.method === "GET") {
+        try {
+          const data = await readFile(path);
+          res.writeHead(200, { "content-type": "application/octet-stream" });
+          return res.end(data);
+        } catch (e) {
+          return json(res, e.code === "ENOENT" ? 404 : 500, { error: String(e.message) });
+        }
+      }
+    }
+    if (p === "/sbr/v1/exec" && req.method === "POST") {
+      const j = JSON.parse((await body(req)).toString() || "{}");
+      if (typeof j.cmd !== "string") return json(res, 400, { error: "cmd required" });
+      res.writeHead(200, { "content-type": "application/x-ndjson" });
+      const line = (o) => res.write(JSON.stringify(o) + "\n");
+      const child = spawn("bash", ["-c", j.cmd], {
+        cwd: j.cwd || process.env.HOME || "/",
+        env: { ...process.env, ...(j.env || {}) },
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: true,
+      });
+      let timedOut = false;
+      let finished = false;
+      const killGroup = () => { try { process.kill(-child.pid, "SIGKILL"); } catch {} };
+      const timer = j.timeoutSeconds > 0 ? setTimeout(() => { timedOut = true; killGroup(); }, j.timeoutSeconds * 1000) : null;
+      res.on("close", () => { if (!finished) killGroup(); });
+      child.stdout.on("data", (d) => line({ stdout: d.toString("base64") }));
+      child.stderr.on("data", (d) => line({ stderr: d.toString("base64") }));
+      child.on("error", (e) => { finished = true; if (timer) clearTimeout(timer); line({ error: String(e.message) }); res.end(); });
+      child.on("close", (code, signal) => {
+        finished = true;
+        if (timer) clearTimeout(timer);
+        // A timeout kill is reported as such, so the client can tell it from a command that exits 124 itself.
+        const exitCode = code ?? (signal ? 128 + (constants.signals[signal] || 0) : 1);
+        line(timedOut ? { exitCode: 124, timedOut: true } : { exitCode });
+        res.end();
+      });
+      return;
+    }
+    json(res, 404, { error: "no route" });
+  } catch (e) {
+    if (!res.headersSent) json(res, 500, { error: String((e && e.message) || e) });
+    else res.end();
+  }
+}).listen(PORT, "0.0.0.0", () => console.log("sandboxrouter MicroVM server on :" + PORT));
+`;
+export const LAMBDA_MICROVM_DOCKERFILE = `FROM public.ecr.aws/docker/library/node:22-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git python3 && rm -rf /var/lib/apt/lists/*
+COPY server.mjs /opt/sbr/server.mjs
+EXPOSE 8080
+CMD ["node", "/opt/sbr/server.mjs"]
+`;
+/** Writes server.mjs + Dockerfile into dir, ready to zip and upload for create-microvm-image. */
+export async function writeLambdaMicrovmBundle(dir) {
+    await mkdir(dir, { recursive: true });
+    await fsWriteFile(join(dir, "server.mjs"), LAMBDA_MICROVM_SERVER);
+    await fsWriteFile(join(dir, "Dockerfile"), LAMBDA_MICROVM_DOCKERFILE);
+}

package/dist/providers/langsmith.d.ts

@@ -0,0 +1,16 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** The size LangSmith will actually run for a request: 2 to 6 GiB per vCPU. */
+export declare function langsmithSize(vcpu: number, memoryGb: number): {
+    vcpu: number;
+    memoryGb: number;
+};
+export declare class LangSmithProvider implements Provider {
+    private apiKey;
+    readonly id: "langsmith";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    private client;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach by sandbox name; a stopped sandbox wakes on its next command. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/langsmith.js

@@ -0,0 +1,149 @@
+import { ProviderError } from "../types.js";
+import { optionalImport } from "../util.js";
+/**
+ * LangSmith Sandboxes (LangChain) via the official `langsmith` SDK's `langsmith/sandbox` module.
+ *
+ * Auth: LANGSMITH_API_KEY. LANGSMITH_ENDPOINT optionally picks the region, BYOC data plane or
+ * self-hosted instance (the SDK reads it; default https://api.smith.langchain.com, GCP US).
+ * Size: `vCpus` and `memBytes`. Memory is tied to 4 GiB per vCPU and must stay within 50% of that,
+ * i.e. 2 to 6 GiB per vCPU, so a request outside that band is widened (more memory, or more vCPUs)
+ * by `langsmithSize`, which the price estimate uses too.
+ * Lifetime: there is no hard lifetime, only an idle stop. `timeoutMinutes` becomes `idleTtlSeconds`
+ * (a multiple of 60), and a stopped sandbox is deleted a day later (`deleteAfterStopSeconds`)
+ * instead of the server default of about 14 days, so a leak bills storage for a day at most.
+ * Pause = `stop()`: compute is released and the filesystem kept; the next command wakes it.
+ * Image: `image.langsmith` = a snapshot id (UUID) or snapshot name; default is LangSmith's runtime.
+ * Streaming goes over a WebSocket, which needs the `ws` package (the SDK's own optional peer).
+ *
+ * Docs: https://docs.langchain.com/langsmith/sandboxes
+ *       https://docs.langchain.com/langsmith/sandbox-cli (sizes, stop/wake, LANGSMITH_ENDPOINT)
+ *       https://reference.langchain.com/javascript/langsmith/sandbox (SandboxClient, Sandbox)
+ *       https://www.langchain.com/pricing (per-second vCPU, memory and storage rates)
+ */
+const ID = "langsmith";
+const GIB = 1024 ** 3;
+/** The size LangSmith will actually run for a request: 2 to 6 GiB per vCPU. */
+export function langsmithSize(vcpu, memoryGb) {
+    let v = Math.max(1, Math.ceil(vcpu));
+    if (memoryGb > v * 6)
+        v = Math.ceil(memoryGb / 6);
+    return { vcpu: v, memoryGb: Math.max(memoryGb, v * 2) };
+}
+export class LangSmithProvider {
+    apiKey;
+    id = ID;
+    constructor(apiKey = process.env.LANGSMITH_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async client() {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "LANGSMITH_API_KEY is not set");
+        const { SandboxClient } = await optionalImport("langsmith/sandbox", "langsmith");
+        return new SandboxClient({ apiKey: this.apiKey });
+    }
+    async create(spec) {
+        const client = await this.client();
+        const size = langsmithSize(spec.vcpu ?? 2, spec.memoryGb ?? 4);
+        const image = spec.image?.langsmith;
+        const isId = !!image && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(image);
+        const opts = {
+            vCpus: size.vcpu,
+            memBytes: Math.round(size.memoryGb * GIB),
+            idleTtlSeconds: Math.max(60, Math.ceil(spec.timeoutMinutes ?? 30) * 60),
+            deleteAfterStopSeconds: 24 * 3600,
+            ...(image && !isId ? { snapshotName: image } : {}),
+            ...(spec.env ? { runConfig: { env_vars: spec.env } } : {}),
+            ...(spec.metadata ? { labels: spec.metadata } : {}),
+        };
+        try {
+            return new LangSmithBox(await client.createSandbox(isId ? image : undefined, opts));
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    /** Reattach by sandbox name; a stopped sandbox wakes on its next command. */
+    async connect(nativeId) {
+        const client = await this.client();
+        try {
+            return new LangSmithBox(await client.getSandbox(nativeId));
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+}
+class LangSmithBox {
+    sbx;
+    constructor(sbx) {
+        this.sbx = sbx;
+    }
+    get nativeId() {
+        return this.sbx.name;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const runConfig = opts.cwd || opts.env ? { ...(opts.cwd ? { work_dir: opts.cwd } : {}), ...(opts.env ? { env_vars: opts.env } : {}) } : undefined;
+        try {
+            const r = await this.sbx.run(cmd, {
+                timeout: opts.timeoutSeconds ?? 60,
+                ...(runConfig ? { runConfig } : {}),
+                ...(opts.onStdout ? { onStdout: opts.onStdout } : {}),
+                ...(opts.onStderr ? { onStderr: opts.onStderr } : {}),
+            });
+            return { exitCode: r.exit_code, stdout: r.stdout, stderr: r.stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async writeFile(path, content) {
+        try {
+            await this.sbx.write(path, content);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async readFile(path) {
+        try {
+            return await this.sbx.read(path);
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async pause() {
+        try {
+            await this.sbx.stop();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+    async kill() {
+        try {
+            await this.sbx.delete();
+        }
+        catch (err) {
+            throw wrap(err);
+        }
+    }
+}
+function wrap(err) {
+    if (err instanceof ProviderError)
+        return err;
+    const status = err?.name === "LangSmithResourceNotFoundError"
+        ? 404
+        : err?.name === "LangSmithSandboxAuthenticationError"
+            ? 401
+            : err?.name === "LangSmithQuotaExceededError"
+                ? 429
+                : typeof err?.status === "number"
+                    ? err.status
+                    : undefined;
+    return new ProviderError(ID, err?.message ?? String(err), status);
+}