sbox-sdk 0.0.2

package/dist/agent-tools/registry.js

@@ -0,0 +1,412 @@
+/**
+ * The 10 canonical sandbox tools, each mapped to the real core `Sandbox` API,
+ * plus `createSandboxTools` — the resolver that gates them by the sandbox's
+ * capabilities and applies `only` / `forbid`. This is the single source of
+ * truth every framework adapter projects from.
+ */
+import { z } from "zod";
+import { err, ok } from "./result.js";
+// --------------------------------------------------------------------------
+// annotation presets (MCP-aligned)
+// --------------------------------------------------------------------------
+const READ_ONLY = {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    readOnlyHint: true,
+};
+const MUTATING = {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+};
+const DESTRUCTIVE = {
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+    readOnlyHint: false,
+};
+const EXEC = {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+};
+// --------------------------------------------------------------------------
+// authoring helper — gives type-safe execute, returns a homogeneous ToolSpec
+// --------------------------------------------------------------------------
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function defineTool(def) {
+    const parse = (raw) => def.inputSchema.parse(raw);
+    const { riskFor } = def;
+    return {
+        annotations: def.annotations,
+        description: def.description,
+        async execute(raw, ctx) {
+            let input;
+            try {
+                input = parse(raw);
+            }
+            catch (error) {
+                return err(`invalid input for ${def.name}: ${errMsg(error)}`);
+            }
+            try {
+                return await def.run(input, ctx);
+            }
+            catch (error) {
+                return err(`${def.name} failed: ${errMsg(error)}`);
+            }
+        },
+        inputSchema: def.inputSchema,
+        name: def.name,
+        outputSchema: def.outputSchema,
+        risk: def.risk,
+        riskFor: riskFor ? (raw) => riskFor(parse(raw)) : undefined,
+        title: def.title,
+    };
+}
+// --------------------------------------------------------------------------
+// the 10 tools — each builder closes over the live sandbox
+// --------------------------------------------------------------------------
+const buildExec = (sandbox) => defineTool({
+    annotations: EXEC,
+    description: "Run a shell command in the sandbox and return its stdout, stderr, and exit code. Use for installing packages, running scripts, inspecting files, and general shell work.",
+    inputSchema: z.object({
+        command: z
+            .string()
+            .describe("The shell command to run, e.g. 'ls -la /app'"),
+        cwd: z.string().optional().describe("Working directory for the command"),
+        timeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Abort the command after this many milliseconds"),
+    }),
+    name: "sbox_exec",
+    risk: "mutating",
+    run: async ({ command, cwd, timeoutMs }, ctx) => {
+        const res = await sandbox.commands.run(command, {
+            cwd,
+            signal: ctx.signal,
+            timeoutMs,
+        });
+        const parts = [];
+        if (res.stdout) {
+            parts.push(res.stdout.replace(/\s+$/, ""));
+        }
+        if (res.stderr) {
+            parts.push(`[stderr]\n${res.stderr.replace(/\s+$/, "")}`);
+        }
+        parts.push(`[exit ${res.exitCode}]`);
+        return ok(parts.join("\n"), {
+            exitCode: res.exitCode,
+            stderr: res.stderr,
+            stdout: res.stdout,
+        });
+    },
+    title: "Run shell command",
+});
+const buildRunCode = (sandbox) => defineTool({
+    annotations: MUTATING,
+    description: "Execute a snippet of code in the sandbox's stateful interpreter (e.g. Python/Node) and return its output, rich results, and any error/traceback.",
+    inputSchema: z.object({
+        code: z.string().describe("The source code to execute"),
+        language: z
+            .string()
+            .optional()
+            .describe("Language id, e.g. 'python' or 'javascript'"),
+    }),
+    name: "sbox_run_code",
+    risk: "mutating",
+    run: async ({ code, language }) => {
+        if (!sandbox.code) {
+            return err("code interpreter is not available");
+        }
+        const ex = await sandbox.code.runCode(code, { language });
+        if (ex.error) {
+            return err(`${ex.error.name}: ${ex.error.value}${ex.error.traceback ? `\n${ex.error.traceback}` : ""}`);
+        }
+        const stdout = ex.logs.stdout.join("").replace(/\s+$/, "");
+        const stderr = ex.logs.stderr.join("").replace(/\s+$/, "");
+        const rich = ex.results
+            .map((r) => r.text ?? "")
+            .filter(Boolean)
+            .join("\n");
+        const text = [stdout, stderr, rich].filter(Boolean).join("\n") || "(no output)";
+        return ok(text, ex);
+    },
+    title: "Run code in interpreter",
+});
+const buildFsRead = (sandbox) => defineTool({
+    annotations: READ_ONLY,
+    description: "Read and return the UTF-8 text contents of a file in the sandbox.",
+    inputSchema: z.object({
+        path: z
+            .string()
+            .describe("Absolute or relative path of the file to read"),
+    }),
+    name: "sbox_fs_read",
+    risk: "safe",
+    run: async ({ path }) => {
+        const file = await sandbox.files.read(path);
+        const content = await file.text();
+        return ok(content, { content, path });
+    },
+    title: "Read file",
+});
+const buildFsWrite = (sandbox) => defineTool({
+    annotations: MUTATING,
+    description: "Create or overwrite a file in the sandbox with the given UTF-8 text content.",
+    inputSchema: z.object({
+        content: z.string().describe("The full text content to write"),
+        path: z.string().describe("Path of the file to write"),
+    }),
+    name: "sbox_fs_write",
+    risk: "mutating",
+    run: async ({ path, content }) => {
+        await sandbox.files.write(path, content);
+        return ok(`Wrote ${content.length} bytes to ${path}`, {
+            bytes: content.length,
+            path,
+        });
+    },
+    title: "Write file",
+});
+const buildFsList = (sandbox) => defineTool({
+    annotations: READ_ONLY,
+    description: "List the entries (files and directories) of a directory in the sandbox.",
+    inputSchema: z.object({
+        path: z.string().describe("Path of the directory to list"),
+    }),
+    name: "sbox_fs_list",
+    risk: "safe",
+    run: async ({ path }) => {
+        const entries = await sandbox.files.list(path);
+        const text = entries
+            .map((e) => `${e.type === "dir" ? "d" : e.type === "symlink" ? "l" : "-"} ${e.name}`)
+            .join("\n") || "(empty)";
+        return ok(text, { entries });
+    },
+    title: "List directory",
+});
+const buildFsRemove = (sandbox) => defineTool({
+    annotations: DESTRUCTIVE,
+    description: "Delete a file or directory in the sandbox. Set recursive=true to remove a non-empty directory. This is destructive.",
+    inputSchema: z.object({
+        path: z.string().describe("Path to delete"),
+        recursive: z
+            .boolean()
+            .optional()
+            .describe("Remove directories and their contents recursively"),
+    }),
+    name: "sbox_fs_remove",
+    risk: "destructive",
+    run: async ({ path, recursive }) => {
+        await sandbox.files.remove(path, { recursive });
+        return ok(`Removed ${path}`, { path });
+    },
+    title: "Remove file or directory",
+});
+const buildExposePort = (sandbox) => defineTool({
+    annotations: EXEC,
+    description: "Expose a port running inside the sandbox and return a public preview URL the model (or user) can open.",
+    inputSchema: z.object({
+        port: z.number().int().positive().describe("The port number to expose"),
+        private: z
+            .boolean()
+            .optional()
+            .describe("If true, require an access token instead of being public"),
+    }),
+    name: "sbox_expose_port",
+    risk: "mutating",
+    run: async ({ port, private: isPrivate }) => {
+        if (!sandbox.ports) {
+            return err("port exposure is not available");
+        }
+        const preview = await sandbox.ports.expose(port, { private: isPrivate });
+        return ok(`Exposed port ${port} at ${preview.url}`, preview);
+    },
+    title: "Expose port",
+});
+const buildSnapshot = (sandbox) => defineTool({
+    annotations: MUTATING,
+    description: "Create, restore, list, or delete sandbox snapshots. 'restore' overwrites the sandbox's current state; 'delete' removes a snapshot — both are destructive.",
+    inputSchema: z.object({
+        action: z.enum(["create", "restore", "list", "delete"]),
+        name: z
+            .string()
+            .optional()
+            .describe("Optional name when creating a snapshot"),
+        ref: z
+            .string()
+            .optional()
+            .describe("Snapshot id — required for 'restore' and 'delete'"),
+    }),
+    name: "sbox_snapshot",
+    risk: "mutating",
+    riskFor: ({ action }) => action === "restore" || action === "delete"
+        ? "destructive"
+        : action === "create"
+            ? "mutating"
+            : "safe",
+    run: async ({ action, ref, name }) => {
+        const snaps = sandbox.snapshots;
+        if (!snaps) {
+            return err("snapshots are not supported");
+        }
+        switch (action) {
+            case "create": {
+                const created = await snaps.create({ name });
+                return ok(`Created snapshot ${created.id}`, created);
+            }
+            case "restore": {
+                if (!ref) {
+                    return err("'ref' is required to restore a snapshot");
+                }
+                await snaps.restore(ref);
+                return ok(`Restored snapshot ${ref}`);
+            }
+            case "list": {
+                const list = await snaps.list();
+                return ok(list.map((s) => s.id).join("\n") || "(no snapshots)", list);
+            }
+            case "delete": {
+                if (!ref) {
+                    return err("'ref' is required to delete a snapshot");
+                }
+                await snaps.delete(ref);
+                return ok(`Deleted snapshot ${ref}`);
+            }
+        }
+    },
+    title: "Manage snapshots",
+});
+const buildLifecycle = (sandbox) => defineTool({
+    annotations: MUTATING,
+    description: "Inspect or change the sandbox lifecycle: getInfo, setTimeout, stop, pause, resume, or destroy. 'stop' and 'destroy' tear the sandbox down and are destructive.",
+    inputSchema: z.object({
+        action: z.enum([
+            "getInfo",
+            "setTimeout",
+            "stop",
+            "pause",
+            "resume",
+            "destroy",
+        ]),
+        ttlMs: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("New time-to-live in ms — required for 'setTimeout'"),
+    }),
+    name: "sbox_lifecycle",
+    risk: "mutating",
+    riskFor: ({ action }) => action === "stop" || action === "destroy"
+        ? "destructive"
+        : action === "getInfo"
+            ? "safe"
+            : "mutating",
+    run: async ({ action, ttlMs }) => {
+        switch (action) {
+            case "getInfo": {
+                const info = await sandbox.getInfo();
+                return ok(`state=${info.state} id=${info.id} provider=${info.provider}`, info);
+            }
+            case "setTimeout": {
+                if (ttlMs === undefined || ttlMs === null) {
+                    return err("'ttlMs' is required for setTimeout");
+                }
+                await sandbox.setTimeout(ttlMs);
+                return ok(`Timeout set to ${ttlMs}ms`);
+            }
+            case "stop": {
+                await sandbox.stop();
+                return ok("Sandbox stopped");
+            }
+            case "pause": {
+                await sandbox.pause();
+                return ok("Sandbox paused");
+            }
+            case "resume": {
+                await sandbox.resume();
+                return ok("Sandbox resumed");
+            }
+            case "destroy": {
+                await sandbox.destroy();
+                return ok("Sandbox destroyed");
+            }
+        }
+    },
+    title: "Sandbox lifecycle",
+});
+const buildSetEgress = (sandbox) => defineTool({
+    annotations: MUTATING,
+    description: "Set the sandbox's outbound network policy: allow all, block all, or allow only specific domains/CIDRs.",
+    inputSchema: z.object({
+        cidrs: z
+            .array(z.string())
+            .optional()
+            .describe("Allowed CIDR ranges when mode is 'allow-list'"),
+        domains: z
+            .array(z.string())
+            .optional()
+            .describe("Allowed domains when mode is 'allow-list'"),
+        mode: z.enum(["allow-all", "block-all", "allow-list"]),
+    }),
+    name: "sbox_set_egress",
+    risk: "mutating",
+    run: async ({ mode, domains, cidrs }) => {
+        if (!sandbox.network) {
+            return err("egress control is not supported");
+        }
+        await sandbox.network.setEgressPolicy({ cidrs, domains, mode });
+        return ok(`Egress policy set to ${mode}`);
+    },
+    title: "Set egress policy",
+});
+const ENTRIES = [
+    { build: buildExec, gate: () => true, name: "sbox_exec" },
+    {
+        build: buildRunCode,
+        gate: (s) => s.can("codeInterpreter"),
+        name: "sbox_run_code",
+    },
+    { build: buildFsRead, gate: () => true, name: "sbox_fs_read" },
+    { build: buildFsWrite, gate: () => true, name: "sbox_fs_write" },
+    { build: buildFsList, gate: () => true, name: "sbox_fs_list" },
+    { build: buildFsRemove, gate: () => true, name: "sbox_fs_remove" },
+    {
+        build: buildExposePort,
+        gate: (s) => s.can("exposePort"),
+        name: "sbox_expose_port",
+    },
+    {
+        build: buildSnapshot,
+        gate: (s) => s.can("snapshot"),
+        name: "sbox_snapshot",
+    },
+    { build: buildLifecycle, gate: () => true, name: "sbox_lifecycle" },
+    {
+        build: buildSetEgress,
+        gate: (s) => s.can("egressControl"),
+        name: "sbox_set_egress",
+    },
+];
+/**
+ * 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 function createSandboxTools(sandbox, opts = {}) {
+    const only = opts.only ? new Set(opts.only) : undefined;
+    const forbid = new Set([
+        ...(opts.policy?.forbid ?? []),
+        ...(opts.forbid ?? []),
+    ]);
+    return ENTRIES.filter((e) => e.gate(sandbox) && (!only || only.has(e.name)) && !forbid.has(e.name)).map((e) => e.build(sandbox));
+}

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

@@ -0,0 +1,32 @@
+/**
+ * The normalized result every tool returns. `text` is always the model-facing
+ * rendering; `output` is the optional structured value. Each framework adapter
+ * serializes ONE of these into its own tool-result shape (AI SDK value,
+ * Anthropic `tool_result` block, OpenAI string, Mastra output object).
+ */
+export interface ToolResultContent {
+    type: "text" | "image";
+    /** present when type === "text" */
+    text?: string;
+    /** base64-encoded payload, present when type === "image" */
+    data?: string;
+    /** e.g. "image/png", present when type === "image" */
+    mediaType?: string;
+}
+export interface ToolResult<O = unknown> {
+    /** false signals a tool-level failure (non-zero exit, denied, provider error). */
+    ok: boolean;
+    /** Always present — what the model reads. */
+    text: string;
+    /** Structured, machine-readable result (when the tool produces one). */
+    output?: O;
+    /** Mirrors `ok === false`; surfaced as `is_error` by adapters that support it. */
+    isError?: boolean;
+    /** Optional rich blocks for adapters that accept them (e.g. Anthropic images). */
+    content?: ToolResultContent[];
+}
+/** A successful result. */
+export declare function ok<O>(text: string, output?: O): ToolResult<O>;
+/** A tool-level failure — never thrown, always returned so the agent can react. */
+export declare function err(text: string): ToolResult<never>;
+//# sourceMappingURL=result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/agent-tools/result.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,kFAAkF;IAClF,EAAE,EAAE,OAAO,CAAC;IACZ,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED,2BAA2B;AAC3B,wBAAgB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAE7D;AAED,mFAAmF;AACnF,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAEnD"}

