agentbox-sdk 0.1.1 → 0.1.3

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

@@ -2,19 +2,21 @@ import {
   AsyncQueue,
   UnsupportedProviderError,
   collectAllAgentReservedPorts,
+  debugSandbox,
   pipeReadableStream,
   readNodeStream,
   readStreamAsText,
   sleep,
-  suppressUnhandledRejection
-} from "./chunk-O7HCJXKW.js";
+  suppressUnhandledRejection,
+  time
+} from "./chunk-INMA52FV.js";
 import {
   shellQuote,
   toShellCommand
 } from "./chunk-NSJM57Z4.js";
 import {
   SandboxProvider
-} from "./chunk-2NKMDGYH.js";
+} from "./chunk-GOFJNFAD.js";
 
 // src/sandboxes/git.ts
 function encodeExtraHeader(name, value) {
@@ -60,6 +62,13 @@ 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 ?? {} };
@@ -77,26 +86,90 @@ var SandboxAdapter = class {
       `downloadFile is not supported by the ${this.provider} provider.`
     );
   }
-  async ensureProvisioned() {
+  /**
+   * 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
@@ -119,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()
@@ -169,6 +242,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     if (existing) {
       this.sandbox = existing;
       await existing.start();
+      this.wasFoundFlag = true;
       return;
     }
     const labels = this.getLabels();
@@ -197,6 +271,7 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
       autoDeleteInterval
     };
     const sandbox = await this.client.create({
+      ...this.options.provider?.createParams,
       ...createBase,
       snapshot: image
     });
@@ -204,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),
@@ -222,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);
@@ -318,6 +393,13 @@ var DaytonaSandboxAdapter = class extends SandboxAdapter {
     return {
       id: commandId,
       raw: { sessionId, commandId },
+      write: async (input) => {
+        await sandbox.process.sendSessionCommandInput(
+          sessionId,
+          commandId,
+          input
+        );
+      },
       wait: () => completion,
       kill: async () => {
         killed = true;
@@ -358,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,
@@ -424,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);
@@ -449,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) {
@@ -477,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();
@@ -653,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;
@@ -673,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();
@@ -713,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() {
@@ -818,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;
@@ -850,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,
@@ -893,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,
@@ -1047,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");
@@ -1064,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 = [];
@@ -1079,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,
@@ -1131,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({
@@ -1160,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";
@@ -1171,6 +1362,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     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,
@@ -1208,10 +1400,10 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     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,
@@ -1234,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,
@@ -1300,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({
@@ -1316,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;
@@ -1328,6 +1563,7 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     }
     await sandbox.terminate();
     this.sandbox = void 0;
+    this.tunnelsPromise = void 0;
   }
   async delete() {
     await this.stop();
@@ -1345,8 +1581,14 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     if (!this.sandbox) {
       return;
     }
+    if (alreadyDeclared) {
+      return;
+    }
     try {
-      const tunnels = await this.sandbox.tunnels();
+      if (!this.tunnelsPromise) {
+        this.tunnelsPromise = this.sandbox.tunnels();
+      }
+      const tunnels = await this.tunnelsPromise;
       if (tunnels[port]) {
         return;
       }
@@ -1358,9 +1600,18 @@ var ModalSandboxAdapter = class extends SandboxAdapter {
     );
   }
   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}.`);
@@ -1535,7 +1786,7 @@ var VercelSandboxAdapter = class extends SandboxAdapter {
     }
   }
   async run(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const signal = buildTimeoutSignal(options?.timeoutMs);
     const result = await wrapVercelApiError(
@@ -1561,7 +1812,7 @@ var VercelSandboxAdapter = class extends SandboxAdapter {
     };
   }
   async runAsync(command, options) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const signal = buildTimeoutSignal(options?.timeoutMs);
     const cmd = await wrapVercelApiError(
@@ -1641,7 +1892,7 @@ var VercelSandboxAdapter = class extends SandboxAdapter {
     );
   }
   async snapshot() {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const snap = await wrapVercelApiError(
       "snapshot sandbox",
@@ -1664,18 +1915,18 @@ var VercelSandboxAdapter = class extends SandboxAdapter {
     void _port;
   }
   async getPreviewLink(port) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     return sandbox.domain(port);
   }
   async uploadFile(content, targetPath) {
-    await this.ensureProvisioned();
+    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) {
-    await this.ensureProvisioned();
+    this.requireProvisioned();
     const sandbox = this.requireSandbox();
     const result = await sandbox.readFileToBuffer({ path: sourcePath });
     if (!result) {
@@ -1723,6 +1974,11 @@ var VercelSandboxAdapter = class extends SandboxAdapter {
 };
 
 // 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 SandboxProvider.LocalDocker:
@@ -1770,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) {
@@ -1786,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);
@@ -1804,7 +2096,11 @@ 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;
@@ -1815,6 +2111,14 @@ var Sandbox = class {
   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 })
+    );
+  }
 };
 
 export {