sbox-sdk 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivek Kornepalli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# sbox-sdk
+
+One unified SDK for agent **sandbox** providers (E2B, Vercel Sandbox, Cloudflare Sandbox, and more). Write your code once; swap the adapter import to change provider — the rest of your code stays the same.
+
+> Status: **alpha** (`0.0.1`). Ships adapters for E2B, Vercel, Cloudflare, Daytona, Modal, Fly, AWS Lambda, Northflank, Runloop, CodeSandbox, Morph, Blaxel, Beam, and Railway — plus a built-in **in-memory** provider for tests/dev. E2B is the most battle-tested; the newer adapters pass the shared conformance suite offline but are less proven against live APIs.
+
+## Install
+
+```bash
+npm install sbox-sdk
+# then install the provider SDK you use (optional peer dependency):
+npm install @e2b/code-interpreter
+```
+
+## Quickstart
+
+```ts
+import { createSandboxClient } from "sbox-sdk";
+import { e2b } from "sbox-sdk/e2b";
+
+const client = createSandboxClient({
+  provider: e2b({ apiKey: process.env.E2B_API_KEY! }),
+});
+const sandbox = await client.create({ template: "python-3.12", ttlMs: 60_000 });
+
+// exec — await for a buffered result (never throws on non-zero exit):
+const res = await sandbox.commands.run("echo hi", { cwd: "/app" });
+console.log(res.exitCode, res.stdout);
+
+// ...or for-await the SAME handle to stream live:
+for await (const ev of sandbox.commands.run(["python", "train.py"])) {
+  if (ev.type === "stdout") process.stdout.write(ev.data);
+}
+
+// filesystem (web-standard bodies in, StoredFile out):
+await sandbox.files.write("/app/data.json", JSON.stringify({ ok: true }));
+const text = await (await sandbox.files.read("/app/data.json")).text();
+
+await sandbox.destroy();
+await client.dispose();
+```
+
+Zero config? `createSandboxClient()` defaults to an in-memory provider — great for tests:
+
+```ts
+import { createSandboxClient } from "sbox-sdk";
+const sb = await createSandboxClient().create();
+await sb.commands.run("echo works offline");
+```
+
+## Swap providers, keep your code
+
+```ts
+import { vercel } from "sbox-sdk/vercel";
+const client = createSandboxClient({
+  provider: vercel({ token, teamId, projectId }),
+});
+// every sandbox.commands / sandbox.files call site above is unchanged
+```
+
+## Providers
+
+Import a provider from its subpath and install its SDK as an (optional) peer:
+
+| Provider    | Import                 | Peer SDK                          |
+| ----------- | ---------------------- | --------------------------------- |
+| E2B         | `sbox-sdk/e2b`         | `@e2b/code-interpreter`           |
+| Vercel      | `sbox-sdk/vercel`      | `@vercel/sandbox`                 |
+| Cloudflare  | `sbox-sdk/cloudflare`  | `@cloudflare/sandbox`             |
+| Daytona     | `sbox-sdk/daytona`     | `@daytonaio/sdk`                  |
+| Modal       | `sbox-sdk/modal`       | `modal`                           |
+| Fly         | `sbox-sdk/fly`         | _none (REST)_                     |
+| AWS Lambda  | `sbox-sdk/aws-lambda`  | `@aws-sdk/client-lambda-microvms` |
+| Northflank  | `sbox-sdk/northflank`  | `@northflank/js-client`           |
+| Runloop     | `sbox-sdk/runloop`     | `@runloop/api-client`             |
+| CodeSandbox | `sbox-sdk/codesandbox` | `@codesandbox/sdk`                |
+| Morph       | `sbox-sdk/morph`       | `morphcloud`                      |
+| Blaxel      | `sbox-sdk/blaxel`      | `@blaxel/core`                    |
+| Beam        | `sbox-sdk/beam`        | `@beamcloud/beam-js`              |
+| Railway     | `sbox-sdk/railway`     | `railway`                         |
+
+The in-memory provider (`sbox-sdk/memory`, also the zero-config default) needs no peer.
+
+## Capability gating
+
+Each provider declares a static capability table. Sub-APIs that a provider doesn't support are typed `undefined` — calling them is a **compile error**, and unsupported features throw `NotSupportedError` at runtime _before_ any network call.
+
+```ts
+// `sandbox.code` only exists on providers with a code interpreter (e.g. E2B):
+if (sandbox.code) {
+  const exec = await sandbox.code.runCode(
+    "import matplotlib.pyplot as plt; plt.plot([1,2,3])"
+  );
+  for (const r of exec.results)
+    if (r.mime["image/png"]) save(r.mime["image/png"]);
+}
+
+// runtime tri-state level (native | emulated | unsupported):
+console.log(sandbox.capabilities.map.snapshot);
+
+// dynamic providers: `can()` narrows at runtime + type level:
+if (sandbox.can("snapshot")) await sandbox.snapshots.create({ name: "ckpt" });
+```
+
+## Errors
+
+All providers normalize to one `SandboxError` taxonomy (`code`, `provider`, `retryable`, …). Key rules:
+
+- `commands.run(...)` **never throws on a non-zero exit** — the exit code is data (`result.exitCode`).
+- `files.exists()` returns `false` only on NotFound; auth/timeout errors throw.
+- `NotSupportedError` is thrown synchronously, before any network call.
+
+## Writing an adapter
+
+Implement the `SandboxProvider` contract from `sbox-sdk/adapter` and run it through the shared conformance suite:
+
+```ts
+import { runConformance } from "sbox-sdk/conformance";
+const report = await runConformance(myProvider());
+expect(report.passed).toBe(true);
+```
+
+## CLI
+
+The package ships a `sbox` bin. `caps` and `doctor` run fully offline; `exec`
+and `list` read credentials from the environment.
+
+```bash
+npx sbox caps e2b              # print a provider's capability matrix
+npx sbox doctor e2b           # check node + whether the provider SDK is installed
+npx sbox exec e2b -- echo hi  # run one command in a fresh sandbox
+npx sbox list e2b             # list live sandboxes
+```
+
+## License
+
+MIT