package/dist/agent-tools/result.js

@@ -0,0 +1,14 @@
+/**
+ * The normalized result every tool returns. `text` is always the model-facing
+ * rendering; `output` is the optional structured value. Each framework adapter
+ * serializes ONE of these into its own tool-result shape (AI SDK value,
+ * Anthropic `tool_result` block, OpenAI string, Mastra output object).
+ */
+/** A successful result. */
+export function ok(text, output) {
+    return { ok: true, output, text };
+}
+/** A tool-level failure — never thrown, always returned so the agent can react. */
+export function err(text) {
+    return { isError: true, ok: false, text };
+}

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

@@ -0,0 +1,76 @@
+/**
+ * The provider- AND framework-agnostic tool model. A `ToolSpec` is the single
+ * source of truth for one sandbox tool; every framework adapter is a pure
+ * projection `ToolSpec -> that framework's tool object`, and the (future) MCP
+ * server + Agent Skills read from the very same specs.
+ */
+import type { z } from "zod";
+import type { Sandbox } from "../internal/types.js";
+import type { ToolResult } from "./result.js";
+/** The fixed set of canonical sandbox tools. */
+export type ToolName = "sbox_exec" | "sbox_run_code" | "sbox_fs_read" | "sbox_fs_write" | "sbox_fs_list" | "sbox_fs_remove" | "sbox_expose_port" | "sbox_snapshot" | "sbox_lifecycle" | "sbox_set_egress";
+/** Drives the default approval posture (see SandboxPolicy). */
+export type Risk = "safe" | "mutating" | "destructive";
+/** MCP-aligned behavioral hints, reused verbatim by the future MCP server. */
+export interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/** Threaded into every tool execution and policy rule. `sandbox` is optional:
+ *  a spec's `execute` closes over its own sandbox, so it is only needed by
+ *  policy rules that introspect the sandbox (absent when adapters are handed a
+ *  pre-built `ToolSpec[]` rather than a live sandbox). */
+export interface ToolRunContext {
+    readonly sandbox?: Sandbox;
+    readonly signal?: AbortSignal;
+}
+/**
+ * One canonical tool. Homogeneous (input typed `unknown`) so the registry can
+ * hold `ToolSpec[]`; `execute` validates its input against `inputSchema` before
+ * running, so adapters may forward framework-parsed args as-is.
+ */
+export interface ToolSpec {
+    readonly name: ToolName;
+    /** Short human label (not shown to the model). */
+    readonly title: string;
+    /** Model-facing description — written for an agent, not a human reader. */
+    readonly description: string;
+    /** Zod is the lingua franca: AI SDK / Mastra / OpenAI / LangChain take it
+     *  directly; the Anthropic adapter converts it to JSON Schema. */
+    readonly inputSchema: z.ZodType;
+    /** Optional structured-output schema (consumed by e.g. Mastra). */
+    readonly outputSchema?: z.ZodType;
+    /** Declared (base) risk; refine per-input via `riskFor`. */
+    readonly risk: Risk;
+    readonly annotations: ToolAnnotations;
+    /** Per-input risk refinement for multi-verb tools (lifecycle, snapshot). */
+    riskFor?(input: unknown): Risk;
+    /** Runs the operation. MUST resolve a ToolResult — never throw for tool-level
+     *  failure (return `err(...)`); may throw only on truly unexpected errors. */
+    execute(input: unknown, ctx: ToolRunContext): Promise<ToolResult>;
+}
+/** Options accepted by `createSandboxTools` and every `toXTools` adapter. */
+export interface ToolSetOptions {
+    /** Approval policy (also carries `forbid`). */
+    policy?: import("./policy.js").SandboxPolicy;
+    /** Allow-list: when set, only these tools are produced. */
+    only?: ToolName[];
+    /** Removed entirely from the produced set (merged with `policy.forbid`). */
+    forbid?: ToolName[];
+}
+/**
+ * A framework "provider" for the `ai()` plugin: knows how to turn a sandbox into
+ * one agent framework's tool objects. Returned by the framework subpaths
+ * (`aiSdk()`, `mastra()`, `openaiAgents()`, `anthropic()`, `langchain()`) and
+ * passed to `ai({ framework })`. `TTools` is the framework's tool shape, so
+ * `sandbox.tools` stays correctly typed.
+ */
+export interface FrameworkAdapter<TTools = unknown> {
+    /** Stable id, e.g. "ai-sdk" or "openai". */
+    readonly name: string;
+    /** Project the sandbox's (capability-gated, policy-aware) tools. */
+    build(sandbox: Sandbox, opts: ToolSetOptions): TTools;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent-tools/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,gDAAgD;AAChD,MAAM,MAAM,QAAQ,GAChB,WAAW,GACX,eAAe,GACf,cAAc,GACd,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,+DAA+D;AAC/D,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC;AAEvD,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;0DAG0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;sEACkE;IAClE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,4EAA4E;IAC5E,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B;kFAC8E;IAC9E,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,aAAa,CAAC;IAC7C,2DAA2D;IAC3D,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC;IAClB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,OAAO;IAChD,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC;CACvD"}

package/dist/agent-tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `sbox-sdk/ai` — the umbrella AI-provider plugin. Pick a framework adapter from
+ * its subpath (`aiSdk()`, `mastra()`, `openaiAgents()`, `anthropic()`,
+ * `langchain()`) and pass it in; `ai()` grafts the framework-shaped tools onto
+ * `sandbox.tools`. Core-only — no framework SDK is imported here, so this stays
+ * dependency-free; the framework you import decides what gets bundled.
+ *
+ * ```ts
+ * import { createSandboxClient } from "sbox-sdk";
+ * import { e2b } from "sbox-sdk/e2b";
+ * import { ai } from "sbox-sdk/ai";
+ * import { aiSdk } from "sbox-sdk/ai-sdk";
+ *
+ * const client = createSandboxClient({
+ *   provider: e2b(),
+ *   plugins: [ai({ framework: aiSdk(), policy })],
+ * });
+ * const sandbox = await client.create();
+ * await generateText({ model, prompt, tools: sandbox.tools });
+ * ```
+ */
+import type { FrameworkAdapter, ToolSetOptions } from "../agent-tools/index.js";
+import type { SandboxPlugin } from "../internal/plugin.js";
+export interface AIOptions<TTools> extends ToolSetOptions {
+    /** The agent framework to target — `aiSdk()`, `openaiAgents()`, … */
+    framework: FrameworkAdapter<TTools>;
+}
+/**
+ * The single AI-provider plugin. Shapes `sandbox.tools` for the given framework,
+ * capability-gated to the provider and gated by the optional `policy`. Per-sandbox
+ * overrides passed to `client.create(spec, options)` are merged over the defaults.
+ */
+export declare function ai<TTools>(opts: AIOptions<TTools>): SandboxPlugin<{
+    tools: TTools;
+}>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAsB,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,WAAW,SAAS,CAAC,MAAM,CAAE,SAAQ,cAAc;IACvD,qEAAqE;IACrE,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;CACrC;AA+BD;;;;GAIG;AACH,wBAAgB,EAAE,CAAC,MAAM,EACvB,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GACtB,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAYlC"}

package/dist/ai/index.js

@@ -0,0 +1,40 @@
+/**
+ * Merge per-sandbox overrides from `client.create(spec, options)` over the
+ * plugin's client-wide defaults. Only `policy`, `only`, and `forbid` are honored
+ * — never the framework. `policy` is shallow-merged so a single sandbox can
+ * tighten its trust posture; `only`/`forbid` are replaced when provided. This is
+ * what makes an untrusted sandbox's policy actually take effect rather than
+ * silently inheriting the laxer client default.
+ */
+function resolveToolOptions(base, createOptions) {
+    if (!createOptions) {
+        return base;
+    }
+    const override = createOptions;
+    const merged = { ...base };
+    if (override.policy) {
+        merged.policy = { ...base.policy, ...override.policy };
+    }
+    if (override.only) {
+        merged.only = override.only;
+    }
+    if (override.forbid) {
+        merged.forbid = override.forbid;
+    }
+    return merged;
+}
+/**
+ * The single AI-provider plugin. Shapes `sandbox.tools` for the given framework,
+ * capability-gated to the provider and gated by the optional `policy`. Per-sandbox
+ * overrides passed to `client.create(spec, options)` are merged over the defaults.
+ */
+export function ai(opts) {
+    const { framework, ...toolOptions } = opts;
+    return {
+        extend: (sandbox, ctx) => ({
+            tools: framework.build(sandbox, resolveToolOptions(toolOptions, ctx.createOptions)),
+        }),
+        kind: "ai-provider",
+        name: `ai:${framework.name}`,
+    };
+}

package/dist/ai-sdk/index.d.ts

@@ -0,0 +1,31 @@
+import type { Tool } from "ai";
+import type { FrameworkAdapter, ToolSetOptions, ToolSpec } from "../agent-tools/types.js";
+import type { Sandbox } from "../internal/types.js";
+export type AISDKToolOptions = ToolSetOptions;
+/** The AI SDK tool map: `{ [toolName]: Tool }`. */
+export type AISDKToolSet = Record<string, Tool>;
+/**
+ * Build AI SDK tools from a live sandbox (capability-gated) or a pre-built
+ * `ToolSpec[]`. Hand the result to `generateText({ tools })`.
+ */
+export declare function toAISDKTools(source: Sandbox | ToolSpec[], opts?: AISDKToolOptions): AISDKToolSet;
+/**
+ * The Vercel AI SDK framework adapter for the `ai()` plugin:
+ *
+ * ```ts
+ * import { ai } from "sbox-sdk/ai";
+ * import { aiSdk } from "sbox-sdk/ai-sdk";
+ *
+ * const client = createSandboxClient({ provider: e2b(), plugins: [ai({ framework: aiSdk() })] });
+ * const sandbox = await client.create();
+ * await generateText({ model, prompt, tools: sandbox.tools });
+ * ```
+ */
+export declare function aiSdk(): FrameworkAdapter<AISDKToolSet>;
+/**
+ * AI SDK v7 forward-compat: build the call-site `toolApproval` map
+ * (`generateText({ tools, toolApproval })`) from the same policy. Each entry
+ * returns `"user-approval"` when the policy says "ask", else `undefined`.
+ */
+export declare function toolApproval(source: Sandbox | ToolSpec[], opts?: AISDKToolOptions): Record<string, (input: unknown) => Promise<"user-approval" | undefined>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAI/B,OAAO,KAAK,EACV,gBAAgB,EAEhB,cAAc,EACd,QAAQ,EACT,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE9C,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAahD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,EAC5B,IAAI,GAAE,gBAAqB,GAC1B,YAAY,CAoBd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,IAAI,gBAAgB,CAAC,YAAY,CAAC,CAKtD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,EAC5B,IAAI,GAAE,gBAAqB,GAC1B,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC,CAc1E"}