agentbox-sdk 0.1.0 → 0.1.1

package/README.md

@@ -18,7 +18,7 @@ const run = new Agent("claude-code", {
   cwd: "/workspace",
   approvalMode: "auto",
 }).stream({
-  model: "claude-sonnet-4-6",
+  model: "sonnet",
   input: "Create a hello world Express server in /workspace/server.ts",
 });
 
@@ -32,7 +32,7 @@ await sandbox.delete();
 Providers are mix-and-match:
 
 - **Agents** — [`claude-code`](./src/agents/providers/claude-code.ts), [`opencode`](./src/agents/providers/opencode.ts), [`codex`](./src/agents/providers/codex.ts)
-- **Sandboxes** — [`local-docker`](./src/sandboxes/providers/local-docker.ts), [`e2b`](./src/sandboxes/providers/e2b.ts), [`modal`](./src/sandboxes/providers/modal.ts), [`daytona`](./src/sandboxes/providers/daytona.ts)
+- **Sandboxes** — [`local-docker`](./src/sandboxes/providers/local-docker.ts), [`e2b`](./src/sandboxes/providers/e2b.ts), [`modal`](./src/sandboxes/providers/modal.ts), [`daytona`](./src/sandboxes/providers/daytona.ts), [`vercel`](./src/sandboxes/providers/vercel.ts)
 
 Swap either one and your app code stays the same.
 
@@ -78,7 +78,7 @@ const agent = new Agent("claude-code", {
 });
 
 const result = await agent.run({
-  model: "claude-sonnet-4-6",
+  model: "sonnet",
   input:
     "Explain the project structure and write a summary to /workspace/OVERVIEW.md",
 });
@@ -93,7 +93,7 @@ await sandbox.delete();
 
 ```ts
 const run = agent.stream({
-  model: "claude-sonnet-4-6",
+  model: "sonnet",
   input: "Write a fizzbuzz in Python",
 });
 
@@ -112,9 +112,9 @@ Three agent providers are supported. Each wraps a CLI that runs inside the sandb
 
 | Provider      | CLI        | Model format                                    |
 | ------------- | ---------- | ----------------------------------------------- |
-| `claude-code` | `claude`   | `claude-sonnet-4-6`                             |
+| `claude-code` | `claude`   | `sonnet`, `opus`, `haiku`                       |
 | `opencode`    | `opencode` | `anthropic/claude-sonnet-4-6`, `openai/gpt-4.1` |
-| `codex`       | `codex`    | `gpt-5-codex`                                   |
+| `codex`       | `codex`    | `gpt-5.3-codex`, `gpt-5.4`                      |
 
 ```ts
 new Agent("claude-code", { sandbox, cwd: "/workspace", approvalMode: "auto" });
@@ -124,17 +124,31 @@ new Agent("codex", { sandbox, cwd: "/workspace", approvalMode: "auto" });
 
 ## Sandboxes
 
-Four sandbox providers are supported. Each gives you an isolated environment with the same interface:
+Five sandbox providers are supported. Each gives you an isolated environment with the same interface:
 
-| Provider       | What it is             | Auth                                    |
-| -------------- | ---------------------- | --------------------------------------- |
-| `local-docker` | Local Docker container | Docker daemon                           |
-| `e2b`          | Cloud micro-VM         | `E2B_API_KEY`                           |
-| `modal`        | Cloud container        | `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` |
-| `daytona`      | Cloud dev environment  | `DAYTONA_API_KEY`                       |
+| Provider       | What it is             | Auth                                                    |
+| -------------- | ---------------------- | ------------------------------------------------------- |
+| `local-docker` | Local Docker container | Docker daemon                                           |
+| `e2b`          | Cloud micro-VM         | `E2B_API_KEY`                                           |
+| `modal`        | Cloud container        | `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET`                 |
+| `daytona`      | Cloud dev environment  | `DAYTONA_API_KEY`                                       |
+| `vercel`       | Ephemeral cloud VM     | `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID` |
 
 Every sandbox supports: `run()`, `runAsync()`, `gitClone()`, `openPort()`, `getPreviewLink()`, `snapshot()`, `stop()`, `delete()`.
 