package/dist/adapter/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `sbox-sdk/adapter` — the authoring kit for provider adapters. Implement
+ * `SandboxProvider` and return it from a factory wrapped in `defineProvider`.
+ * Everything an adapter needs (contract types, capability helpers, the error
+ * taxonomy, and shell-emulation helpers) is re-exported from here.
+ */
+import type { CapabilityMap } from "../internal/capabilities.js";
+import type { SandboxProvider } from "../internal/types.js";
+/** Typed-identity wrapper so a provider factory infers its Caps/Raw/Opts. */
+export declare function defineProvider<Caps extends CapabilityMap, Raw, Opts>(factory: (opts: Opts) => SandboxProvider<Caps, Raw>): (opts: Opts) => SandboxProvider<Caps, Raw>;
+export type { SandboxProvider, DriverHandle, DriverExec, DriverProcess, CallContext, MaybePromise, SandboxSpec, SandboxInfo, SandboxState, ResourceSpec, VolumeMount, SecretRef, ExecOptions, ExecResult, OutputEvent, ProcessInfo, FileBody, FileType, FileInfo, DirEntry, StoredFile, FsEvent, Preview, EgressPolicy, SshCredentials, KernelContext, RichResult, CodeExecution, SnapshotRef, ListFilter, } from "../internal/types.js";
+export { baseCapabilities, defaultFlags, freezeCapabilities, isCapable, assertCapability, } from "../internal/capabilities.js";
+export type { CapabilityMap, CapabilityLevel, CapabilityName, CapabilityFlags, Capabilities, PreviewModel, } from "../internal/capabilities.js";
+export { SandboxError, NotSupportedError, ProviderNotFoundError, AllProvidersFailedError, isRetryableStatus, isRetryableError, } from "../internal/errors.js";
+export type { SandboxErrorCode, SandboxErrorInit, ProviderAttempt, } from "../internal/errors.js";
+export { shellQuote, joinCmd, buildExecCommand, parseLsOutput, parseStatOutput, EXIT_MARKER, } from "../internal/shell.js";
+export type { BuiltExec } from "../internal/shell.js";
+export { detectRuntime, hasFetch } from "../internal/runtime.js";
+export type { Runtime } from "../internal/runtime.js";
+export { AsyncQueue, numExit } from "../internal/stream.js";
+export { base64ToBytes, bytesToBase64 } from "../internal/encoding.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,SAAS,aAAa,EAAE,GAAG,EAAE,IAAI,EAClE,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,GAClD,CAAC,IAAI,EAAE,IAAI,KAAK,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAE5C;AAGD,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,OAAO,EACP,OAAO,EACP,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,EACV,aAAa,EACb,WAAW,EACX,UAAU,GACX,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,SAAS,EACT,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,YAAY,GACb,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,UAAU,EACV,OAAO,EACP,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACjE,YAAY,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/adapter/index.js

