agentbox-sdk 0.1.0 → 0.1.3

package/dist/{chunk-QRQFQTGH.js → chunk-LPKKT6YT.js}

@@ -1,15 +1,22 @@
 import {
   AsyncQueue,
   UnsupportedProviderError,
+  collectAllAgentReservedPorts,
+  debugSandbox,
   pipeReadableStream,
   readNodeStream,
   readStreamAsText,
-  sleep
-} from "./chunk-HMBWQSVN.js";
+  sleep,
+  suppressUnhandledRejection,
+  time
+} from "./chunk-INMA52FV.js";
 import {
   shellQuote,
   toShellCommand
-} from "./chunk-JFDP556Q.js";
+} from "./chunk-NSJM57Z4.js";
+import {
+  SandboxProvider
+} from "./chunk-GOFJNFAD.js";
 
 // src/sandboxes/git.ts
 function encodeExtraHeader(name, value) {
@@ -55,30 +62,122 @@ var SandboxAdapter = class {
   baseEnv;
   provisioned = false;
   provisioning;
+  /**
+   * Whether `provision()` warm-attached to a pre-existing tagged sandbox
+   * (true) or had to create a fresh one (false). Set by adapter
+   * `provision()` implementations. Stays `false` until `findOrProvision()`
+   * has resolved.
+   */
+  wasFoundFlag = false;
   constructor(options) {
     this.options = options;
     this.baseEnv = { ...options.env ?? {} };
   }
-  async ensureProvisioned() {
+  async uploadFile(_content, _targetPath) {
+    void _content;
+    void _targetPath;
+    throw new Error(
+      `uploadFile is not supported by the ${this.provider} provider.`
+    );
+  }
+  async downloadFile(_sourcePath) {
+    void _sourcePath;
+    throw new Error(
+      `downloadFile is not supported by the ${this.provider} provider.`
+    );
+  }
+  /**
+   * Upload a tarball of files into the sandbox and execute a command in
+   * the same round-trip. Used by setup paths that would otherwise need one
+   * sandbox RPC per file plus another to run the install script — Modal-
+   * style providers pay ~700ms per RPC, so collapsing N+1 calls into one
+   * is the single biggest win on cold setup.
+   *
+   * Default implementation falls back to `uploadFile` per entry + a final
+   * `run`. Providers that support stdin streaming (Modal) override this to
+   * do the upload + extract + exec in a single sandbox `exec` call.
+   */
+  async uploadAndRun(files, command, options) {
+    this.requireProvisioned();
+    for (const entry of files) {
+      const content = typeof entry.content === "string" ? Buffer.from(entry.content, "utf8") : entry.content;
+      await this.uploadFile(content, entry.path);
+    }
+    if (files.length > 0) {
+      const chmodCmd = files.filter((entry) => entry.mode && (entry.mode & 73) !== 0).map(
+        (entry) => `chmod ${entry.mode.toString(8)} ${shellQuote(entry.path)}`
+      );
+      if (chmodCmd.length > 0) {
+        await this.run(chmodCmd.join(" && "), options);
+      }
+    }
+    return this.run(command, options);
+  }
+  /**
+   * Public hook that callers must invoke before they touch the sandbox
+   * (running commands, cloning repos, uploading files, opening preview
+   * links, …). It either attaches to an existing tagged sandbox or creates
+   * a new one. The result is cached so repeated calls are cheap.
+   *
+   * Provisioning is no longer triggered implicitly by `run`, `runAsync`,
+   * `gitClone`, `uploadAndRun`, etc. Those methods now throw a clear error
+   * when the adapter has not been provisioned yet, which makes the
+   * lifecycle explicit and gives callers control over when the
+   * (potentially slow) sandbox attach / create happens.
+   */
+  async findOrProvision() {
     if (this.provisioned) {
       return;
     }
     if (!this.provisioning) {
-      this.provisioning = (async () => {
-        await this.provision();
-        this.provisioned = true;
-      })().finally(() => {
+      this.provisioning = time(
+        debugSandbox,
+        `provision [${this.provider}] (find-or-create)`,
+        async () => {
+          await this.provision();
+          this.provisioned = true;
+        }
+      ).finally(() => {
         this.provisioning = void 0;
       });
     }
     await this.provisioning;
   }
+  /**
+   * Throw a consistent error when a method that needs a provisioned
+   * sandbox is called before `findOrProvision()`. Provider adapters call
+   * this at the top of `run`, `runAsync`, `uploadFile`, etc.
+   */
+  requireProvisioned() {
+    if (!this.provisioned) {
+      throw new Error(
+        `Sandbox (${this.provider}) is not provisioned. Call \`sandbox.findOrProvision()\` once before running commands, cloning repos, or uploading files.`
+      );
+    }
+  }
   get tags() {
     return { ...this.options.tags ?? {} };
   }
   get workingDir() {
     return this.options.workingDir ?? "/workspace";
   }
+  /**
+   * 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() {
+    return this.wasFoundFlag;
+  }
+  /**
+   * Headers that callers should attach to HTTP / WebSocket requests they make
+   * against this sandbox's preview URL. Default is empty; providers like
+   * Vercel override this to inject Deployment Protection bypass tokens.
+   */
+  get previewHeaders() {
+    return {};
+  }
   getMergedEnv(extra) {
     return {
       ...this.baseEnv,
@@ -93,7 +192,7 @@ var SandboxAdapter = class {
     Object.assign(this.secrets, values);
   }
   async gitClone(options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     return this.run(buildGitCloneCommand(options), {
       cwd: this.workingDir,
       env: this.getMergedEnv()
@@ -127,7 +226,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     });
   }
   get provider() {
-    return "daytona";
+    return SandboxProvider.Daytona;
   }
   get raw() {
     return {
@@ -143,6 +242,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     if (existing) {
       this.sandbox = existing;
       await existing.start();
+      this.wasFoundFlag = true;
       return;
     }
     const labels = this.getLabels();
@@ -171,6 +271,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
       autoDeleteInterval
     };
     const sandbox = await this.client.create({
+      ...this.options.provider?.createParams,
       ...createBase,
       snapshot: image
     });
@@ -178,7 +279,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     this.sandbox = sandbox;
   }
   async run(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const result = await sandbox.process.executeCommand(
       toShellCommand(command),
@@ -196,7 +297,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     };
   }
   async runAsync(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const sessionId = `agentbox-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     await sandbox.process.createSession(sessionId);
@@ -288,9 +389,17 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: commandId,
       raw: { sessionId, commandId },
+      write: async (input) => {
+        await sandbox.process.sendSessionCommandInput(
+          sessionId,
+          commandId,
+          input
+        );
+      },
       wait: () => completion,
       kill: async () => {
         killed = true;
@@ -331,15 +440,26 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     this.sandbox = void 0;
   }
   async openPort(port) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     await this.requireSandbox().getPreviewLink(port);
   }
   async getPreviewLink(port) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const preview = await sandbox.getPreviewLink(port);
     return preview.url;
   }
+  async uploadFile(content, targetPath) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+    await sandbox.fs.uploadFile(buffer, targetPath);
+  }
+  async downloadFile(sourcePath) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    return sandbox.fs.downloadFile(sourcePath);
+  }
   getLabels() {
     return {
       "agentbox.provider": this.provider,
@@ -382,7 +502,7 @@ async function loadE2bModule() {
 var E2bSandboxAdapter = class extends SandboxAdapter {
   sandbox;
   get provider() {
-    return "e2b";
+    return SandboxProvider.E2B;
   }
   get raw() {
     return {
@@ -397,6 +517,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
     const existing = await this.findMatchingSandbox();
     if (existing) {
       this.sandbox = existing;
+      this.wasFoundFlag = true;
       return;
     }
     const template = resolveSandboxImage(this.options.image);
@@ -422,7 +543,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
     });
   }
   async run(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const { CommandExitError } = await loadE2bModule();
     if (options?.pty) {
@@ -450,7 +571,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
     }
   }
   async runAsync(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const { CommandExitError } = await loadE2bModule();
     const queue = new AsyncQueue();
@@ -520,6 +641,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: String(handle.pid),
       raw: handle,
@@ -585,6 +707,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: String(handle.pid),
       raw: handle,
@@ -624,7 +747,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
     return sandboxes;
   }
   async snapshot() {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const snapshot = await sandbox.createSnapshot();
     return snapshot.snapshotId;
@@ -644,11 +767,27 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
     void _port;
   }
   async getPreviewLink(port) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const host = sandbox.getHost(port);
     return host.startsWith("localhost:") ? `http://${host}` : `https://${host}`;
   }
+  async uploadFile(content, targetPath) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    if (typeof content === "string") {
+      await sandbox.files.write(targetPath, content);
+      return;
+    }
+    const exactBytes = Uint8Array.from(content);
+    await sandbox.files.write(targetPath, new Blob([exactBytes]));
+  }
+  async downloadFile(sourcePath) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const bytes = await sandbox.files.read(sourcePath, { format: "bytes" });
+    return Buffer.from(bytes);
+  }
   async findMatchingSandbox() {
     const { Sandbox: E2bSandbox } = await loadE2bModule();
     const matches = await this.list();
@@ -684,7 +823,14 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
     return {
       cwd: options?.cwd ?? this.workingDir,
       envs: this.getMergedEnv(options?.env),
-      timeoutMs: options?.timeoutMs
+      // E2B is the only provider whose underlying SDK applies its own
+      // per-command timeout (60_000 ms) when nothing is specified.
+      // local-docker / modal / daytona pass through `undefined` and
+      // let the caller decide, so we do the same here by disabling
+      // E2B's default with `0`. Callers that want a wall-clock cap
+      // pass `timeoutMs` explicitly; everyone else relies on the
+      // sandbox lifecycle / their own AbortController.
+      timeoutMs: options?.timeoutMs ?? 0
     };
   }
   resolveTimeoutConfig() {
@@ -762,7 +908,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
   client = new Docker();
   container;
   get provider() {
-    return "local-docker";
+    return SandboxProvider.LocalDocker;
   }
   get raw() {
     return {
@@ -789,11 +935,11 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
     const env = Object.entries(this.getMergedEnv()).map(
       ([key, value]) => `${key}=${value}`
     );
-    const publishedPorts = this.options.provider?.publishedPorts ?? [];
+    const publishedPorts = this.resolveDefaultPublishedPorts();
     const portBindings = publishedPorts.length > 0 ? Object.fromEntries(
       publishedPorts.map((port) => [
         `${port}/tcp`,
-        [{ HostIp: "127.0.0.1", HostPort: String(port) }]
+        [{ HostIp: "127.0.0.1", HostPort: "" }]
       ])
     ) : void 0;
     const exposedPorts = publishedPorts.length > 0 ? Object.fromEntries(publishedPorts.map((port) => [`${port}/tcp`, {}])) : void 0;
@@ -821,7 +967,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
     await container.start();
   }
   async run(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const container = this.requireContainer();
     const exec = await container.exec({
       AttachStdout: true,
@@ -864,7 +1010,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
     };
   }
   async runAsync(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const container = this.requireContainer();
     const exec = await container.exec({
       AttachStdin: true,
@@ -921,6 +1067,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: exec.id,
       raw: { exec, stream },
@@ -1017,15 +1164,26 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
     if (networkMode === "host") {
       return `http://127.0.0.1:${port}`;
     }
-    if (this.options.provider?.publishedPorts?.includes(port)) {
-      return `http://127.0.0.1:${port}`;
+    const declared = this.resolveDefaultPublishedPorts();
+    if (!declared.includes(port)) {
+      throw new Error(
+        `Port ${port} is not reachable from the host. Use local-docker provider.networkMode="host" or provider.publishedPorts to expose it.`
+      );
     }
-    throw new Error(
-      `Port ${port} is not reachable from the host. Use local-docker provider.networkMode="host" or provider.publishedPorts to expose it.`
-    );
+    const container = this.requireContainer();
+    const inspect = await container.inspect();
+    const portsMap = inspect.NetworkSettings?.Ports ?? {};
+    const bindings = portsMap[`${port}/tcp`];
+    const hostPort = Array.isArray(bindings) ? bindings.find((binding) => binding?.HostPort)?.HostPort : void 0;
+    if (!hostPort) {
+      throw new Error(
+        `Port ${port} is not bound on the local-docker container. Make sure it is listed in provider.publishedPorts (or covered by AGENT_RESERVED_PORTS) before findOrProvision().`
+      );
+    }
+    return `http://127.0.0.1:${hostPort}`;
   }
   async uploadFile(content, targetPath) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const container = this.requireContainer();
     const pack = tar.pack();
     const body = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
@@ -1034,7 +1192,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
     await container.putArchive(pack, { path: "/" });
   }
   async downloadFile(sourcePath) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const container = this.requireContainer();
     const archive = await container.getArchive({ path: sourcePath });
     const chunks = [];
@@ -1049,6 +1207,32 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
     }
     return this.container;
   }
+  /**
+   * Local-docker requires ports to be declared at container creation
+   * time (the `PortBindings` host config can't be amended on a running
+   * container). To make `openPort` work predictably across providers,
+   * we pre-publish all well-known agent-harness ports on every
+   * local-docker sandbox we create — mirroring the Modal adapter's
+   * `resolveDefaultUnencryptedPorts` behavior. Any explicit
+   * `provider.publishedPorts` is honored AND merged with the reserved
+   * set, so callers don't have to remember to list the agent's
+   * default port for things like the claude-code SDK relay.
+   *
+   * Network-mode "host" containers don't use port bindings at all, so
+   * we skip the merge in that case.
+   */
+  resolveDefaultPublishedPorts() {
+    if (this.options.provider?.networkMode === "host") {
+      return [];
+    }
+    const declared = this.options.provider?.publishedPorts;
+    const reserved = collectAllAgentReservedPorts();
+    const merged = new Set(declared ?? []);
+    for (const port of reserved) {
+      merged.add(port);
+    }
+    return Array.from(merged);
+  }
   getLabels() {
     return {
       "agentbox.provider": this.provider,
@@ -1101,10 +1285,46 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
 
 // src/sandboxes/providers/modal.ts
 import { ModalClient } from "modal";
+
+// src/sandboxes/tarball.ts
+import tar2 from "tar-stream";
+async function buildTarball(entries) {
+  const pack = tar2.pack();
+  const chunks = [];
+  pack.on("data", (chunk) => {
+    chunks.push(chunk);
+  });
+  const finished2 = new Promise((resolve, reject) => {
+    pack.on("end", () => resolve());
+    pack.on("error", (error) => reject(error));
+  });
+  for (const entry of entries) {
+    const content = typeof entry.content === "string" ? Buffer.from(entry.content, "utf8") : entry.content;
+    pack.entry(
+      {
+        name: entry.path.replace(/^\/+/, ""),
+        mode: entry.mode ?? 420,
+        size: content.length,
+        mtime: /* @__PURE__ */ new Date(0),
+        type: "file"
+      },
+      content
+    );
+  }
+  pack.finalize();
+  await finished2;
+  return Buffer.concat(chunks);
+}
+
+// src/sandboxes/providers/modal.ts
 var ModalSandboxAdapter = class extends SandboxAdapter {
   client;
   sandbox;
   clientClosed = false;
+  // Cached tunnel map. Populated on the first `getPreviewLink` call after
+  // provision; reused on every subsequent call so the agent runtime path
+  // doesn't re-issue the Modal RPC for each per-run tunnel lookup.
+  tunnelsPromise;
   constructor(options) {
     super(options);
     this.client = new ModalClient({
@@ -1115,7 +1335,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     });
   }
   get provider() {
-    return "modal";
+    return SandboxProvider.Modal;
   }
   get raw() {
     return {
@@ -1130,6 +1350,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     const existing = await this.findMatchingSandbox();
     if (existing) {
       this.sandbox = existing;
+      this.wasFoundFlag = true;
       return;
     }
     const appName = this.options.provider?.appName ?? "agentbox";
@@ -1139,7 +1360,9 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     });
     const image = await this.resolveModalImage();
     const resources = resolveSandboxResources(this.options.resources);
+    const unencryptedPorts = this.resolveDefaultUnencryptedPorts();
     const sandbox = await this.client.sandboxes.create(app, image, {
+      ...this.options.provider?.createParams,
       cpu: resources?.cpu,
       memoryMiB: resources?.memoryMiB,
       timeoutMs: this.options.autoStopMs,
@@ -1148,17 +1371,39 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
       command: this.options.provider?.command ?? ["sleep", "infinity"],
       env: this.getMergedEnv(),
       encryptedPorts: this.options.provider?.encryptedPorts,
-      unencryptedPorts: this.options.provider?.unencryptedPorts,
+      unencryptedPorts,
       verbose: this.options.provider?.verbose
     });
     await sandbox.setTags(this.getTags());
     this.sandbox = sandbox;
   }
+  /**
+   * Modal requires ports to be declared at sandbox creation time — a running
+   * sandbox cannot gain new tunnels. To make `openPort` work predictably
+   * across providers, we pre-declare all well-known agent-harness ports on
+   * every Modal sandbox we create, unless the caller has explicitly pinned
+   * them to a specific (possibly empty) list.
+   */
+  resolveDefaultUnencryptedPorts() {
+    const declared = this.options.provider?.unencryptedPorts;
+    const encrypted = new Set(this.options.provider?.encryptedPorts ?? []);
+    const reserved = collectAllAgentReservedPorts().filter(
+      (port) => !encrypted.has(port)
+    );
+    if (declared === void 0) {
+      return reserved.length > 0 ? reserved : void 0;
+    }
+    const merged = new Set(declared);
+    for (const port of reserved) {
+      merged.add(port);
+    }
+    return Array.from(merged);
+  }
   async run(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const process2 = await sandbox.exec(
-      ["/bin/sh", "-lc", toShellCommand(command)],
+      ["/bin/sh", "-c", toShellCommand(command)],
       {
         workdir: options?.cwd ?? this.workingDir,
         timeoutMs: options?.timeoutMs,
@@ -1181,10 +1426,10 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     };
   }
   async runAsync(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const process2 = await sandbox.exec(
-      ["/bin/sh", "-lc", toShellCommand(command)],
+      ["/bin/sh", "-c", toShellCommand(command)],
       {
         workdir: options?.cwd ?? this.workingDir,
         timeoutMs: options?.timeoutMs,
@@ -1230,6 +1475,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: `${sandbox.sandboxId}:${Date.now()}`,
       raw: process2,
@@ -1246,6 +1492,49 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
       [Symbol.asyncIterator]: () => queue[Symbol.asyncIterator]()
     };
   }
+  /**
+   * Upload `files` as a tarball piped through stdin to a single in-sandbox
+   * `tar -x` invocation, then exec `command` — all in one Modal `exec`
+   * round-trip. This collapses the typical "N writeArtifact RPCs +
+   * runCommand" setup pattern (~25 RPCs on cold paths, ~6s wall) into a
+   * single ~1s call dominated by the actual install work.
+   */
+  async uploadAndRun(files, command, options) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const tar3 = await buildTarball(files);
+    const wrapped = `set -e
+tar -xf - -C /
+${command}`;
+    const process2 = await sandbox.exec(["/bin/sh", "-c", wrapped], {
+      workdir: options?.cwd ?? this.workingDir,
+      timeoutMs: options?.timeoutMs,
+      env: this.getMergedEnv(options?.env),
+      mode: "binary"
+    });
+    const writer = process2.stdin.getWriter();
+    try {
+      await writer.write(tar3);
+      await writer.close();
+    } finally {
+      try {
+        writer.releaseLock();
+      } catch {
+      }
+    }
+    const [stdout, stderr, exitCode] = await Promise.all([
+      readStreamAsText(process2.stdout),
+      readStreamAsText(process2.stderr),
+      process2.wait()
+    ]);
+    return {
+      exitCode,
+      stdout,
+      stderr,
+      combinedOutput: `${stdout}${stderr}`,
+      raw: process2
+    };
+  }
   async list(options) {
     const sandboxes = [];
     for await (const sandbox of this.client.sandboxes.list({
@@ -1262,7 +1551,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     return sandboxes;
   }
   async snapshot() {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const image = await sandbox.snapshotFilesystem();
     return image.imageId;
@@ -1274,6 +1563,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     }
     await sandbox.terminate();
     this.sandbox = void 0;
+    this.tunnelsPromise = void 0;
   }
   async delete() {
     await this.stop();
@@ -1284,12 +1574,44 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     if (provider.encryptedPorts?.includes(port)) {
       return;
     }
-    provider.unencryptedPorts = provider.unencryptedPorts?.includes(port) ? provider.unencryptedPorts : [...provider.unencryptedPorts ?? [], port];
+    const alreadyDeclared = provider.unencryptedPorts?.includes(port) ?? false;
+    if (!alreadyDeclared) {
+      provider.unencryptedPorts = [...provider.unencryptedPorts ?? [], port];
+    }
+    if (!this.sandbox) {
+      return;
+    }
+    if (alreadyDeclared) {
+      return;
+    }
+    try {
+      if (!this.tunnelsPromise) {
+        this.tunnelsPromise = this.sandbox.tunnels();
+      }
+      const tunnels = await this.tunnelsPromise;
+      if (tunnels[port]) {
+        return;
+      }
+    } catch {
+      return;
+    }
+    throw new Error(
+      `Modal sandbox is already running and cannot expose port ${port} dynamically. Declare it at creation time via \`provider.unencryptedPorts\` (e.g. \`provider: { unencryptedPorts: [${port}] }\`) or use \`AGENT_RESERVED_PORTS\` / \`collectAllAgentReservedPorts()\` from agentbox-sdk to pre-declare the agent harness ports.`
+    );
   }
   async getPreviewLink(port) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
-    const tunnels = await sandbox.tunnels();
+    if (!this.tunnelsPromise) {
+      this.tunnelsPromise = sandbox.tunnels();
+    }
+    let tunnels;
+    try {
+      tunnels = await this.tunnelsPromise;
+    } catch (error) {
+      this.tunnelsPromise = void 0;
+      throw error;
+    }
     const tunnel = tunnels[port];
     if (!tunnel) {
       throw new Error(`Modal sandbox does not expose port ${port}.`);
@@ -1347,22 +1669,335 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
   }
 };
 
+// src/sandboxes/providers/vercel.ts
+import { Sandbox as VercelSandbox } from "@vercel/sandbox";
+function pickFirstTag(tags) {
+  if (!tags) return void 0;
+  const entries = Object.entries(tags);
+  if (entries.length === 0) return void 0;
+  const [key, value] = entries[0];
+  return { [key]: value };
+}
+function matchesAllTags(candidateTags, required) {
+  return Object.entries(required).every(
+    ([key, value]) => candidateTags?.[key] === value
+  );
+}
+function describeVercelApiError(error, action) {
+  if (error && typeof error === "object" && "response" in error && error.response instanceof Response) {
+    const apiError = error;
+    const status = apiError.response.status;
+    const body = apiError.json !== void 0 ? JSON.stringify(apiError.json) : apiError.text ?? "";
+    return new Error(
+      `Vercel ${action} failed with HTTP ${status}: ${body || apiError.message}`
+    );
+  }
+  return error instanceof Error ? error : new Error(String(error));
+}
+async function wrapVercelApiError(action, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw describeVercelApiError(error, action);
+  }
+}
+function buildTimeoutSignal(timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0) return void 0;
+  return AbortSignal.timeout(timeoutMs);
+}
+function getCredentials(options) {
+  const token = options.provider?.token ?? process.env.VERCEL_TOKEN;
+  const teamId = options.provider?.teamId ?? process.env.VERCEL_TEAM_ID;
+  const projectId = options.provider?.projectId ?? process.env.VERCEL_PROJECT_ID;
+  if (token && teamId && projectId) {
+    return { token, teamId, projectId };
+  }
+  return {};
+}
+var VercelSandboxAdapter = class extends SandboxAdapter {
+  sandbox;
+  get provider() {
+    return SandboxProvider.Vercel;
+  }
+  get raw() {
+    return { sandbox: this.sandbox };
+  }
+  get id() {
+    return this.sandbox?.name;
+  }
+  get workingDir() {
+    return this.options.workingDir ?? "/vercel/sandbox";
+  }
+  get previewHeaders() {
+    const token = this.options.provider?.protectionBypass;
+    return token ? { "x-vercel-protection-bypass": token } : {};
+  }
+  async provision() {
+    const existing = await this.findExistingSandbox();
+    if (existing) {
+      this.sandbox = existing;
+      return;
+    }
+    const credentials = getCredentials(this.options);
+    const provider = this.options.provider;
+    const snapshotId = provider?.snapshotId;
+    const timeout = provider?.timeoutMs ?? 12e4;
+    const runtime = provider?.runtime ?? "node24";
+    const resources = resolveSandboxResources(this.options.resources);
+    const vcpus = resources?.cpu ? { resources: { vcpus: resources.cpu } } : {};
+    const base = {
+      ...credentials,
+      timeout,
+      env: this.getMergedEnv(),
+      ...vcpus,
+      tags: this.getTags(),
+      ...provider?.ports?.length ? { ports: provider.ports } : {}
+    };
+    const sandbox = await wrapVercelApiError("create sandbox", () => {
+      if (snapshotId) {
+        return VercelSandbox.create({
+          ...base,
+          source: { type: "snapshot", snapshotId }
+        });
+      }
+      if (provider?.gitSource) {
+        const git = provider.gitSource;
+        const source = {
+          type: "git",
+          url: git.url,
+          depth: git.depth,
+          revision: git.revision,
+          ...git.username && git.password ? { username: git.username, password: git.password } : {}
+        };
+        return VercelSandbox.create({ ...base, runtime, source });
+      }
+      return VercelSandbox.create({ ...base, runtime });
+    });
+    this.sandbox = sandbox;
+    if (this.workingDir !== "/vercel/sandbox") {
+      await wrapVercelApiError(
+        "create working directory",
+        () => sandbox.runCommand({
+          cmd: "mkdir",
+          args: ["-p", this.workingDir],
+          sudo: true
+        })
+      );
+    }
+  }
+  async run(command, options) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const signal = buildTimeoutSignal(options?.timeoutMs);
+    const result = await wrapVercelApiError(
+      "run command",
+      () => sandbox.runCommand({
+        cmd: "sh",
+        args: ["-lc", toShellCommand(command)],
+        cwd: options?.cwd ?? this.workingDir,
+        env: this.getMergedEnv(options?.env),
+        ...signal ? { signal } : {}
+      })
+    );
+    const [stdout, stderr] = await Promise.all([
+      result.stdout(),
+      result.stderr()
+    ]);
+    return {
+      exitCode: result.exitCode,
+      stdout,
+      stderr,
+      combinedOutput: `${stdout}${stderr}`,
+      raw: result
+    };
+  }
+  async runAsync(command, options) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const signal = buildTimeoutSignal(options?.timeoutMs);
+    const cmd = await wrapVercelApiError(
+      "start async command",
+      () => sandbox.runCommand({
+        cmd: "sh",
+        args: ["-lc", toShellCommand(command)],
+        cwd: options?.cwd ?? this.workingDir,
+        env: this.getMergedEnv(options?.env),
+        detached: true,
+        ...signal ? { signal } : {}
+      })
+    );
+    const queue = new AsyncQueue();
+    let stdout = "";
+    let stderr = "";
+    const completion = (async () => {
+      for await (const log of cmd.logs()) {
+        if (log.stream === "stdout") {
+          stdout += log.data;
+          queue.push({
+            type: "stdout",
+            chunk: log.data,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        } else {
+          stderr += log.data;
+          queue.push({
+            type: "stderr",
+            chunk: log.data,
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        }
+      }
+      const finished2 = await cmd.wait();
+      const exitCode = finished2.exitCode;
+      queue.push({
+        type: "exit",
+        exitCode,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      queue.finish();
+      return {
+        exitCode,
+        stdout,
+        stderr,
+        combinedOutput: `${stdout}${stderr}`,
+        raw: finished2
+      };
+    })().catch((error) => {
+      queue.fail(error);
+      throw error;
+    });
+    suppressUnhandledRejection(completion);
+    return {
+      id: cmd.cmdId,
+      raw: cmd,
+      wait: () => completion,
+      kill: async () => {
+        await cmd.kill();
+      },
+      [Symbol.asyncIterator]: () => queue[Symbol.asyncIterator]()
+    };
+  }
+  async list(options) {
+    const filterTags = options?.tags ?? this.getTags();
+    const sandboxes = await this.listSandboxesByTags(filterTags);
+    return sandboxes.map(
+      (s) => ({
+        provider: this.provider,
+        id: s.name,
+        state: s.status,
+        tags: s.tags ?? {},
+        createdAt: new Date(s.createdAt).toISOString(),
+        raw: s
+      })
+    );
+  }
+  async snapshot() {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const snap = await wrapVercelApiError(
+      "snapshot sandbox",
+      () => sandbox.snapshot()
+    );
+    return snap.snapshotId;
+  }
+  async stop() {
+    const sandbox = this.sandbox;
+    if (!sandbox) {
+      return;
+    }
+    await wrapVercelApiError("stop sandbox", () => sandbox.stop());
+    this.sandbox = void 0;
+  }
+  async delete() {
+    await this.stop();
+  }
+  async openPort(_port) {
+    void _port;
+  }
+  async getPreviewLink(port) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    return sandbox.domain(port);
+  }
+  async uploadFile(content, targetPath) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const data = typeof content === "string" ? content : new Uint8Array(content);
+    await sandbox.writeFiles([{ path: targetPath, content: data }]);
+  }
+  async downloadFile(sourcePath) {
+    this.requireProvisioned();
+    const sandbox = this.requireSandbox();
+    const result = await sandbox.readFileToBuffer({ path: sourcePath });
+    if (!result) {
+      throw new Error(`File not found in Vercel sandbox: ${sourcePath}`);
+    }
+    return result;
+  }
+  getTags() {
+    return {
+      "agentbox.provider": this.provider,
+      ...this.options.tags ?? {}
+    };
+  }
+  async listSandboxesByTags(tags) {
+    const credentials = getCredentials(this.options);
+    const result = await wrapVercelApiError(
+      "list sandboxes",
+      () => VercelSandbox.list({
+        ...credentials,
+        tags: pickFirstTag(tags)
+      })
+    );
+    return result.sandboxes.filter(
+      (s) => matchesAllTags(s.tags, tags)
+    );
+  }
+  async findExistingSandbox() {
+    const credentials = getCredentials(this.options);
+    const sandboxes = await this.listSandboxesByTags(this.getTags());
+    const match = sandboxes.find((s) => s.status === "running");
+    if (!match) {
+      return void 0;
+    }
+    return wrapVercelApiError(
+      "get sandbox",
+      () => VercelSandbox.get({ ...credentials, name: match.name })
+    );
+  }
+  requireSandbox() {
+    if (!this.sandbox) {
+      throw new Error("Vercel sandbox has not been provisioned.");
+    }
+    return this.sandbox;
+  }
+};
+
 // src/sandboxes/Sandbox.ts
+function shortLabel(command) {
+  const oneLine = Array.isArray(command) ? command.join(" ") : command;
+  const cleaned = oneLine.replace(/\s+/g, " ").trim();
+  return cleaned.length > 80 ? `${cleaned.slice(0, 80)}\u2026` : cleaned;
+}
 function createSandboxAdapter(provider, options) {
   switch (provider) {
-    case "local-docker":
+    case SandboxProvider.LocalDocker:
       return new LocalDockerSandboxAdapter(
         options
       );
-    case "modal":
+    case SandboxProvider.Modal:
       return new ModalSandboxAdapter(
         options
       );
-    case "daytona":
+    case SandboxProvider.Daytona:
       return new DaytonaSandboxAdapter(
         options
       );
-    case "e2b":
+    case SandboxProvider.Vercel:
+      return new VercelSandboxAdapter(
+        options
+      );
+    case SandboxProvider.E2B:
       return new E2bSandboxAdapter(
         options
       );
@@ -1391,8 +2026,35 @@ var Sandbox = class {
   get raw() {
     return this.adapter.raw;
   }
+  /**
+   * 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() {
+    return this.adapter.wasFound;
+  }
+  /**
+   * 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).
+   */
+  async findOrProvision() {
+    await time(
+      debugSandbox,
+      `findOrProvision [${this.provider}]`,
+      () => this.adapter.findOrProvision()
+    );
+    return this;
+  }
   async openPort(port) {
-    await this.adapter.openPort(port);
+    await time(
+      debugSandbox,
+      `openPort [${this.provider}] :${port}`,
+      () => this.adapter.openPort(port)
+    );
     return this;
   }
   setSecret(name, value) {
@@ -1407,10 +2069,19 @@ var Sandbox = class {
     return this.adapter.gitClone(options);
   }
   async run(command, options) {
-    return this.adapter.run(command, options);
+    return time(
+      debugSandbox,
+      `run [${this.provider}] ${shortLabel(command)}`,
+      () => this.adapter.run(command, options),
+      (result) => ({ exit: result.exitCode })
+    );
   }
   async runAsync(command, options) {
-    return this.adapter.runAsync(command, options);
+    return time(
+      debugSandbox,
+      `runAsync [${this.provider}] ${shortLabel(command)}`,
+      () => this.adapter.runAsync(command, options)
+    );
   }
   async list(options) {
     return this.adapter.list(options);
@@ -1425,7 +2096,28 @@ var Sandbox = class {
     return this.adapter.delete();
   }
   async getPreviewLink(port) {
-    return this.adapter.getPreviewLink(port);
+    return time(
+      debugSandbox,
+      `getPreviewLink [${this.provider}] :${port}`,
+      () => this.adapter.getPreviewLink(port)
+    );
+  }
+  get previewHeaders() {
+    return this.adapter.previewHeaders;
+  }
+  async uploadFile(content, targetPath) {
+    return this.adapter.uploadFile(content, targetPath);
+  }
+  async downloadFile(sourcePath) {
+    return this.adapter.downloadFile(sourcePath);
+  }
+  async uploadAndRun(files, command, options) {
+    return time(
+      debugSandbox,
+      `uploadAndRun [${this.provider}] ${shortLabel(command)}`,
+      () => this.adapter.uploadAndRun(files, command, options),
+      (result) => ({ exit: result.exitCode, files: files.length })
+    );
   }
 };