+Vercel sandboxes use runtime snapshots instead of pre-built images — call `sandbox.snapshot()` to capture state and pass the returned id via `provider.snapshotId` on the next run.
+
+Vercel also requires ports to be declared at create time via `provider.ports` — `openPort()` is a no-op at runtime, so any port the agent (or your own code) will listen on must be listed up front:
+
+```ts
+const sandbox = new Sandbox("vercel", {
+  provider: {
+    snapshotId: process.env.VERCEL_SNAPSHOT_ID!,
+    ports: [4096], // e.g. opencode; codex/claude-code use 43180
+  },
+});
+```
+
 ## Skills
 
 Attach GitHub repos as agent skills. They're cloned into the sandbox and surfaced to the agent:
@@ -241,7 +255,7 @@ Pass images and files alongside text:
 import { pathToFileURL } from "node:url";
 
 const result = await agent.run({
-  model: "claude-sonnet-4-6",
+  model: "sonnet",
   input: [
     { type: "text", text: "Describe this mockup and suggest improvements." },
     { type: "image", image: pathToFileURL("/workspace/mockup.png") },
@@ -348,6 +362,7 @@ The [`examples/`](./examples) directory has short, runnable scripts that each de
 | [`multimodal.ts`](./examples/multimodal.ts)                     | Send images to the agent      |
 | [`custom-image.ts`](./examples/custom-image.ts)                 | Build a custom sandbox image  |
 | [`cloud-sandbox.ts`](./examples/cloud-sandbox.ts)               | Use E2B, Modal, or Daytona    |
+| [`basic-vercel.ts`](./examples/basic-vercel.ts)                 | Use a Vercel sandbox          |
 | [`git-clone.ts`](./examples/git-clone.ts)                       | Clone a repo into the sandbox |
 
 All examples import from `"agentbox-sdk"` like a normal dependency. Run them with:

package/dist/{Sandbox-DTprxRZf.d.ts → Sandbox-BQX-sWzs.d.ts}

@@ -1,20 +1,26 @@
 import { Sandbox as Sandbox$1 } from 'e2b';
-import { Daytona, Sandbox as Sandbox$2 } from '@daytonaio/sdk';
-import { ModalClient, Sandbox as Sandbox$3 } from 'modal';
+import { Sandbox as Sandbox$2 } from '@vercel/sandbox';
+import { Daytona, Sandbox as Sandbox$3 } from '@daytonaio/sdk';
+import { ModalClient, Sandbox as Sandbox$4 } from 'modal';
 import Docker from 'dockerode';
+import { SandboxProvider } from './enums.js';
 
 type E2bRaw = {
     sandbox?: Sandbox$1;
 };
 
+type VercelRaw = {
+    sandbox?: Sandbox$2;
+};
+
 type DaytonaRaw = {
     client: Daytona;
-    sandbox?: Sandbox$2;
+    sandbox?: Sandbox$3;
 };
 
 type ModalRaw = {
     client: ModalClient;
-    sandbox?: Sandbox$3;
+    sandbox?: Sandbox$4;
 };
 
 type DockerRaw = {
@@ -22,7 +28,7 @@ type DockerRaw = {
     container?: Docker.Container;
 };
 
-type SandboxProviderName = "local-docker" | "modal" | "daytona" | "e2b";
+type SandboxProviderName = SandboxProvider;
 interface CommandOptions {
     cwd?: string;
     env?: Record<string, string>;
@@ -113,6 +119,35 @@ interface DaytonaProviderOptions {
     user?: string;
     public?: boolean;
 }
+interface VercelGitSource {
+    url: string;
+    depth?: number;
+    revision?: string;
+    username?: string;
+    password?: string;
+}
+interface VercelProviderOptions {
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+    runtime?: string;
+    snapshotId?: string;
+    timeoutMs?: number;
+    gitSource?: VercelGitSource;
+    /**
+     * Ports to declare at sandbox creation time. The Vercel SDK requires ports
+     * to be known upfront; runtime-opened ports are not supported. Max 4.
+     */
+    ports?: number[];
+    /**
+     * Vercel Deployment Protection bypass token. When set, every request the
+     * agent transports send through the sandbox preview URL will include
+     * `x-vercel-protection-bypass: <token>`. Required when the linked Vercel
+     * project has Deployment Protection enabled — without it, POST requests
+     * to sandbox-exposed ports come back 200 + empty body.
+     */
+    protectionBypass?: string;
+}
 interface E2bProviderOptions {
     apiKey?: string;
     accessToken?: string;
@@ -139,6 +174,9 @@ interface ModalSandboxOptions extends SandboxOptionsBase {
 interface DaytonaSandboxOptions extends SandboxOptionsBase {
     provider?: DaytonaProviderOptions;
 }
+interface VercelSandboxOptions extends SandboxOptionsBase {
+    provider?: VercelProviderOptions;
+}
 interface E2bSandboxOptions extends SandboxOptionsBase {
     provider?: E2bProviderOptions;
 }
@@ -146,6 +184,7 @@ type SandboxOptionsMap = {
     "local-docker": LocalDockerSandboxOptions;
     modal: ModalSandboxOptions;
     daytona: DaytonaSandboxOptions;
+    vercel: VercelSandboxOptions;
     e2b: E2bSandboxOptions;
 };
 type SandboxOptions<P extends SandboxProviderName = SandboxProviderName> = SandboxOptionsMap[P];
@@ -153,6 +192,7 @@ type SandboxRawMap = {
     "local-docker": DockerRaw;
     modal: ModalRaw;
     daytona: DaytonaRaw;
+    vercel: VercelRaw;
     e2b: E2bRaw;
 };
 type SandboxRaw<P extends SandboxProviderName = SandboxProviderName> = SandboxRawMap[P];
@@ -177,6 +217,9 @@ declare class Sandbox<P extends SandboxProviderName = SandboxProviderName> {
     stop(): Promise<void>;
     delete(): Promise<void>;
     getPreviewLink(port: number): Promise<string>;
+    get previewHeaders(): Record<string, string>;
+    uploadFile(content: Buffer | string, targetPath: string): Promise<void>;
+    downloadFile(sourcePath: string): Promise<Buffer>;
 }
 
-export { type AsyncCommandHandle as A, type CommandEvent as C, type DaytonaProviderOptions as D, type E2bProviderOptions as E, type GitCloneOptions as G, type LocalDockerProviderOptions as L, type ModalProviderOptions as M, Sandbox as S, type CommandOptions as a, type CommandResult as b, type DaytonaSandboxOptions as c, type E2bSandboxOptions as d, type LocalDockerSandboxOptions as e, type ModalSandboxOptions as f, type SandboxDescriptor as g, type SandboxListOptions as h, type SandboxOptions as i, type SandboxOptionsBase as j, type SandboxOptionsMap as k, type SandboxProviderName as l, type SandboxRaw as m, type SandboxRawMap as n, type SandboxResourceSpec as o };
+export { type AsyncCommandHandle as A, type CommandEvent as C, type DaytonaProviderOptions as D, type E2bProviderOptions as E, type GitCloneOptions as G, type LocalDockerProviderOptions as L, type ModalProviderOptions as M, Sandbox as S, type VercelGitSource as V, type CommandOptions as a, type CommandResult as b, type DaytonaSandboxOptions as c, type E2bSandboxOptions as d, type LocalDockerSandboxOptions as e, type ModalSandboxOptions as f, type SandboxDescriptor as g, type SandboxListOptions as h, type SandboxOptions as i, type SandboxOptionsBase as j, type SandboxOptionsMap as k, type SandboxProviderName as l, type SandboxRaw as m, type SandboxRawMap as n, type SandboxResourceSpec as o, type VercelProviderOptions as p, type VercelSandboxOptions as q };

package/dist/agents/index.d.ts

@@ -1,7 +1,9 @@
-import { m as AgentProviderName, f as AgentOptions, q as AgentRunConfig, p as AgentRun, o as AgentResult, Z as RawAgentEvent } from '../types-BwcoN0n-.js';
-export { a as AgentApprovalMode, b as AgentCommandConfig, c as AgentExecutionRequest, d as AgentLocalMcpConfig, e as AgentMcpConfig, g as AgentOptionsBase, h as AgentOptionsMap, i as AgentPermissionDecision, j as AgentPermissionKind, k as AgentPermissionResponse, l as AgentProviderAdapter, n as AgentRemoteMcpConfig, r as AgentRunSink, s as AgentSkillConfig, t as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, u as ClaudeCodeHookConfig, v as ClaudeCodeHookEvent, w as ClaudeCodeHookHandler, x as ClaudeCodeHookMatcherGroup, y as ClaudeCodeHooksConfig, z as ClaudeCodeProviderOptions, B as CodexAgentOptions, D as CodexCommandHook, E as CodexHookEvent, F as CodexHookMatcherGroup, G as CodexHooksConfig, H as CodexProviderOptions, I as DataContent, J as EmbeddedSkillConfig, K as FilePart, L as ImagePart, S as OpenCodeAgentOptions, T as OpenCodePluginConfig, U as OpenCodePluginEvent, V as OpenCodePluginHookConfig, W as OpenCodeProviderOptions, $ as RepoSkillConfig, a4 as TextPart, a8 as UserContent, a9 as UserContentPart } from '../types-BwcoN0n-.js';
-import '../Sandbox-DTprxRZf.js';
+import { m as AgentProviderName, f as AgentOptions, q as AgentRunConfig, p as AgentRun, o as AgentResult, Z as RawAgentEvent } from '../types-Et22oPap.js';
+export { a as AgentApprovalMode, b as AgentCommandConfig, c as AgentExecutionRequest, d as AgentLocalMcpConfig, e as AgentMcpConfig, g as AgentOptionsBase, h as AgentOptionsMap, i as AgentPermissionDecision, j as AgentPermissionKind, k as AgentPermissionResponse, l as AgentProviderAdapter, n as AgentRemoteMcpConfig, r as AgentRunSink, s as AgentSkillConfig, t as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, u as ClaudeCodeHookConfig, v as ClaudeCodeHookEvent, w as ClaudeCodeHookHandler, x as ClaudeCodeHookMatcherGroup, y as ClaudeCodeHooksConfig, z as ClaudeCodeProviderOptions, B as CodexAgentOptions, D as CodexCommandHook, E as CodexHookEvent, F as CodexHookMatcherGroup, G as CodexHooksConfig, H as CodexProviderOptions, I as DataContent, J as EmbeddedSkillConfig, K as FilePart, L as ImagePart, S as OpenCodeAgentOptions, T as OpenCodePluginConfig, U as OpenCodePluginEvent, V as OpenCodePluginHookConfig, W as OpenCodeProviderOptions, $ as RepoSkillConfig, a4 as TextPart, a8 as UserContent, a9 as UserContentPart } from '../types-Et22oPap.js';
+export { AgentProvider } from '../enums.js';
+import '../Sandbox-BQX-sWzs.js';
 import 'e2b';
+import '@vercel/sandbox';
 import '@daytonaio/sdk';
 import 'modal';
 import 'dockerode';
@@ -16,4 +18,22 @@ declare class Agent<P extends AgentProviderName = AgentProviderName> {
     rawEvents(runConfig: AgentRunConfig): AsyncIterable<RawAgentEvent>;
 }
 
-export { Agent, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig };
+/**
+ * Ports each agent harness needs exposed on its sandbox in order to reach
+ * its app-server (or equivalent local server). These are used to:
+ *
+ *   1. Drive `sandbox.openPort(...)` at `Agent` construction time so providers
+ *      whose `openPort` only mutates options before provisioning (Modal) still
+ *      include the port.
+ *   2. Pre-declare the ports on Modal sandboxes by default so that a Modal
+ *      sandbox created without explicit `unencryptedPorts` still works when
+ *      the caller later points an `Agent` at it.
+ *
+ * Exported so callers can forward the ports to sandbox creation options when
+ * they know in advance which harness will be used (e.g.
+ * `provider.unencryptedPorts: AGENT_RESERVED_PORTS.codex`).
+ */
+declare const AGENT_RESERVED_PORTS: Record<AgentProviderName, readonly number[]>;
+declare function collectAllAgentReservedPorts(): number[];
+
+export { AGENT_RESERVED_PORTS, Agent, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig, collectAllAgentReservedPorts };

package/dist/agents/index.js

@@ -1,9 +1,18 @@
 import {
   Agent
-} from "../chunk-BW43ESRM.js";
+} from "../chunk-G27423WX.js";
 import "../chunk-7FLLQJ6J.js";
-import "../chunk-HMBWQSVN.js";
-import "../chunk-JFDP556Q.js";
+import {
+  AGENT_RESERVED_PORTS,
+  collectAllAgentReservedPorts
+} from "../chunk-O7HCJXKW.js";
+import "../chunk-NSJM57Z4.js";
+import {
+  AgentProvider
+} from "../chunk-2NKMDGYH.js";
 export {
-  Agent
+  AGENT_RESERVED_PORTS,
+  Agent,
+  AgentProvider,
+  collectAllAgentReservedPorts
 };

package/dist/chunk-2NKMDGYH.js

@@ -0,0 +1,18 @@
+// src/enums.ts
+var AgentProvider = {
+  ClaudeCode: "claude-code",
+  OpenCode: "opencode",
+  Codex: "codex"
+};
+var SandboxProvider = {
+  LocalDocker: "local-docker",
+  Modal: "modal",
+  Daytona: "daytona",
+  Vercel: "vercel",
+  E2B: "e2b"
+};
+
+export {
+  AgentProvider,
+  SandboxProvider
+};