@@ -0,0 +1,16 @@
+/** Typed-identity wrapper so a provider factory infers its Caps/Raw/Opts. */
+export function defineProvider(factory) {
+    return factory;
+}
+// ---- capability helpers + types ----
+export { baseCapabilities, defaultFlags, freezeCapabilities, isCapable, assertCapability, } from "../internal/capabilities.js";
+// ---- error taxonomy ----
+export { SandboxError, NotSupportedError, ProviderNotFoundError, AllProvidersFailedError, isRetryableStatus, isRetryableError, } from "../internal/errors.js";
+// ---- shell-emulation helpers (for exec-over-transport adapters) ----
+export { shellQuote, joinCmd, buildExecCommand, parseLsOutput, parseStatOutput, EXIT_MARKER, } from "../internal/shell.js";
+// ---- runtime probe ----
+export { detectRuntime, hasFetch } from "../internal/runtime.js";
+// ---- stream bridge (push callbacks -> AsyncIterable<OutputEvent>) ----
+export { AsyncQueue, numExit } from "../internal/stream.js";
+// ---- encoding helpers (exec-over-text fs) ----
+export { base64ToBytes, bytesToBase64 } from "../internal/encoding.js";

package/dist/agent-tools/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `sbox-sdk/agent-tools` — the framework-agnostic agent-tooling core. Build a
+ * provider-neutral tool set from any sandbox, then project it into a framework
+ * with one of the adapter subpaths (`sbox-sdk/ai-sdk`, `/openai`, …) or feed it
+ * to the (future) MCP server. Depends only on the core SDK + `zod`.
+ */
+export { createSandboxTools } from "./registry.js";
+export type { ToolName, Risk, ToolAnnotations, ToolRunContext, ToolSpec, ToolSetOptions, FrameworkAdapter, } from "./types.js";
+export { ok, err } from "./result.js";
+export type { ToolResult, ToolResultContent } from "./result.js";
+export { decide, effectiveRisk, enforcePolicy, DEFAULT_DECISIONS, } from "./policy.js";
+export type { Decision, SandboxPolicy, ApprovalRequest, AuditRecord, } from "./policy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agent-tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,YAAY,EACV,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,cAAc,EACd,QAAQ,EACR,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEjE,OAAO,EACL,MAAM,EACN,aAAa,EACb,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,QAAQ,EACR,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,aAAa,CAAC"}

package/dist/agent-tools/index.js

@@ -0,0 +1,9 @@
+/**
+ * `sbox-sdk/agent-tools` — the framework-agnostic agent-tooling core. Build a
+ * provider-neutral tool set from any sandbox, then project it into a framework
+ * with one of the adapter subpaths (`sbox-sdk/ai-sdk`, `/openai`, …) or feed it
+ * to the (future) MCP server. Depends only on the core SDK + `zod`.
+ */
+export { createSandboxTools } from "./registry.js";
+export { ok, err } from "./result.js";
+export { decide, effectiveRisk, enforcePolicy, DEFAULT_DECISIONS, } from "./policy.js";

package/dist/agent-tools/policy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The single, framework-agnostic approval model. One `SandboxPolicy` is
+ * authored once; each adapter translates a `Decision` into that framework's
+ * native human-in-the-loop mechanism (AI SDK `needsApproval`, OpenAI
+ * interruptions, Mastra `suspend()`, or an `onApprovalRequest` gate).
+ */
+import type { Risk, ToolName, ToolRunContext, ToolSpec } from "./types.js";
+export type Decision = "allow" | "ask" | "deny";
+export interface ApprovalRequest {
+    readonly tool: ToolName;
+    readonly title: string;
+    readonly input: unknown;
+    readonly risk: Risk;
+    readonly sandboxId: string;
+}
+export interface AuditRecord {
+    readonly tool: ToolName;
+    readonly input: unknown;
+    readonly risk: Risk;
+    readonly decision: Decision;
+    readonly sandboxId: string;
+}
+export interface SandboxPolicy {
+    /** Per-risk default decision. Defaults to DEFAULT_DECISIONS below. */
+    defaults?: Partial<Record<Risk, Decision>>;
+    /** Per-tool override; may inspect the actual input. Wins over `defaults`. */
+    rules?: Partial<Record<ToolName, (input: unknown, ctx: ToolRunContext) => Decision>>;
+    /** Hard removal — tool never appears in the produced set. */
+    forbid?: ToolName[];
+    /** Used by adapters with no native HITL (Anthropic, LangChain without a graph). */
+    onApprovalRequest?: (req: ApprovalRequest) => boolean | Promise<boolean>;
+    /** Observe every decision (logging, metrics, audit trails). */
+    audit?: (rec: AuditRecord) => void;
+}
+/** Sensible default: only destructive actions pause for approval. */
+export declare const DEFAULT_DECISIONS: Readonly<Record<Risk, Decision>>;
+/** Effective risk for a given input (refined for multi-verb tools). */
+export declare function effectiveRisk(spec: ToolSpec, input: unknown): Risk;
+/** Resolve the approval decision for one tool call. */
+export declare function decide(spec: ToolSpec, input: unknown, ctx: ToolRunContext, policy?: SandboxPolicy): Decision;
+/**
+ * Shared approval gate used by adapters without native HITL (and as the portable
+ * default everywhere). Returns `null` when the call may proceed, or a denial
+ * message the model can read. `"ask"` awaits `onApprovalRequest` when configured;
+ * otherwise it proceeds (human-in-the-loop is opt-in). Emits `audit` records.
+ */
+export declare function enforcePolicy(spec: ToolSpec, input: unknown, ctx: ToolRunContext, policy?: SandboxPolicy): Promise<string | null>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/agent-tools/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/agent-tools/policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3C,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CACb,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,KAAK,QAAQ,CAAC,CACpE,CAAC;IACF,6DAA6D;IAC7D,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IACpB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,+DAA+D;IAC/D,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;CACpC;AAED,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAI9D,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAElE;AAED,uDAAuD;AACvD,wBAAgB,MAAM,CACpB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,cAAc,EACnB,MAAM,CAAC,EAAE,aAAa,GACrB,QAAQ,CAUV;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,cAAc,EACnB,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBxB"}

