agentbox-sdk 0.1.0 → 0.1.1

package/dist/{chunk-HMBWQSVN.js → chunk-O7HCJXKW.js}

@@ -1,3 +1,23 @@
+import {
+  AgentProvider
+} from "./chunk-2NKMDGYH.js";
+
+// src/agents/ports.ts
+var AGENT_RESERVED_PORTS = {
+  [AgentProvider.ClaudeCode]: [43180],
+  [AgentProvider.Codex]: [43181],
+  [AgentProvider.OpenCode]: [4096]
+};
+function collectAllAgentReservedPorts() {
+  const seen = /* @__PURE__ */ new Set();
+  for (const ports of Object.values(AGENT_RESERVED_PORTS)) {
+    for (const port of ports) {
+      seen.add(port);
+    }
+  }
+  return Array.from(seen);
+}
+
 // src/shared/errors.ts
 var AgentBoxError = class extends Error {
   code;
@@ -24,6 +44,10 @@ function asError(error) {
   }
   return new Error(typeof error === "string" ? error : JSON.stringify(error));
 }
+function suppressUnhandledRejection(promise) {
+  promise.catch(() => void 0);
+  return promise;
+}
 
 // src/shared/async-queue.ts
 var AsyncQueue = class {
@@ -193,6 +217,7 @@ export {
   AgentBoxError,
   UnsupportedProviderError,
   asError,
+  suppressUnhandledRejection,
   AsyncQueue,
   sleep,
   getAvailablePort,
@@ -200,5 +225,7 @@ export {
   readStreamAsText,
   pipeReadableStream,
   readNodeStream,
-  linesFromTextChunks
+  linesFromTextChunks,
+  AGENT_RESERVED_PORTS,
+  collectAllAgentReservedPorts
 };

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

@@ -1,15 +1,20 @@
 import {
   AsyncQueue,
   UnsupportedProviderError,
+  collectAllAgentReservedPorts,
   pipeReadableStream,
   readNodeStream,
   readStreamAsText,
-  sleep
-} from "./chunk-HMBWQSVN.js";
+  sleep,
+  suppressUnhandledRejection
+} from "./chunk-O7HCJXKW.js";
 import {
   shellQuote,
   toShellCommand
-} from "./chunk-JFDP556Q.js";
+} from "./chunk-NSJM57Z4.js";
+import {
+  SandboxProvider
+} from "./chunk-2NKMDGYH.js";
 
 // src/sandboxes/git.ts
 function encodeExtraHeader(name, value) {
@@ -59,6 +64,19 @@ var SandboxAdapter = class {
     this.options = options;
     this.baseEnv = { ...options.env ?? {} };
   }
+  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.`
+    );
+  }
   async ensureProvisioned() {
     if (this.provisioned) {
       return;
@@ -79,6 +97,14 @@ var SandboxAdapter = class {
   get workingDir() {
     return this.options.workingDir ?? "/workspace";
   }
+  /**
+   * 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,
@@ -127,7 +153,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     });
   }
   get provider() {
-    return "daytona";
+    return SandboxProvider.Daytona;
   }
   get raw() {
     return {
@@ -288,6 +314,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: commandId,
       raw: { sessionId, commandId },
@@ -382,7 +409,7 @@ async function loadE2bModule() {
 var E2bSandboxAdapter = class extends SandboxAdapter {
   sandbox;
   get provider() {
-    return "e2b";
+    return SandboxProvider.E2B;
   }
   get raw() {
     return {
@@ -520,6 +547,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: String(handle.pid),
       raw: handle,
@@ -585,6 +613,7 @@ var E2bSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: String(handle.pid),
       raw: handle,
@@ -762,7 +791,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
   client = new Docker();
   container;
   get provider() {
-    return "local-docker";
+    return SandboxProvider.LocalDocker;
   }
   get raw() {
     return {
@@ -921,6 +950,7 @@ var LocalDockerSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: exec.id,
       raw: { exec, stream },
@@ -1115,7 +1145,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     });
   }
   get provider() {
-    return "modal";
+    return SandboxProvider.Modal;
   }
   get raw() {
     return {
@@ -1139,6 +1169,7 @@ 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, {
       cpu: resources?.cpu,
       memoryMiB: resources?.memoryMiB,
@@ -1148,12 +1179,34 @@ 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();
     const sandbox = this.requireSandbox();
@@ -1230,6 +1283,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
       queue.fail(error);
       throw error;
     });
+    suppressUnhandledRejection(completion);
     return {
       id: `${sandbox.sandboxId}:${Date.now()}`,
       raw: process2,
@@ -1284,7 +1338,24 @@ 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;
+    }
+    try {
+      const tunnels = await this.sandbox.tunnels();
+      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();
@@ -1347,22 +1418,330 @@ 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) {
+    await this.ensureProvisioned();
+    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) {
+    await this.ensureProvisioned();
+    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() {
+    await this.ensureProvisioned();
+    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) {
+    await this.ensureProvisioned();
+    const sandbox = this.requireSandbox();
+    return sandbox.domain(port);
+  }
+  async uploadFile(content, targetPath) {
+    await this.ensureProvisioned();
+    const sandbox = this.requireSandbox();
+    const data = typeof content === "string" ? content : new Uint8Array(content);
+    await sandbox.writeFiles([{ path: targetPath, content: data }]);
+  }
+  async downloadFile(sourcePath) {
+    await this.ensureProvisioned();
+    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 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
       );
@@ -1427,6 +1806,15 @@ var Sandbox = class {
   async getPreviewLink(port) {
     return 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);
+  }
 };
 
 export {

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import {
   toShellCommand
-} from "./chunk-JFDP556Q.js";
+} from "./chunk-NSJM57Z4.js";
+import {
+  SandboxProvider
+} from "./chunk-2NKMDGYH.js";
 
 // src/sandbox-images/build.ts
 import { existsSync } from "fs";
@@ -77,14 +80,18 @@ async function buildSandboxImage(options) {
     options.cwd
   );
   switch (options.provider) {
-    case "local-docker":
+    case SandboxProvider.LocalDocker:
       return buildLocalDockerImage(definition, options);
-    case "modal":
+    case SandboxProvider.Modal:
       return buildModalImage(definition, options);
-    case "daytona":
+    case SandboxProvider.Daytona:
       return buildDaytonaSnapshot(definition, options);
-    case "e2b":
+    case SandboxProvider.E2B:
       return buildE2bTemplate(definition, options);
+    default:
+      throw new Error(
+        `Image building is not supported for provider "${options.provider}". Vercel sandboxes use runtime snapshots instead \u2014 see Sandbox.snapshot().`
+      );
   }
 }
 async function loadSandboxImageDefinition(preset, file, cwd = process.cwd()) {
@@ -371,7 +378,7 @@ function parseOptions(args) {
   return options;
 }
 function isSandboxProviderName(value) {
-  return value === "local-docker" || value === "modal" || value === "daytona" || value === "e2b";
+  return Object.values(SandboxProvider).includes(value);
 }
 function isBuiltInImageName(value) {
   return value === "browser-agent" || value === "computer-use";
@@ -380,8 +387,8 @@ function printHelp() {
   process.stdout.write(`agentbox
 
 Usage:
-  agentbox image build --provider <local-docker|modal|daytona|e2b> --preset <browser-agent|computer-use>
-  agentbox image build --provider <local-docker|modal|daytona|e2b> --file <path>
+  agentbox image build --provider <local-docker|modal|daytona|vercel|e2b> --preset <browser-agent|computer-use>
+  agentbox image build --provider <local-docker|modal|daytona|vercel|e2b> --file <path>
 
 Options:
   --image-name <name>        Override the built artifact name
@@ -390,6 +397,7 @@ Options:
 Environment:
   Modal: MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, MODAL_ENVIRONMENT?, MODAL_ENDPOINT?
   Daytona: DAYTONA_API_KEY or DAYTONA_JWT_TOKEN, DAYTONA_ORGANIZATION_ID?, DAYTONA_API_URL?, DAYTONA_TARGET?
+  Vercel: VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID
   E2B: E2B_API_KEY, E2B_DOMAIN?, E2B_ACCESS_TOKEN?
 `);
 }

package/dist/enums.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure value-level provider enums.
+ *
+ * This file MUST NOT import anything from the rest of the SDK. It is used as
+ * a standalone tsup entry (`agentbox-sdk/enums`) so that client-side bundles
+ * in Next.js/browser contexts can reference `AgentProvider`/`SandboxProvider`
+ * without pulling in server-only modules like `net`, `crypto`, or the sandbox
+ * provider adapters.
+ */
+declare const AgentProvider: {
+    readonly ClaudeCode: "claude-code";
+    readonly OpenCode: "opencode";
+    readonly Codex: "codex";
+};
+type AgentProvider = (typeof AgentProvider)[keyof typeof AgentProvider];
+declare const SandboxProvider: {
+    readonly LocalDocker: "local-docker";
+    readonly Modal: "modal";
+    readonly Daytona: "daytona";
+    readonly Vercel: "vercel";
+    readonly E2B: "e2b";
+};
+type SandboxProvider = (typeof SandboxProvider)[keyof typeof SandboxProvider];
+
+export { AgentProvider, SandboxProvider };

package/dist/enums.js

@@ -0,0 +1,8 @@
+import {
+  AgentProvider,
+  SandboxProvider
+} from "./chunk-2NKMDGYH.js";
+export {
+  AgentProvider,
+  SandboxProvider
+};