@sandboxrouter/sdk 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,7 +1,11 @@
-export { Router, RoutedSandbox, defaultProviders, parseId } from "./router.js";
+export { checkProvider, CHECK_STEPS } from "./check.js";
+export { Ledger, defaultLedgerFile } from "./ledger.js";
+export { conformanceTable, loadConformance } from "./conformance.js";
+export { gc, listOpen, isGone } from "./gc.js";
+export { Router, RoutedSandbox, defaultProviders, defaultComputerProviders, parseId } from "./router.js";
 export { CATALOG, hourlyCost, unfit, info } from "./catalog.js";
 export { createApp } from "./server.js";
-export { RoutedComputer, createComputer, } from "./computers.js";
+export { RoutedComputer, createComputer, planComputer, computerCatalog, computerHourly, COMPUTER_ENTRIES, } from "./computers.js";
 export { bench, benchMarkdown } from "./bench.js";
 export { aggregate, loadReports, makeReport, renderLeaderboard } from "./leaderboard.js";
 export { MaritimeProvider } from "./providers/maritime.js";
@@ -14,4 +18,32 @@ export { SpritesProvider } from "./providers/sprites.js";
 export { BlaxelProvider } from "./providers/blaxel.js";
 export { TensorlakeProvider } from "./providers/tensorlake.js";
 export { RunloopProvider } from "./providers/runloop.js";
+export { DockerProvider } from "./providers/docker.js";
+export { HopxProvider } from "./providers/hopx.js";
+export { CloudflareProvider } from "./providers/cloudflare.js";
+export { NorthflankProvider } from "./providers/northflank.js";
+export { BoatProvider } from "./providers/boat.js";
+export { ExeDevProvider } from "./providers/exedev.js";
+export { AgentCoreProvider } from "./providers/agentcore.js";
+export { AzureSessionsProvider } from "./providers/azure.js";
+export { LambdaMicrovmProvider, writeLambdaMicrovmBundle } from "./providers/lambda.js";
+export { AlibabaProvider } from "./providers/alibaba.js";
+export { BeamProvider } from "./providers/beam.js";
+export { CodeSandboxProvider } from "./providers/codesandbox.js";
+export { DenoProvider } from "./providers/deno.js";
+export { FreestyleProvider } from "./providers/freestyle.js";
+export { KoyebProvider } from "./providers/koyeb.js";
+export { DedalusProvider } from "./providers/dedalus.js";
+export { OpenScaleProvider } from "./providers/openscale.js";
+export { SuperserveProvider } from "./providers/superserve.js";
+export { SailProvider } from "./providers/sail.js";
+export { InstaboxProvider, INSTABOX_SIZES, instaboxSize } from "./providers/instabox.js";
+export { Agent37Provider, AGENT37_SHAPES, agent37Shape } from "./providers/agent37.js";
+export { NovitaProvider } from "./providers/novita.js";
+export { LangSmithProvider, langsmithSize } from "./providers/langsmith.js";
+export { UpstashProvider } from "./providers/upstash.js";
+export { OrgoProvider } from "./providers/orgo.js";
+export { MobilerunProvider } from "./providers/mobilerun.js";
+export { LimrunProvider } from "./providers/limrun.js";
+export { WorkspacesAgentProvider } from "./providers/workspaces.js";
 export * from "./types.js";

package/dist/leaderboard.d.ts

@@ -31,7 +31,13 @@ export interface LeaderRow {
     medianCreateMs?: number;
     medianExecMs?: number;
     successRate: number;
+    /** List price for the size the bench runs it at (`size`). */
     hourlyUsd: number;
+    /** The size bench runs: 2 vCPU / 4 GB, or the provider's fixed default size. */
+    size: {
+        vcpu: number;
+        memoryGb: number;
+    };
 }
 /** Median of each submission's medians, so one heavy submitter can't skew a provider. */
 export declare function aggregate(reports: BenchReport[]): LeaderRow[];

package/dist/leaderboard.js