package/dist/agent-tools/policy.js

@@ -0,0 +1,51 @@
+/** Sensible default: only destructive actions pause for approval. */
+export const DEFAULT_DECISIONS = {
+    destructive: "ask",
+    mutating: "allow",
+    safe: "allow",
+};
+/** Effective risk for a given input (refined for multi-verb tools). */
+export function effectiveRisk(spec, input) {
+    return spec.riskFor?.(input) ?? spec.risk;
+}
+/** Resolve the approval decision for one tool call. */
+export function decide(spec, input, ctx, policy) {
+    if (policy?.forbid?.includes(spec.name)) {
+        return "deny";
+    }
+    const rule = policy?.rules?.[spec.name];
+    if (rule) {
+        return rule(input, ctx);
+    }
+    const risk = effectiveRisk(spec, input);
+    return policy?.defaults?.[risk] ?? DEFAULT_DECISIONS[risk];
+}
+/**
+ * Shared approval gate used by adapters without native HITL (and as the portable
+ * default everywhere). Returns `null` when the call may proceed, or a denial
+ * message the model can read. `"ask"` awaits `onApprovalRequest` when configured;
+ * otherwise it proceeds (human-in-the-loop is opt-in). Emits `audit` records.
+ */
+export async function enforcePolicy(spec, input, ctx, policy) {
+    const risk = effectiveRisk(spec, input);
+    const sandboxId = ctx.sandbox?.id ?? "";
+    const audit = (decision) => policy?.audit?.({ decision, input, risk, sandboxId, tool: spec.name });
+    const decision = decide(spec, input, ctx, policy);
+    if (decision === "deny") {
+        audit("deny");
+        return `Denied by policy: ${spec.name} is not permitted.`;
+    }
+    if (decision === "ask" && policy?.onApprovalRequest) {
+        const approved = await policy.onApprovalRequest({
+            input,
+            risk,
+            sandboxId,
+            title: spec.title,
+            tool: spec.name,
+        });
+        audit(approved ? "allow" : "deny");
+        return approved ? null : `Approval denied for ${spec.name}.`;
+    }
+    audit("allow");
+    return null;
+}

package/dist/agent-tools/registry.d.ts

@@ -0,0 +1,9 @@
+import type { Sandbox } from "../internal/types.js";
+import type { ToolSetOptions, ToolSpec } from "./types.js";
+/**
+ * Build the provider-neutral tool set for a sandbox: only the tools whose
+ * capabilities the provider supports, minus `forbid`, intersected with `only`.
+ * This `ToolSpec[]` is the input to every `toXTools` adapter.
+ */
+export declare function createSandboxTools(sandbox: Sandbox, opts?: ToolSetOptions): ToolSpec[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/agent-tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agent-tools/registry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,KAAK,EAKV,cAAc,EACd,QAAQ,EACT,MAAM,YAAY,CAAC;AA+cpB;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE,cAAmB,GACxB,QAAQ,EAAE,CASZ"}