agentbox-sdk 0.1.0 → 0.1.3

package/README.md

@@ -1,5 +1,7 @@
 # AgentBox
 
+[Live demo](https://agentbox-demo-175164121374.us-west1.run.app/)
+
 Run coding agents inside sandboxes. One API, any provider.
 
 Unlike wrappers that shell out to CLIs in non-interactive mode (e.g. `claude --print`), AgentBox launches each agent as a **server process** inside the sandbox and communicates over WebSocket or HTTP. This preserves the full interactive capabilities of each agent — approval flows, tool-use control, streaming events.
@@ -13,12 +15,14 @@ const sandbox = new Sandbox("local-docker", {
   env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
 });
 
+await sandbox.findOrProvision();
+
 const run = new Agent("claude-code", {
   sandbox,
   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 +36,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.
 
@@ -71,6 +75,11 @@ const sandbox = new Sandbox("local-docker", {
   env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
 });
 
+// Explicitly attach to / create the sandbox before running anything.
+// Subsequent `sandbox.run`, `sandbox.gitClone`, agent runs, etc. all
+// require this to have happened first.
+await sandbox.findOrProvision();
+
 const agent = new Agent("claude-code", {
   sandbox,
   cwd: "/workspace",
@@ -78,7 +87,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 +102,7 @@ await sandbox.delete();
 
 ```ts
 const run = agent.stream({
-  model: "claude-sonnet-4-6",
+  model: "sonnet",
   input: "Write a fizzbuzz in Python",
 });
 
@@ -112,28 +121,72 @@ 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" });
-new Agent("opencode", { sandbox, cwd: "/workspace", approvalMode: "auto" });
+new Agent("open-code", { sandbox, cwd: "/workspace", approvalMode: "auto" });
 new Agent("codex", { sandbox, cwd: "/workspace", approvalMode: "auto" });
 ```
 
+### Reasoning effort
+
+Pass an optional `reasoning` level alongside `model` on any run. It maps to each provider's native reasoning control: Codex's `effort` on `turn/start`, Claude Code's `--effort` flag, and OpenCode's `reasoningEffort` agent variant.
+
+```ts
+await agent.run({
+  model: "sonnet",
+  reasoning: "high", // "low" | "medium" | "high" | "xhigh"
+  input: "Refactor this module and explain your reasoning.",
+});
+```
+
+`xhigh` requires a model that supports it (e.g. Claude Opus 4.7+, Codex `gpt-5.4`).
+
 ## 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`                                       |
+| `vercel`       | Ephemeral cloud VM     | `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID` |
+
+Every sandbox supports: `findOrProvision()`, `run()`, `runAsync()`, `gitClone()`, `uploadAndRun()`, `openPort()`, `getPreviewLink()`, `snapshot()`, `stop()`, `delete()`.
+
+### Provisioning lifecycle
 
-| 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`                       |
+`new Sandbox(...)` only stores configuration — it does **not** create or attach to a real sandbox. Call `findOrProvision()` once when you're ready to start using it, and every subsequent operation (`run`, `gitClone`, `uploadAndRun`, agent runs, …) reuses that sandbox:
 
-Every sandbox supports: `run()`, `runAsync()`, `gitClone()`, `openPort()`, `getPreviewLink()`, `snapshot()`, `stop()`, `delete()`.
+```ts
+const sandbox = new Sandbox("modal", {
+  /* … */
+});
+
+await sandbox.findOrProvision(); // attach to existing tagged sandbox or create a fresh one
+await sandbox.gitClone({ repoUrl: "…" });
+const result = await sandbox.run("pnpm install");
+```
+
+Calling a method that needs a live sandbox before `findOrProvision()` throws a clear error. This makes the (potentially slow) attach / create step explicit and lets you control exactly when it happens.
+
+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
 
@@ -218,7 +271,7 @@ const agent = new Agent("claude-code", {
 Register slash commands the agent can use:
 
 ```ts
-const agent = new Agent("opencode", {
+const agent = new Agent("open-code", {
   sandbox,
   cwd: "/workspace",
   approvalMode: "auto",
@@ -241,7 +294,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") },
@@ -319,7 +372,7 @@ new Agent("codex", {
 **OpenCode** — plugin-based hooks:
 
 ```ts
-new Agent("opencode", {
+new Agent("open-code", {
   sandbox,
   cwd: "/workspace",
   provider: {
@@ -348,6 +401,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-CByFJI8X.d.ts}

@@ -1,20 +1,44 @@
 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, CreateSandboxFromSnapshotParams, CreateSandboxFromImageParams } from '@daytonaio/sdk';
+import { ModalClient, Sandbox as Sandbox$4, SandboxCreateParams } from 'modal';
 import Docker from 'dockerode';
+import { SandboxProvider } from './enums.js';
+
+/**
+ * Tiny in-memory tarball builder used by `Sandbox.uploadAndRun`.
+ *
+ * Builds an uncompressed POSIX USTAR archive entirely in-memory, suitable
+ * for piping through a sandbox's stdin to be extracted by `tar -x`. We
+ * deliberately don't gzip on the host: setup tarballs are small (a few
+ * KB) and the sandbox's `tar` may not always have gzip when the image is
+ * stripped down, so plain tar keeps the contract simple.
+ */
+interface TarballEntry {
+    /** Absolute or relative path the file should be written to in the sandbox. */
+    path: string;
+    /** File contents. Strings are encoded as UTF-8. */
+    content: string | Buffer;
+    /** Optional file mode (default `0o644`). Pass `0o755` for executables. */
+    mode?: number;
+}
 
 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 +46,7 @@ type DockerRaw = {
     container?: Docker.Container;
 };
 
-type SandboxProviderName = "local-docker" | "modal" | "daytona" | "e2b";
+type SandboxProviderName = SandboxProvider;
 interface CommandOptions {
     cwd?: string;
     env?: Record<string, string>;
@@ -101,6 +125,16 @@ interface ModalProviderOptions {
     unencryptedPorts?: number[];
     command?: string[];
     verbose?: boolean;
+    /**
+     * Escape hatch: extra parameters spread into Modal's
+     * `client.sandboxes.create()` call. Lets callers use Modal-specific
+     * features that are not surfaced as typed fields here (e.g.
+     * `experimentalOptions`, `gpu`, `cloudBucketMounts`, `regions`).
+     *
+     * Typed fields on `ModalProviderOptions` and `SandboxOptionsBase` take
+     * precedence over keys provided via `createParams`.
+     */
+    createParams?: Partial<SandboxCreateParams>;
 }
 interface DaytonaProviderOptions {
     apiKey?: string;
@@ -112,6 +146,45 @@ interface DaytonaProviderOptions {
     language?: string;
     user?: string;
     public?: boolean;
+    /**
+     * Escape hatch: extra parameters spread into Daytona's `client.create()`
+     * call. Lets callers use Daytona-specific features that are not surfaced
+     * as typed fields here (e.g. `volumes`, `networkBlockAll`,
+     * `networkAllowList`, `ephemeral`, `autoArchiveInterval`).
+     *
+     * Typed fields on `DaytonaProviderOptions` and `SandboxOptionsBase` take
+     * precedence over keys provided via `createParams`.
+     */
+    createParams?: Partial<CreateSandboxFromSnapshotParams & CreateSandboxFromImageParams>;
+}
+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;
@@ -139,6 +212,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 +222,7 @@ type SandboxOptionsMap = {
     "local-docker": LocalDockerSandboxOptions;
     modal: ModalSandboxOptions;
     daytona: DaytonaSandboxOptions;
+    vercel: VercelSandboxOptions;
     e2b: E2bSandboxOptions;
 };
 type SandboxOptions<P extends SandboxProviderName = SandboxProviderName> = SandboxOptionsMap[P];
@@ -153,6 +230,7 @@ type SandboxRawMap = {
     "local-docker": DockerRaw;
     modal: ModalRaw;
     daytona: DaytonaRaw;
+    vercel: VercelRaw;
     e2b: E2bRaw;
 };
 type SandboxRaw<P extends SandboxProviderName = SandboxProviderName> = SandboxRawMap[P];
@@ -166,6 +244,20 @@ declare class Sandbox<P extends SandboxProviderName = SandboxProviderName> {
     get optionsSnapshot(): SandboxOptions<P>;
     get id(): string | undefined;
     get raw(): SandboxRaw<P> | undefined;
+    /**
+     * Whether `findOrProvision()` warm-attached to a pre-existing tagged
+     * sandbox (`true`) or created a fresh one (`false`). Useful to skip
+     * idempotent setup that the previous run already performed (e.g.
+     * `agent.setup()`). Always `false` before `findOrProvision()` resolves.
+     */
+    get wasFound(): boolean;
+    /**
+     * Attach to an existing tagged sandbox or create a new one. Must be
+     * called before `run`, `runAsync`, `gitClone`, `uploadAndRun`,
+     * `getPreviewLink`, etc. Repeated calls are cheap (the result is
+     * cached internally).
+     */
+    findOrProvision(): Promise<this>;
     openPort(port: number): Promise<this>;
     setSecret(name: string, value: string): this;
     setSecrets(values: Record<string, string>): this;
@@ -177,6 +269,10 @@ 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>;
+    uploadAndRun(files: TarballEntry[], command: string, options?: CommandOptions): Promise<CommandResult>;
 }
 
-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 TarballEntry as T, 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,19 +1,88 @@
-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 { o as AgentProviderName, h as AgentOptions, v as AgentSetupConfig, t as AgentRunConfig, s as AgentRun, r as AgentResult, a3 as RawAgentEvent, b as AgentAttachRequest, z as AttachedRun } from '../types-B3N-Qo2q.js';
+export { a as AgentApprovalMode, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, u as AgentRunSink, w as AgentSetupRequest, x as AgentSkillConfig, y as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, B as ClaudeCodeHookConfig, D as ClaudeCodeHookEvent, E as ClaudeCodeHookHandler, F as ClaudeCodeHookMatcherGroup, G as ClaudeCodeHooksConfig, H as ClaudeCodeProviderOptions, I as CodexAgentOptions, J as CodexCommandHook, K as CodexHookEvent, L as CodexHookMatcherGroup, M as CodexHooksConfig, N as CodexProviderOptions, O as DataContent, P as EmbeddedSkillConfig, Q as FilePart, R as ImagePart, Y as OpenCodeAgentOptions, Z as OpenCodePluginConfig, _ as OpenCodePluginEvent, $ as OpenCodePluginHookConfig, a0 as OpenCodeProviderOptions, a5 as RepoSkillConfig, aa as TextPart, ae as UserContent, af as UserContentPart } from '../types-B3N-Qo2q.js';
+import { S as Sandbox } from '../Sandbox-CByFJI8X.js';
+export { AgentProvider } from '../enums.js';
 import 'e2b';
+import '@vercel/sandbox';
 import '@daytonaio/sdk';
 import 'modal';
 import 'dockerode';
 
 declare class Agent<P extends AgentProviderName = AgentProviderName> {
     private readonly adapter;
-    private readonly provider;
+    readonly provider: P;
     private readonly options;
+    private setupPromise?;
     constructor(provider: P, options: AgentOptions<P>);
+    /**
+     * The sandbox the agent will run inside, if any was passed via
+     * `options.sandbox`. Returns `undefined` for host-mode runs (no sandbox).
+     */
+    get sandbox(): Sandbox | undefined;
+    /**
+     * Prepare provider-specific runtime state on the configured sandbox
+     * (skill artifacts, MCP/hook/sub-agent config, app-server / relay boot, …).
+     *
+     * `setup()` is REQUIRED before {@link Agent.stream} or {@link Agent.run}
+     * for any sandbox-backed run. `stream` and the underlying
+     * `adapter.execute` deliberately do not trigger setup themselves so
+     * callers can run sandbox-side preparation in parallel with other
+     * long-running work (e.g. `git clone`).
+     *
+     * `execute` does not consume any setup output and does not re-do
+     * setup work. It assumes the relay/server boot performed here is
+     * already up. Skipping `setup()` against a remote sandbox is a
+     * programmer error and surfaces as a connect-retry timeout inside
+     * `execute`, not a silent fallback.
+     *
+     * Idempotent across repeated invocations: subsequent calls return the
+     * promise from the first call. The differential setup cache and the
+     * relay/server probes also make this cheap on warm sandboxes — the
+     * second `setup()` against the same sandbox does ~one round-trip of
+     * work.
+     */
+    setup(config?: AgentSetupConfig): Promise<void>;
     stream(runConfig: AgentRunConfig): AgentRun;
     run(runConfig: AgentRunConfig): Promise<AgentResult>;
     rawEvents(runConfig: AgentRunConfig): AsyncIterable<RawAgentEvent>;
+    /**
+     * Stateless control plane for an in-flight run.
+     *
+     * Returns an {@link AttachedRun} whose `abort()` / `sendMessage()` methods
+     * dial the in-sandbox provider server directly (codex app-server, opencode
+     * HTTP server, claude-code relay control endpoint) — there is no shared
+     * in-memory registry or Redis broker. Any process with the right `sandbox`
+     * + `runId` (+ optional provider-native `sessionId`) can issue commands
+     * against a run started on a different process.
+     *
+     * The originating process keeps owning the event stream that
+     * `agent.stream()` returned; commands attached here cause the in-sandbox
+     * server to emit the natural follow-up events (`turn/aborted`, message
+     * events, etc.), which the originating process ingests through its
+     * existing transport.
+     *
+     * The handle is short-lived: each method call opens a fresh connection,
+     * performs the operation with a timeout, and tears the connection down.
+     */
+    static attach<P extends AgentProviderName>(request: AgentAttachRequest<P>): Promise<AttachedRun>;
 }
 
-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, AgentAttachRequest, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig, AgentSetupConfig, AttachedRun, collectAllAgentReservedPorts };

package/dist/agents/index.js

@@ -1,9 +1,18 @@
 import {
   Agent
-} from "../chunk-BW43ESRM.js";
-import "../chunk-7FLLQJ6J.js";
-import "../chunk-HMBWQSVN.js";
-import "../chunk-JFDP556Q.js";
+} from "../chunk-4MBB6QHD.js";
+import "../chunk-ZOWBRUQR.js";
+import {
+  AGENT_RESERVED_PORTS,
+  collectAllAgentReservedPorts
+} from "../chunk-INMA52FV.js";
+import "../chunk-NSJM57Z4.js";
+import {
+  AgentProvider
+} from "../chunk-GOFJNFAD.js";
 export {
-  Agent
+  AGENT_RESERVED_PORTS,
+  Agent,
+  AgentProvider,
+  collectAllAgentReservedPorts
 };