@@ -1,6 +1,6 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { CATALOG, hourlyCost } from "./catalog.js";
+import { CATALOG, fittingSpec, hourlyCost } from "./catalog.js";
 import { median } from "./bench-store.js";
 export function makeReport(rows, opts) {
     return {
@@ -55,7 +55,8 @@ export function aggregate(reports) {
             medianCreateMs: median(rs.map((r) => r.medianCreateMs).filter((n) => typeof n === "number")),
             medianExecMs: median(rs.map((r) => r.medianExecMs).filter((n) => typeof n === "number")),
             successRate: runs ? ok / runs : 0,
-            hourlyUsd: hourlyCost(id),
+            hourlyUsd: hourlyCost(id, fittingSpec(id)),
+            size: fittingSpec(id),
         };
     });
     return rows.sort((a, b) => (a.medianCreateMs ?? Infinity) - (b.medianCreateMs ?? Infinity));
@@ -81,7 +82,7 @@ export function renderLeaderboard(reports) {
   <th scope="row">${esc(r.name)}</th>
   ${bar(r.medianCreateMs, maxCreate, r.medianCreateMs === undefined ? "" : `${r.medianCreateMs.toLocaleString("en-US")} ms`, `${r.name}: median cold start ${r.medianCreateMs} ms across ${r.submissions} submission${r.submissions === 1 ? "" : "s"}`)}
   <td class="num">${r.medianExecMs === undefined ? "n/a" : `${r.medianExecMs} ms`}</td>
-  ${bar(r.hourlyUsd, maxPrice, `$${r.hourlyUsd.toFixed(3)}`, `${r.name}: $${r.hourlyUsd.toFixed(4)} per hour at list price, 2 vCPU / 4 GB`)}
+  ${bar(r.hourlyUsd, maxPrice, `$${r.hourlyUsd.toFixed(3)}`, `${r.name}: $${r.hourlyUsd.toFixed(4)} per hour at list price, ${r.size.vcpu} vCPU / ${r.size.memoryGb} GB`)}
   <td class="num">${(r.successRate * 100).toFixed(0)}%</td>
   <td class="num muted">${r.submissions}</td>
 </tr>`)
@@ -154,7 +155,7 @@ a { color: inherit; }
     <table>
       <thead><tr>
         <th>#</th><th>Provider</th><th>Cold start (median)</th><th>Exec round trip</th>
-        <th>List price, 2 vCPU / 4 GB</th><th>Success</th><th>Submissions</th>
+        <th>List price (size run)</th><th>Success</th><th>Submissions</th>
       </tr></thead>
       <tbody>
 ${body || `<tr><td colspan="7" class="muted">No results yet. Run <code>npx @sandboxrouter/sdk bench --share</code> and open a PR.</td></tr>`}

package/dist/ledger.d.ts

@@ -0,0 +1,38 @@
+import type { ProviderId } from "./types.js";
+/** One sandbox the router started and hasn't seen killed. */
+export interface LedgerEntry {
+    /** Routed id, `provider:nativeId`. */
+    id: string;
+    provider: ProviderId;
+    /** ISO time the create returned. */
+    createdAt: string;
+    /** ISO time its requested lifetime (spec.timeoutMinutes) runs out. */
+    expiresAt: string;
+    /** Estimated list price per hour while it runs. */
+    usdHour: number;
+}
+/**
+ * Where the default ledger lives: $SANDBOXROUTER_HOME/sandboxes.jsonl, else ~/.sandboxrouter/.
+ * Returns null when SANDBOXROUTER_LEDGER=off.
+ */
+export declare function defaultLedgerFile(): string | null;
+/**
+ * A local record of every sandbox this machine's routers created, so a crashed script's sandboxes
+ * can still be found and killed (`sandboxrouter ls` / `gc`). Append-only JSON lines, so several
+ * processes can write at once; `compact()` rewrites it with only the open entries.
+ * Writing never throws: a ledger problem must not break creating or killing a sandbox.
+ */
+export declare class Ledger {
+    readonly file: string;
+    private warned;
+    constructor(file: string);
+    open(e: LedgerEntry): void;
+    close(id: string, why?: string): void;
+    /** Open entries, oldest first. */
+    list(): LedgerEntry[];
+    /** Rewrite the file with only the open entries. */
+    compact(): void;
+    private lines;
+    private append;
+    private warn;
+}

package/dist/ledger.js

@@ -0,0 +1,89 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Where the default ledger lives: $SANDBOXROUTER_HOME/sandboxes.jsonl, else ~/.sandboxrouter/.
+ * Returns null when SANDBOXROUTER_LEDGER=off.
+ */
+export function defaultLedgerFile() {
+    if (/^(off|0|false|no)$/i.test(process.env.SANDBOXROUTER_LEDGER ?? ""))
+        return null;
+    return join(process.env.SANDBOXROUTER_HOME || join(homedir(), ".sandboxrouter"), "sandboxes.jsonl");
+}
+/**
+ * A local record of every sandbox this machine's routers created, so a crashed script's sandboxes
+ * can still be found and killed (`sandboxrouter ls` / `gc`). Append-only JSON lines, so several
+ * processes can write at once; `compact()` rewrites it with only the open entries.
+ * Writing never throws: a ledger problem must not break creating or killing a sandbox.
+ */
+export class Ledger {
+    file;
+    warned = false;
+    constructor(file) {
+        this.file = file;
+    }
+    open(e) {
+        this.append({ op: "open", ...e });
+    }
+    close(id, why = "killed") {
+        this.append({ op: "close", id, at: new Date().toISOString(), why });
+    }
+    /** Open entries, oldest first. */
+    list() {
+        const open = new Map();
+        for (const line of this.lines()) {
+            if (line.op === "open") {
+                const { op: _op, ...e } = line;
+                open.set(e.id, e);
+            }
+            else
+                open.delete(line.id);
+        }
+        return [...open.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    /** Rewrite the file with only the open entries. */
+    compact() {
+        const keep = this.list().map((e) => JSON.stringify({ op: "open", ...e })).join("\n");
+        try {
+            const tmp = `${this.file}.${process.pid}.tmp`;
+            writeFileSync(tmp, keep ? `${keep}\n` : "", { mode: 0o600 });
+            renameSync(tmp, this.file);
+        }
+        catch (err) {
+            this.warn(err);
+        }
+    }
+    lines() {
+        if (!existsSync(this.file))
+            return [];
+        const out = [];
+        for (const raw of readFileSync(this.file, "utf8").split("\n")) {
+            if (!raw.trim())
+                continue;
+            try {
+                const l = JSON.parse(raw);
+                if ((l?.op === "open" || l?.op === "close") && typeof l.id === "string")
+                    out.push(l);
+            }
+            catch {
+                // A line cut short by a crash: skip it.
+            }
+        }
+        return out;
+    }
+    append(line) {
+        try {
+            mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
+            appendFileSync(this.file, `${JSON.stringify(line)}\n`, { mode: 0o600 });
+        }
+        catch (err) {
+            this.warn(err);
+        }
+    }
+    warn(err) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        console.warn(`sandboxrouter: couldn't write the sandbox ledger at ${this.file}: ${err.message}`);
+    }
+}

