@hasna/sandboxes 0.1.7 → 0.1.9

package/dist/mcp/index.js

@@ -147,10 +147,11 @@ class E2BProvider {
         onStderr: opts?.onStderr ? (data) => opts.onStderr(data) : undefined,
         envs: opts?.env,
         cwd: opts?.cwd,
-        timeoutMs: opts?.timeout ? opts.timeout * 1000 : undefined
+        timeoutMs: opts?.timeout ? opts.timeout * 1000 : undefined,
+        ...opts?.stdin !== undefined ? { stdin: opts.stdin } : {}
       });
       return {
-        exit_code: result.exitCode,
+        exit_code: result.exitCode ?? 0,
         stdout: result.stdout,
         stderr: result.stderr
       };
@@ -158,10 +159,28 @@ class E2BProvider {
       throw new ProviderError("e2b", `Failed to exec command: ${err.message}`);
     }
   }
-  async readFile(sandboxId, path) {
+  async readFile(sandboxId, path, opts) {
     const sandbox = await this.getInstance(sandboxId);
     try {
-      return await sandbox.files.read(path, { format: "text" });
+      if (opts?.encoding === "base64") {
+        const bytes = await sandbox.files.read(path, { format: "bytes" });
+        const sliced = opts.offset !== undefined || opts.limit !== undefined ? bytes.slice(opts.offset ?? 0, opts.limit !== undefined ? (opts.offset ?? 0) + opts.limit : undefined) : bytes;
+        return Buffer.from(sliced).toString("base64");
+      } else if (opts?.encoding === "hex") {
+        const bytes = await sandbox.files.read(path, { format: "bytes" });
+        const sliced = opts.offset !== undefined || opts.limit !== undefined ? bytes.slice(opts.offset ?? 0, opts.limit !== undefined ? (opts.offset ?? 0) + opts.limit : undefined) : bytes;
+        return Buffer.from(sliced).toString("hex");
+      } else {
+        const content = await sandbox.files.read(path, { format: "text" });
+        if (opts?.offset !== undefined || opts?.limit !== undefined) {
+          const lines = content.split(`
+`);
+          const sliced = lines.slice(opts.offset ?? 0, opts.limit !== undefined ? (opts.offset ?? 0) + opts.limit : undefined);
+          return sliced.join(`
+`);
+        }
+        return content;
+      }
     } catch (err) {
       throw new ProviderError("e2b", `Failed to read file ${path}: ${err.message}`);
     }
@@ -174,9 +193,21 @@ class E2BProvider {
       throw new ProviderError("e2b", `Failed to write file ${path}: ${err.message}`);
     }
   }
-  async listFiles(sandboxId, path) {
+  async listFiles(sandboxId, path, opts) {
     const sandbox = await this.getInstance(sandboxId);
     try {
+      if (opts?.recursive || opts?.glob) {
+        const pattern = opts.glob ? opts.glob : "*";
+        const cmd = opts.recursive ? `find ${JSON.stringify(path)} -name ${JSON.stringify(pattern)} 2>/dev/null | head -500` : `ls -la ${JSON.stringify(path)}/${pattern} 2>/dev/null`;
+        const result = await sandbox.commands.run(cmd);
+        return result.stdout.trim().split(`
+`).filter(Boolean).map((p) => ({
+          path: p.trim(),
+          name: p.trim().split("/").pop() || p.trim(),
+          is_dir: false,
+          size: 0
+        }));
+      }
       const entries = await sandbox.files.list(path);
       return entries.map((e) => ({
         path: e.path,
@@ -217,6 +248,15 @@ class E2BProvider {
       throw new ProviderError("e2b", `Failed to resume sandbox: ${err.message}`);
     }
   }
+  async getPublicUrl(sandboxId, port, _protocol) {
+    const sandbox = await this.getInstance(sandboxId);
+    try {
+      const host = sandbox.getHost(port);
+      return `https://${host}`;
+    } catch (err) {
+      throw new ProviderError("e2b", `Failed to get public URL for port ${port}: ${err.message}`);
+    }
+  }
   async keepAlive(sandboxId, durationMs) {
     const sandbox = await this.getInstance(sandboxId);
     try {
@@ -377,6 +417,9 @@ class DaytonaProvider {
       throw new ProviderError("daytona", `Failed to delete sandbox: ${err.message}`);
     }
   }
+  async getPublicUrl(_sandboxId, _port, _protocol) {
+    throw new ProviderError("daytona", "Port forwarding not supported by Daytona provider");
+  }
   async pause(_sandboxId) {
     throw new ProviderError("daytona", "Pause/resume not supported by Daytona provider");
   }
@@ -605,6 +648,9 @@ class ModalProvider {
   async delete(sandboxId) {
     await this.stop(sandboxId);
   }
+  async getPublicUrl(_sandboxId, _port, _protocol) {
+    throw new ProviderError("modal", "Port forwarding not supported by Modal provider");
+  }
   async pause(_sandboxId) {
     throw new ProviderError("modal", "Pause/resume not supported by Modal provider");
   }
@@ -4795,6 +4841,24 @@ ALTER TABLE sandbox_sessions_new RENAME TO sandbox_sessions;
 CREATE INDEX IF NOT EXISTS idx_sessions_sandbox ON sandbox_sessions(sandbox_id);
 CREATE INDEX IF NOT EXISTS idx_sessions_status ON sandbox_sessions(status);
 INSERT OR IGNORE INTO _migrations (id) VALUES (3);
+  `,
+  `
+CREATE TABLE IF NOT EXISTS snapshots (
+  id TEXT PRIMARY KEY,
+  sandbox_id TEXT NOT NULL,
+  provider_sandbox_id TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  name TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_snapshots_sandbox ON snapshots(sandbox_id);
+INSERT OR IGNORE INTO _migrations (id) VALUES (4);
+  `,
+  `
+ALTER TABLE sandboxes ADD COLUMN budget_limit_usd REAL;
+ALTER TABLE sandboxes ADD COLUMN on_budget_exceeded TEXT NOT NULL DEFAULT 'terminate' CHECK(on_budget_exceeded IN ('terminate', 'pause', 'notify'));
+ALTER TABLE sandboxes ADD COLUMN started_at TEXT;
+INSERT OR IGNORE INTO _migrations (id) VALUES (5);
   `
 ];
 var db = null;
@@ -4855,6 +4919,9 @@ function rowToSandbox(row) {
     project_id: row.project_id,
     on_timeout: row.on_timeout ?? "terminate",
     auto_resume: row.auto_resume === 1,
+    budget_limit_usd: row.budget_limit_usd ?? null,
+    on_budget_exceeded: row.on_budget_exceeded ?? "terminate",
+    started_at: row.started_at ?? null,
     created_at: row.created_at,
     updated_at: row.updated_at
   };
@@ -4872,8 +4939,10 @@ function createSandbox(input) {
   const project_id = input.project_id ?? null;
   const on_timeout = input.on_timeout ?? "terminate";
   const auto_resume = input.auto_resume ? 1 : 0;
-  db2.query(`INSERT INTO sandboxes (id, provider, name, status, image, timeout, config, env_vars, project_id, on_timeout, auto_resume, created_at, updated_at)
-     VALUES (?, ?, ?, 'creating', ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, provider, name, image, timeout, config, env_vars, project_id, on_timeout, auto_resume, timestamp, timestamp);
+  const budget_limit_usd = input.budget_limit_usd ?? null;
+  const on_budget_exceeded = input.on_budget_exceeded ?? "terminate";
+  db2.query(`INSERT INTO sandboxes (id, provider, name, status, image, timeout, config, env_vars, project_id, on_timeout, auto_resume, budget_limit_usd, on_budget_exceeded, created_at, updated_at)
+     VALUES (?, ?, ?, 'creating', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, provider, name, image, timeout, config, env_vars, project_id, on_timeout, auto_resume, budget_limit_usd, on_budget_exceeded, timestamp, timestamp);
   return getSandbox(id);
 }
 function getSandbox(id) {
@@ -4945,6 +5014,10 @@ function updateSandbox(id, updates) {
     setClauses.push("keep_alive_until = ?");
     params.push(updates.keep_alive_until);
   }
+  if (updates.started_at !== undefined) {
+    setClauses.push("started_at = ?");
+    params.push(updates.started_at);
+  }
   if (setClauses.length === 0) {
     return getSandbox(resolvedId);
   }
@@ -5183,6 +5256,46 @@ function deleteTemplate(id) {
   db2.query("DELETE FROM templates WHERE id = ?").run(resolvedId);
 }
 
+// src/db/snapshots.ts
+class SnapshotNotFoundError extends Error {
+  constructor(id) {
+    super(`Snapshot not found: ${id}`);
+    this.name = "SnapshotNotFoundError";
+  }
+}
+function createSnapshot(input) {
+  const db2 = getDatabase();
+  const id = uuid();
+  const timestamp = now();
+  db2.query(`INSERT INTO snapshots (id, sandbox_id, provider_sandbox_id, provider, name, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(id, input.sandbox_id, input.provider_sandbox_id, input.provider, input.name ?? null, timestamp);
+  return getSnapshot(id);
+}
+function getSnapshot(id) {
+  const db2 = getDatabase();
+  const resolvedId = resolvePartialId("snapshots", id);
+  if (!resolvedId)
+    throw new SnapshotNotFoundError(id);
+  const row = db2.query("SELECT * FROM snapshots WHERE id = ?").get(resolvedId);
+  if (!row)
+    throw new SnapshotNotFoundError(id);
+  return row;
+}
+function listSnapshots(sandboxId) {
+  const db2 = getDatabase();
+  if (sandboxId) {
+    return db2.query("SELECT * FROM snapshots WHERE sandbox_id = ? ORDER BY created_at DESC").all(sandboxId);
+  }
+  return db2.query("SELECT * FROM snapshots ORDER BY created_at DESC").all();
+}
+function deleteSnapshot(id) {
+  const db2 = getDatabase();
+  const resolvedId = resolvePartialId("snapshots", id);
+  if (!resolvedId)
+    throw new SnapshotNotFoundError(id);
+  db2.query("DELETE FROM snapshots WHERE id = ?").run(resolvedId);
+}
+
 // src/providers/index.ts
 init_types();
 
@@ -5426,13 +5539,23 @@ function getAgentDriver(name) {
 }
 
 // src/lib/agent-runner.ts
+async function fireWebhook(url, payload) {
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload)
+    });
+  } catch {}
+}
 async function runAgent(sandboxId, opts) {
   const sandbox = getSandbox(sandboxId);
   if (!sandbox.provider_sandbox_id) {
     throw new Error("Sandbox has no provider instance");
   }
   const provider = await getProvider(sandbox.provider);
-  const env = Object.keys(sandbox.env_vars ?? {}).length > 0 ? sandbox.env_vars : undefined;
+  const mergedEnv = { ...sandbox.env_vars, ...opts.callEnvVars };
+  const env = Object.keys(mergedEnv).length > 0 ? mergedEnv : undefined;
   let cmd;
   const driver = opts.agentType !== "custom" ? getAgentDriver(opts.agentType) : undefined;
   if (opts.command) {
@@ -5451,6 +5574,18 @@ async function runAgent(sandboxId, opts) {
     command: cmd
   });
   emitLifecycleEvent(sandbox.id, `Agent ${opts.agentType} started: ${opts.prompt.slice(0, 100)}`);
+  const startedAt = Date.now();
+  const webhookEvents = opts.webhookEvents ?? ["start", "complete", "error"];
+  if (opts.webhookUrl && webhookEvents.includes("start")) {
+    fireWebhook(opts.webhookUrl, {
+      event: "start",
+      session_id: session.id,
+      sandbox_id: sandbox.id,
+      agent_type: opts.agentType,
+      status: "running",
+      timestamp: new Date().toISOString()
+    });
+  }
   const collector = createStreamCollector(sandbox.id, session.id);
   provider.exec(sandbox.provider_sandbox_id, cmd, {
     onStdout: (data) => {
@@ -5467,9 +5602,32 @@ async function runAgent(sandboxId, opts) {
     const status = exitResult.exit_code === 0 ? "completed" : "failed";
     endSession(session.id, exitResult.exit_code ?? 0, status);
     emitLifecycleEvent(sandbox.id, `Agent ${opts.agentType} finished with exit code ${exitResult.exit_code}`);
+    if (opts.webhookUrl && webhookEvents.includes("complete")) {
+      fireWebhook(opts.webhookUrl, {
+        event: "complete",
+        session_id: session.id,
+        sandbox_id: sandbox.id,
+        agent_type: opts.agentType,
+        status,
+        exit_code: exitResult.exit_code,
+        duration_ms: Date.now() - startedAt,
+        timestamp: new Date().toISOString()
+      });
+    }
   }).catch((err) => {
     endSession(session.id, 1, "failed");
     emitLifecycleEvent(sandbox.id, `Agent ${opts.agentType} failed: ${err.message}`);
+    if (opts.webhookUrl && webhookEvents.includes("error")) {
+      fireWebhook(opts.webhookUrl, {
+        event: "error",
+        session_id: session.id,
+        sandbox_id: sandbox.id,
+        agent_type: opts.agentType,
+        status: "failed",
+        duration_ms: Date.now() - startedAt,
+        timestamp: new Date().toISOString()
+      });
+    }
   });
   return session;
 }
@@ -5484,7 +5642,62 @@ async function stopAgent(sandboxId) {
   emitLifecycleEvent(sandbox.id, "Agent stopped by user");
 }
 
+// src/lib/images.ts
+var BUILTIN_IMAGES = {
+  node20: {
+    e2b: "e2bdev/base:latest",
+    description: "Node 20 + npm + pnpm + yarn",
+    setup_script: "curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs && npm install -g pnpm yarn"
+  },
+  "node20-claude": {
+    e2b: "e2bdev/base:latest",
+    description: "Node 20 + Claude Code CLI pre-installed",
+    setup_script: `curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs && npm install -g @anthropic-ai/claude-code && mkdir -p ~/.claude && echo '{"hasCompletedOnboarding":true,"hasTrustDialogAccepted":true,"hasAcknowledgedCostThreshold":true}' > ~/.claude.json`
+  },
+  "node20-codex": {
+    e2b: "e2bdev/base:latest",
+    description: "Node 20 + Codex CLI pre-installed",
+    setup_script: `curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs && npm install -g @openai/codex && mkdir -p ~/.codex && echo '[core]
+approvalMode = "full-auto"
+' > ~/.codex/config.toml`
+  },
+  python312: {
+    e2b: "e2bdev/base:latest",
+    description: "Python 3.12 + uv + pip",
+    setup_script: "apt-get update && apt-get install -y python3.12 python3-pip && pip3 install uv"
+  },
+  "python312-agents": {
+    e2b: "e2bdev/base:latest",
+    description: "Python 3.12 + uv + common AI libs",
+    setup_script: "apt-get update && apt-get install -y python3.12 python3-pip && pip3 install uv anthropic openai langchain"
+  },
+  fullstack: {
+    e2b: "e2bdev/base:latest",
+    description: "Node 20 + Python 3.12 + git + build tools",
+    setup_script: "apt-get update && apt-get install -y git build-essential python3.12 python3-pip && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && apt-get install -y nodejs && npm install -g pnpm"
+  }
+};
+function resolveImage(image) {
+  return BUILTIN_IMAGES[image]?.e2b ?? image;
+}
+function getBuiltinImageSetupScript(image) {
+  return BUILTIN_IMAGES[image]?.setup_script;
+}
+
 // src/mcp/index.ts
+var E2B_COST_PER_SECOND = 0.000014;
+var DAYTONA_COST_PER_SECOND = 0.00001;
+function estimateCost(providerName, startedAt) {
+  if (!startedAt)
+    return { compute_seconds: 0, cost_usd: 0 };
+  const seconds = (Date.now() - new Date(startedAt).getTime()) / 1000;
+  const rate = providerName === "daytona" ? DAYTONA_COST_PER_SECOND : E2B_COST_PER_SECOND;
+  return {
+    compute_seconds: Math.round(seconds),
+    cost_usd: Math.round(seconds * rate * 1e6) / 1e6
+  };
+}
+var exposedPorts = new Map;
 function ok(data) {
   return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -5518,7 +5731,16 @@ var TOOL_CATALOG = [
   { name: "list_templates", description: "List all sandbox templates" },
   { name: "get_template", description: "Get a sandbox template by ID" },
   { name: "delete_template", description: "Delete a sandbox template" },
-  { name: "get_sandbox_status", description: "Get running processes, disk usage and uptime in a sandbox" }
+  { name: "get_sandbox_status", description: "Get running processes, disk usage and uptime in a sandbox" },
+  { name: "snapshot_sandbox", description: "Capture sandbox filesystem state as a snapshot" },
+  { name: "list_snapshots", description: "List filesystem snapshots" },
+  { name: "delete_snapshot", description: "Delete a snapshot" },
+  { name: "expose_port", description: "Forward a sandbox port and get a public URL" },
+  { name: "list_exposed_ports", description: "List all forwarded ports for a sandbox" },
+  { name: "close_port", description: "Stop forwarding a sandbox port" },
+  { name: "get_network_log", description: "Get outbound network connections from a sandbox" },
+  { name: "watch_file", description: "Get new content from a file since a previous read (tail -f equivalent)" },
+  { name: "list_images", description: "List available pre-warmed sandbox image aliases" }
 ];
 var server = new McpServer({
   name: "sandboxes",
@@ -5532,7 +5754,11 @@ server.tool("create_sandbox", "Create a new sandbox", {
   env_vars: exports_external.record(exports_external.string()).optional().describe("Environment variables"),
   template_id: exports_external.string().optional().describe("Template ID to base this sandbox on"),
   on_timeout: exports_external.enum(["pause", "terminate"]).optional().describe("What to do on timeout: pause (saves state) or terminate"),
-  auto_resume: exports_external.boolean().optional().describe("Auto-resume paused sandbox on next connect")
+  auto_resume: exports_external.boolean().optional().describe("Auto-resume paused sandbox on next connect"),
+  snapshot_id: exports_external.string().optional().describe("Snapshot ID to restore from"),
+  network: exports_external.enum(["full", "restricted", "none"]).optional().describe("Network access policy for the sandbox"),
+  budget_limit_usd: exports_external.number().optional().describe("Auto-terminate sandbox if compute cost exceeds this USD amount"),
+  on_budget_exceeded: exports_external.enum(["terminate", "pause", "notify"]).optional().describe("Action when budget limit is reached (default: terminate)")
 }, async (params) => {
   try {
     const providerName = params.provider ?? getDefaultProvider();
@@ -5542,23 +5768,38 @@ server.tool("create_sandbox", "Create a new sandbox", {
       const tmpl = getTemplate(params.template_id);
       templateData = { image: tmpl.image ?? undefined, env_vars: tmpl.env_vars, setup_script: tmpl.setup_script };
     }
-    const image = params.image ?? templateData.image;
+    const rawImage = params.image ?? templateData.image;
+    const resolvedImage = rawImage ? resolveImage(rawImage) : rawImage;
+    const builtinSetupScript = rawImage ? getBuiltinImageSetupScript(rawImage) : undefined;
     const envVars = { ...templateData.env_vars, ...params.env_vars };
     const onTimeout = params.on_timeout ?? "terminate";
     const autoResume = params.auto_resume ?? false;
     const sandbox = createSandbox({
       provider: providerName,
-      image,
+      image: resolvedImage,
       timeout,
       name: params.name,
       env_vars: envVars,
       on_timeout: onTimeout,
       auto_resume: autoResume,
-      template_id: params.template_id
+      template_id: params.template_id,
+      config: { network: params.network ?? "full" },
+      budget_limit_usd: params.budget_limit_usd,
+      on_budget_exceeded: params.on_budget_exceeded
     });
     const provider = await getProvider(providerName);
+    if (params.snapshot_id) {
+      const snapshot = getSnapshot(params.snapshot_id);
+      await provider.resume(snapshot.provider_sandbox_id);
+      const updated2 = updateSandbox(sandbox.id, {
+        provider_sandbox_id: snapshot.provider_sandbox_id,
+        status: "running"
+      });
+      emitLifecycleEvent(sandbox.id, `Sandbox restored from snapshot ${snapshot.id}`);
+      return ok(updated2);
+    }
     const result = await provider.create({
-      image,
+      image: resolvedImage,
       timeout,
       envVars,
       onTimeout,
@@ -5566,7 +5807,8 @@ server.tool("create_sandbox", "Create a new sandbox", {
     });
     const updated = updateSandbox(sandbox.id, {
       provider_sandbox_id: result.id,
-      status: "running"
+      status: "running",
+      started_at: new Date().toISOString()
     });
     emitLifecycleEvent(sandbox.id, "sandbox created");
     if (templateData.setup_script && result.id) {
@@ -5574,6 +5816,11 @@ server.tool("create_sandbox", "Create a new sandbox", {
         await provider.exec(result.id, templateData.setup_script);
       } catch {}
     }
+    if (builtinSetupScript && result.id) {
+      try {
+        await provider.exec(result.id, builtinSetupScript);
+      } catch {}
+    }
     return ok(updated);
   } catch (e) {
     return err(e);
@@ -5583,7 +5830,9 @@ server.tool("get_sandbox", "Get sandbox details by ID", {
   id: exports_external.string().describe("Sandbox ID or partial ID")
 }, async (params) => {
   try {
-    return ok(getSandbox(params.id));
+    const sandbox = getSandbox(params.id);
+    const cost = estimateCost(sandbox.provider, sandbox.started_at);
+    return ok({ ...sandbox, ...cost });
   } catch (e) {
     return err(e);
   }
@@ -5593,10 +5842,11 @@ server.tool("list_sandboxes", "List sandboxes with filters", {
   provider: exports_external.string().optional().describe("Filter by provider")
 }, async (params) => {
   try {
-    return ok(listSandboxes({
+    const sandboxes = listSandboxes({
       status: params.status,
       provider: params.provider
-    }));
+    });
+    return ok(sandboxes.map((s) => ({ ...s, ...estimateCost(s.provider, s.started_at) })));
   } catch (e) {
     return err(e);
   }
@@ -5652,7 +5902,10 @@ server.tool("keep_alive", "Extend sandbox lifetime", {
 server.tool("exec_command", "Execute a command in a sandbox", {
   sandbox_id: exports_external.string().describe("Sandbox ID or partial ID"),
   command: exports_external.string().describe("Command to execute"),
-  background: exports_external.boolean().optional().describe("Run in background")
+  background: exports_external.boolean().optional().describe("Run in background"),
+  env_vars: exports_external.record(exports_external.string()).optional().describe("Per-call environment variables (merged with sandbox env_vars, not persisted)"),
+  stdin: exports_external.string().optional().describe("String to pipe as stdin to the command"),
+  tty: exports_external.boolean().optional().describe("Allocate a TTY for the session (best-effort)")
 }, async (params) => {
   try {
     const sandbox = getSandbox(params.sandbox_id);
@@ -5664,12 +5917,15 @@ server.tool("exec_command", "Execute a command in a sandbox", {
     });
     const collector = createStreamCollector(sandbox.id, session.id);
     const provider = await getProvider(sandbox.provider);
-    const env = Object.keys(sandbox.env_vars ?? {}).length > 0 ? sandbox.env_vars : undefined;
+    const callEnv = { ...sandbox.env_vars, ...params.env_vars };
+    const env = Object.keys(callEnv).length > 0 ? callEnv : undefined;
     if (params.background) {
       provider.exec(sandbox.provider_sandbox_id, params.command, {
         onStdout: collector.onStdout,
         onStderr: collector.onStderr,
-        env
+        env,
+        stdin: params.stdin,
+        tty: params.tty
       }).then((res) => {
         const r = res;
         endSession(session.id, r.exit_code ?? 0);
@@ -5681,7 +5937,9 @@ server.tool("exec_command", "Execute a command in a sandbox", {
     const result = await provider.exec(sandbox.provider_sandbox_id, params.command, {
       onStdout: collector.onStdout,
       onStderr: collector.onStderr,
-      env
+      env,
+      stdin: params.stdin,
+      tty: params.tty
     });
     const execResult = result;
     endSession(session.id, execResult.exit_code);
@@ -5697,15 +5955,22 @@ server.tool("exec_command", "Execute a command in a sandbox", {
 });
 server.tool("read_file", "Read a file from a sandbox", {
   sandbox_id: exports_external.string().describe("Sandbox ID or partial ID"),
-  path: exports_external.string().describe("File path")
+  path: exports_external.string().describe("File path"),
+  offset: exports_external.number().optional().describe("Line or byte offset to start reading from"),
+  limit: exports_external.number().optional().describe("Max lines or bytes to return"),
+  encoding: exports_external.enum(["utf8", "base64", "hex"]).optional().describe("Output encoding (default: utf8)")
 }, async (params) => {
   try {
     const sandbox = getSandbox(params.sandbox_id);
     if (!sandbox.provider_sandbox_id)
       throw new Error("Sandbox has no provider ID");
     const provider = await getProvider(sandbox.provider);
-    const content = await provider.readFile(sandbox.provider_sandbox_id, params.path);
-    return ok({ path: params.path, content });
+    const content = await provider.readFile(sandbox.provider_sandbox_id, params.path, {
+      encoding: params.encoding,
+      offset: params.offset,
+      limit: params.limit
+    });
+    return ok({ path: params.path, content, encoding: params.encoding ?? "utf8" });
   } catch (e) {
     return err(e);
   }
@@ -5728,14 +5993,19 @@ server.tool("write_file", "Write a file to a sandbox", {
 });
 server.tool("list_files", "List files in a sandbox directory", {
   sandbox_id: exports_external.string().describe("Sandbox ID or partial ID"),
-  path: exports_external.string().describe("Directory path")
+  path: exports_external.string().describe("Directory path"),
+  recursive: exports_external.boolean().optional().describe("List files recursively"),
+  glob: exports_external.string().optional().describe("Glob pattern to filter files")
 }, async (params) => {
   try {
     const sandbox = getSandbox(params.sandbox_id);
     if (!sandbox.provider_sandbox_id)
       throw new Error("Sandbox has no provider ID");
     const provider = await getProvider(sandbox.provider);
-    const files = await provider.listFiles(sandbox.provider_sandbox_id, params.path);
+    const files = await provider.listFiles(sandbox.provider_sandbox_id, params.path, {
+      recursive: params.recursive,
+      glob: params.glob
+    });
     return ok(files);
   } catch (e) {
     return err(e);
@@ -5815,14 +6085,20 @@ server.tool("run_agent", "Run an AI agent inside a sandbox", {
   agent_type: exports_external.enum(["claude", "codex", "gemini", "opencode", "pi", "custom"]).describe("Agent type"),
   prompt: exports_external.string().describe("Prompt for the agent"),
   agent_name: exports_external.string().optional().describe("Agent name"),
-  command: exports_external.string().optional().describe("Custom command (for 'custom' type)")
+  command: exports_external.string().optional().describe("Custom command (for 'custom' type)"),
+  env_vars: exports_external.record(exports_external.string()).optional().describe("Per-call environment variables (merged with sandbox env_vars, not persisted)"),
+  webhook_url: exports_external.string().optional().describe("URL to POST result to when agent finishes"),
+  webhook_events: exports_external.array(exports_external.enum(["start", "complete", "error"])).optional().describe("Which events to notify on (default: all)")
 }, async (params) => {
   try {
     const session = await runAgent(params.sandbox_id, {
       agentType: params.agent_type,
       prompt: params.prompt,
       agentName: params.agent_name,
-      command: params.command
+      command: params.command,
+      callEnvVars: params.env_vars,
+      webhookUrl: params.webhook_url,
+      webhookEvents: params.webhook_events
     });
     return ok({ session_id: session.id, status: session.status });
   } catch (e) {
@@ -5842,17 +6118,19 @@ server.tool("stop_agent", "Stop a running agent in a sandbox", {
 server.tool("get_agent_output", "Get output from an agent session", {
   sandbox_id: exports_external.string().describe("Sandbox ID"),
   session_id: exports_external.string().optional().describe("Session ID"),
-  limit: exports_external.number().optional().describe("Max events")
+  limit: exports_external.number().optional().describe("Max events"),
+  offset: exports_external.number().optional().describe("Skip first N events (for incremental polling)")
 }, async (params) => {
   try {
     const events = listEvents({
       sandbox_id: params.sandbox_id,
       session_id: params.session_id,
-      limit: params.limit || 100
+      limit: params.limit || 100,
+      offset: params.offset
     });
     const stdout = events.filter((e) => e.type === "stdout").map((e) => e.data).join("");
     const stderr = events.filter((e) => e.type === "stderr").map((e) => e.data).join("");
-    return ok({ stdout, stderr, event_count: events.length });
+    return ok({ stdout, stderr, event_count: events.length, next_offset: (params.offset ?? 0) + events.length });
   } catch (e) {
     return err(e);
   }
@@ -5963,5 +6241,142 @@ server.tool("get_sandbox_status", "Get running processes, disk usage and uptime
     return err(e);
   }
 });
+server.tool("snapshot_sandbox", "Capture sandbox filesystem state as a snapshot", {
+  id: exports_external.string().describe("Sandbox ID or partial ID"),
+  name: exports_external.string().optional().describe("Snapshot name")
+}, async (params) => {
+  try {
+    const sandbox = getSandbox(params.id);
+    if (!sandbox.provider_sandbox_id)
+      throw new Error("Sandbox has no provider ID");
+    const provider = await getProvider(sandbox.provider);
+    await provider.pause(sandbox.provider_sandbox_id);
+    updateSandbox(sandbox.id, { status: "paused" });
+    const snapshot = createSnapshot({
+      sandbox_id: sandbox.id,
+      provider_sandbox_id: sandbox.provider_sandbox_id,
+      provider: sandbox.provider,
+      name: params.name
+    });
+    emitLifecycleEvent(sandbox.id, `Snapshot created: ${snapshot.id}`);
+    return ok(snapshot);
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("list_snapshots", "List filesystem snapshots", {
+  sandbox_id: exports_external.string().optional().describe("Filter by sandbox ID")
+}, async (params) => {
+  try {
+    return ok(listSnapshots(params.sandbox_id));
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("delete_snapshot", "Delete a snapshot", {
+  id: exports_external.string().describe("Snapshot ID or partial ID")
+}, async (params) => {
+  try {
+    deleteSnapshot(params.id);
+    return ok({ deleted: params.id });
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("expose_port", "Forward a sandbox port and get a public URL", {
+  sandbox_id: exports_external.string().describe("Sandbox ID or partial ID"),
+  port: exports_external.number().describe("Port number to expose"),
+  protocol: exports_external.string().optional().describe("Protocol: http or ws (default: http)")
+}, async (params) => {
+  try {
+    const sandbox = getSandbox(params.sandbox_id);
+    if (!sandbox.provider_sandbox_id)
+      throw new Error("Sandbox has no provider ID");
+    const provider = await getProvider(sandbox.provider);
+    const url = await provider.getPublicUrl(sandbox.provider_sandbox_id, params.port, params.protocol);
+    if (!exposedPorts.has(sandbox.id))
+      exposedPorts.set(sandbox.id, new Map);
+    exposedPorts.get(sandbox.id).set(params.port, url);
+    return ok({ sandbox_id: sandbox.id, port: params.port, url });
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("list_exposed_ports", "List all forwarded ports for a sandbox", {
+  sandbox_id: exports_external.string().describe("Sandbox ID or partial ID")
+}, async (params) => {
+  try {
+    const sandbox = getSandbox(params.sandbox_id);
+    const ports = exposedPorts.get(sandbox.id) ?? new Map;
+    const result = Array.from(ports.entries()).map(([port, url]) => ({ port, url }));
+    return ok(result);
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("close_port", "Stop forwarding a sandbox port", {
+  sandbox_id: exports_external.string().describe("Sandbox ID or partial ID"),
+  port: exports_external.number().describe("Port number to close")
+}, async (params) => {
+  try {
+    const sandbox = getSandbox(params.sandbox_id);
+    exposedPorts.get(sandbox.id)?.delete(params.port);
+    return ok({ sandbox_id: sandbox.id, port: params.port, closed: true });
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("get_network_log", "Get outbound network connections from a sandbox", {
+  sandbox_id: exports_external.string().describe("Sandbox ID or partial ID")
+}, async (params) => {
+  try {
+    const sandbox = getSandbox(params.sandbox_id);
+    if (!sandbox.provider_sandbox_id)
+      throw new Error("Sandbox has no provider ID");
+    const provider = await getProvider(sandbox.provider);
+    const result = await provider.exec(sandbox.provider_sandbox_id, "ss -tnp 2>/dev/null || netstat -tnp 2>/dev/null || echo 'Network log not available'");
+    return ok({ sandbox_id: sandbox.id, connections: (result.stdout || "").trim() });
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("watch_file", "Get new content from a file since a previous read (tail -f equivalent)", {
+  sandbox_id: exports_external.string().describe("Sandbox ID or partial ID"),
+  path: exports_external.string().describe("File path to watch"),
+  offset: exports_external.number().optional().describe("Line offset to read from (use next_offset from previous call)"),
+  limit: exports_external.number().optional().describe("Max lines to return (default: 100)")
+}, async (params) => {
+  try {
+    const sandbox = getSandbox(params.sandbox_id);
+    if (!sandbox.provider_sandbox_id)
+      throw new Error("Sandbox has no provider ID");
+    const provider = await getProvider(sandbox.provider);
+    const content = await provider.readFile(sandbox.provider_sandbox_id, params.path, {
+      offset: params.offset,
+      limit: params.limit ?? 100
+    });
+    const lines = content.split(`
+`);
+    return ok({
+      path: params.path,
+      content,
+      lines_read: lines.length,
+      next_offset: (params.offset ?? 0) + lines.length
+    });
+  } catch (e) {
+    return err(e);
+  }
+});
+server.tool("list_images", "List available pre-warmed sandbox image aliases", {}, async () => {
+  try {
+    return ok(Object.entries(BUILTIN_IMAGES).map(([name, info]) => ({
+      name,
+      description: info.description,
+      has_setup_script: !!info.setup_script
+    })));
+  } catch (e) {
+    return err(e);
+  }
+});
 var transport = new StdioServerTransport;
 await server.connect(transport);