package/dist/providers/agent37.d.ts

@@ -0,0 +1,40 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** Default-type shapes from https://www.agent37.com/docs/agents-api/instance-sizing (2026-11-05). */
+export declare const AGENT37_SHAPES: readonly [{
+    readonly vcpu: 2;
+    readonly memoryGb: 4;
+    readonly diskGb: 4;
+    readonly usdMonth: 4.76;
+    readonly usdHour: number;
+}, {
+    readonly vcpu: 4;
+    readonly memoryGb: 8;
+    readonly diskGb: 6;
+    readonly usdMonth: 9.34;
+    readonly usdHour: number;
+}, {
+    readonly vcpu: 4;
+    readonly memoryGb: 16;
+    readonly diskGb: 12;
+    readonly usdMonth: 15.48;
+    readonly usdHour: number;
+}, {
+    readonly vcpu: 4;
+    readonly memoryGb: 32;
+    readonly diskGb: 24;
+    readonly usdMonth: 27.76;
+    readonly usdHour: number;
+}];
+/** Smallest shape with at least this much CPU and memory, or undefined. */
+export declare function agent37Shape(vcpu: number, memoryGb: number): (typeof AGENT37_SHAPES)[number] | undefined;
+export declare class Agent37Provider implements Provider {
+    private apiKey;
+    private baseUrl;
+    readonly id: "agent37";
+    constructor(apiKey?: string | undefined, baseUrl?: string);
+    configured(): boolean;
+    /** @internal */
+    api<T>(method: string, path: string, json?: unknown, signal?: AbortSignal): Promise<T>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/agent37.js

@@ -0,0 +1,224 @@
+import { ProviderError } from "../types.js";
+import { dirname, shq, toBytes, wrapCommand } from "../util.js";
+/**
+ * Agent37 (YC F26) instances over plain REST. gVisor containers that bill per minute while
+ * running and only for disk while asleep. Fixed shapes, at most 4 vCPU. The workspace wallet is
+ * prepaid, and create needs one day of the instance's running cost in it (402 otherwise).
+ *
+ * https://api.agent37.com, Authorization: Bearer <AGENT37_API_KEY> (sk_live_...):
+ *   POST   /v1/instances {template, resources:{cpu, memory}, auto_sleep, idle_timeout_seconds, env, metadata}
+ *                        201 with the instance once status is "running"
+ *   GET    /v1/instances/:id           -> {id, status, status_reason, url, ...}
+ *   POST   /v1/instances/:id/start, POST /v1/instances/:id/sleep, DELETE /v1/instances/:id
+ *   POST   /v1/instances/:id/exec {command}   -> {exit_code, stdout, stderr, truncated}
+ *          command runs under sh -c; body max 128 KB; stdout and stderr capped at 512 KB each;
+ *          the call waits up to 780 s and the command keeps running if the call gives up.
+ * Status: provisioning, running, stopping, stopped, starting, restarting, updating, sleeping,
+ * waking, failed, deleting, deleted. Errors are {error:{code, message}}.
+ * The files endpoints live on agent templates only, not agent37-base, so files go through exec as
+ * base64, in chunks that fit the request and output caps. exec has no cwd/env/timeout fields, so
+ * those are added to the shell command. No streaming: output arrives when the command ends.
+ * Docs: https://www.agent37.com/docs/agents-api/overview, .../instances/create, .../exec,
+ *       .../instance-sizing, .../instances/sleep, .../instances/object
+ */
+const ID = "agent37";
+const READY_TIMEOUT_MS = 5 * 60_000;
+/** Base64 characters per write request, under the 128 KB body cap. */
+const WRITE_CHUNK_B64 = 96 * 1024;
+/** Raw bytes per read request; base64 of this stays under the 512 KB stdout cap. */
+const READ_CHUNK = 256 * 1024;
+/** Default-type shapes from https://www.agent37.com/docs/agents-api/instance-sizing (2026-11-05). */
+export const AGENT37_SHAPES = [
+    // usdHour = (monthly price at default disk - disk at $0.09/GB-month) / 730 h
+    { vcpu: 2, memoryGb: 4, diskGb: 4, usdMonth: 4.76, usdHour: 4.4 / 730 },
+    { vcpu: 4, memoryGb: 8, diskGb: 6, usdMonth: 9.34, usdHour: 8.8 / 730 },
+    { vcpu: 4, memoryGb: 16, diskGb: 12, usdMonth: 15.48, usdHour: 14.4 / 730 },
+    { vcpu: 4, memoryGb: 32, diskGb: 24, usdMonth: 27.76, usdHour: 25.6 / 730 },
+];
+/** Smallest shape with at least this much CPU and memory, or undefined. */
+export function agent37Shape(vcpu, memoryGb) {
+    return AGENT37_SHAPES.find((s) => s.vcpu >= vcpu && s.memoryGb >= memoryGb);
+}
+export class Agent37Provider {
+    apiKey;
+    baseUrl;
+    id = ID;
+    constructor(apiKey = process.env.AGENT37_API_KEY, baseUrl = process.env.AGENT37_API_URL ?? "https://api.agent37.com") {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    /** @internal */
+    async api(method, path, json, signal) {
+        if (!this.apiKey)
+            throw new ProviderError(ID, "AGENT37_API_KEY is not set");
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${this.apiKey}`, ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
+            body: json !== undefined ? JSON.stringify(json) : undefined,
+            signal,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                const e = j?.error;
+                detail = typeof e === "string" ? e : e?.code ? `${e.code}${e.message ? `: ${e.message}` : ""}` : (j?.message ?? detail);
+            }
+            catch {
+                /* plain-text body */
+            }
+            throw new ProviderError(ID, `${method} ${path} -> ${res.status} ${detail}`, res.status);
+        }
+        return (text ? JSON.parse(text) : {});
+    }
+    async create(spec) {
+        const vcpu = spec.vcpu ?? 2;
+        const memoryGb = spec.memoryGb ?? 4;
+        const shape = agent37Shape(vcpu, memoryGb);
+        if (!shape)
+            throw new ProviderError(ID, `no Agent37 shape has ${vcpu} vCPU / ${memoryGb} GB (max 4 vCPU / 32 GB)`);
+        const idle = Math.min(86_400, Math.max(300, Math.round((spec.timeoutMinutes ?? 30) * 60)));
+        const inst = await this.api("POST", "/v1/instances", {
+            template: spec.image?.agent37 ?? "agent37-base",
+            resources: { cpu: shape.vcpu, memory: shape.memoryGb },
+            // Sleep (disk-only billing) once idle for the requested lifetime, so a leaked box stops costing compute.
+            auto_sleep: true,
+            idle_timeout_seconds: idle,
+            ...(spec.env && Object.keys(spec.env).length ? { env: spec.env } : {}),
+            ...(spec.metadata ? { metadata: spec.metadata } : {}),
+        });
+        if (!inst.id)
+            throw new ProviderError(ID, "create returned no id");
+        const box = new Agent37Box(this, inst.id);
+        try {
+            if (inst.status !== "running")
+                await box.waitRunning();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    async connect(nativeId) {
+        const box = new Agent37Box(this, nativeId);
+        await box.waitRunning();
+        return box;
+    }
+}
+class Agent37Box {
+    p;
+    nativeId;
+    constructor(p, nativeId) {
+        this.p = p;
+        this.nativeId = nativeId;
+    }
+    get path() {
+        return `/v1/instances/${encodeURIComponent(this.nativeId)}`;
+    }
+    /** Poll until running, starting the instance if it sleeps or is stopped. */
+    async waitRunning() {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        let started = false;
+        for (;;) {
+            const inst = await this.p.api("GET", this.path);
+            const status = inst.status ?? "";
+            if (status === "running")
+                return;
+            if (status === "failed" || status === "deleting" || status === "deleted") {
+                throw new ProviderError(ID, `instance ${this.nativeId} is ${status}${inst.status_reason ? `: ${inst.status_reason}` : ""}`, status === "failed" ? undefined : 404);
+            }
+            if ((status === "sleeping" || status === "stopped") && !started) {
+                await this.p.api("POST", `${this.path}/start`);
+                started = true;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `instance ${this.nativeId} not running after ${READY_TIMEOUT_MS / 1000}s (${status || "unknown"})`);
+            await sleep(500);
+        }
+    }
+    async call(command, waitSeconds) {
+        const send = () => this.p.api("POST", `${this.path}/exec`, { command }, AbortSignal.timeout(waitSeconds * 1000));
+        try {
+            return await send();
+        }
+        catch (err) {
+            // A sleeping instance may refuse exec until started.
+            if (err instanceof ProviderError && err.status === 400 && /sleep|stopp/i.test(err.message)) {
+                await this.waitRunning();
+                return send();
+            }
+            throw err;
+        }
+    }
+    /** The exec API has no timeout field, so the command runs under `timeout` when the image has it. */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const secs = opts.timeoutSeconds ?? 60;
+        const inner = wrapCommand(cmd, { cwd: opts.cwd, env: opts.env });
+        const guarded = `if command -v timeout >/dev/null 2>&1; then exec timeout -k 5 ${secs} /bin/sh -c ${shq(inner)}; else exec /bin/sh -c ${shq(inner)}; fi`;
+        let r;
+        try {
+            r = await this.call(guarded, Math.min(secs + 20, 780));
+        }
+        catch (err) {
+            if (err?.name === "TimeoutError")
+                throw new ProviderError(ID, `command timed out after ${secs}s`);
+            throw err;
+        }
+        const durationMs = Date.now() - t0;
+        const exitCode = r.exit_code ?? -1;
+        if (durationMs >= secs * 1000 && [124, 137, 143].includes(exitCode))
+            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, stdout, stderr, durationMs };
+    }
+    async writeFile(path, content) {
+        const b64 = Buffer.from(toBytes(content)).toString("base64");
+        const tmp = `${path}.sbr-part`;
+        let first = true;
+        for (let i = 0; first || i < b64.length; i += WRITE_CHUNK_B64) {
+            const part = b64.slice(i, i + WRITE_CHUNK_B64);
+            const cmd = `${first ? `mkdir -p ${shq(dirname(path))} && ` : ""}printf %s ${shq(part)} | base64 -d ${first ? ">" : ">>"} ${shq(tmp)}`;
+            const r = await this.call(cmd, 120);
+            if (r.exit_code !== 0)
+                throw new ProviderError(ID, `write ${path}: ${r.stderr?.trim() || `exit ${r.exit_code}`}`);
+            first = false;
+        }
+        const r = await this.call(`mv -f ${shq(tmp)} ${shq(path)}`, 60);
+        if (r.exit_code !== 0)
+            throw new ProviderError(ID, `write ${path}: ${r.stderr?.trim() || `exit ${r.exit_code}`}`);
+    }
+    async readFile(path) {
+        const size = await this.call(`wc -c < ${shq(path)}`, 60);
+        if (size.exit_code !== 0)
+            throw new ProviderError(ID, `read ${path}: ${size.stderr?.trim() || "no such file"}`, 404);
+        const total = Number((size.stdout ?? "").trim());
+        const parts = [];
+        for (let off = 0; off < total; off += READ_CHUNK) {
+            const r = await this.call(`tail -c +${off + 1} ${shq(path)} | head -c ${READ_CHUNK} | base64`, 120);
+            if (r.exit_code !== 0)
+                throw new ProviderError(ID, `read ${path}: ${r.stderr?.trim() || `exit ${r.exit_code}`}`);
+            parts.push(Buffer.from((r.stdout ?? "").replace(/\s+/g, ""), "base64"));
+        }
+        return new Uint8Array(Buffer.concat(parts));
+    }
+    async pause() {
+        await this.p.api("POST", `${this.path}/sleep`);
+    }
+    async kill() {
+        await this.p.api("DELETE", this.path);
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/providers/agentcore.d.ts

@@ -0,0 +1,71 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/** True when the default AWS chain plausibly has credentials (env keys, a profile, or a container/web identity). */
+export declare function awsCredentialsHinted(env?: NodeJS.ProcessEnv): boolean;
+/** SigV4-signs and sends JSON requests for one AWS service in one region. */
+export declare class AwsClient {
+    readonly provider: string;
+    readonly service: string;
+    readonly region: string;
+    private credentials?;
+    private signer?;
+    constructor(provider: string, service: string, region: string, credentials?: AwsCredentials | (() => Promise<AwsCredentials>) | undefined);
+    private getSigner;
+    /** Signs and sends; returns the response as-is (callers check status). */
+    send(method: string, url: URL, opts?: {
+        json?: unknown;
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<Response>;
+    /** send() + parse JSON, throwing ProviderError (with the AWS error name) on non-2xx. */
+    json<T>(method: string, url: URL, opts?: {
+        json?: unknown;
+        headers?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<T>;
+}
+export declare function awsFail(provider: string, res: Response, what: string): Promise<never>;
+export interface EventMessage {
+    headers: Record<string, string | number | boolean | Uint8Array>;
+    payload: Uint8Array;
+}
+/**
+ * Decodes the AWS event stream binary framing: [total len u32][headers len u32][prelude crc u32]
+ * [headers][payload][message crc u32]. Header value types per the spec (7 = string).
+ */
+export declare function readEventStream(res: Response): AsyncGenerator<EventMessage>;
+/** Encodes one event stream frame (string headers only). Used by tests' mocks. */
+export declare function encodeEvent(headers: Record<string, string>, payload: Uint8Array | string): Buffer;
+export interface AgentCoreOptions {
+    region?: string;
+    /** Code interpreter id (default aws.codeinterpreter.v1, the AWS-managed one). */
+    codeInterpreterId?: string;
+    /** Override the data-plane base URL (tests). Default https://bedrock-agentcore.{region}.amazonaws.com. */
+    endpoint?: string;
+    /** Static credentials or a provider; default is the standard AWS chain. */
+    credentials?: AwsCredentials | (() => Promise<AwsCredentials>);
+}
+export declare class AgentCoreProvider implements Provider {
+    readonly id: "agentcore";
+    readonly region?: string;
+    readonly interpreter: string;
+    private readonly opts;
+    private client?;
+    constructor(opts?: AgentCoreOptions);
+    /**
+     * Opt-in: AWS credentials alone are common, so the router only uses AgentCore when you name an
+     * interpreter (AGENTCORE_CODE_INTERPRETER_ID=aws.codeinterpreter.v1 for the managed one) or
+     * construct the provider yourself.
+     */
+    configured(): boolean;
+    /** @internal */
+    aws(): AwsClient;
+    /** @internal */
+    url(path: string, query?: Record<string, string>): URL;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}