@madarco/agentbox 0.8.0 → 0.9.0

package/runtime/relay/bin.cjs

@@ -18044,6 +18044,23 @@ function isGhPrOp(value) {
   return GH_PR_OPS.includes(value);
 }
 var GH_PR_READ_ONLY_OPS = /* @__PURE__ */ new Set(["view", "list"]);
+function injectPrCreateHead(op, branch, args) {
+  if (op !== "create") return args;
+  if (!branch || branch === "HEAD") return args;
+  if (hasHeadArg(args)) return args;
+  return ["--head", branch, ...args];
+}
+function hasHeadArg(args) {
+  return args.some((a2) => a2 === "--head" || a2.startsWith("--head=") || a2.startsWith("-H"));
+}
+function prCreateNeedsHead(op, args) {
+  return op === "create" && !hasHeadArg(args);
+}
+var PR_CREATE_NO_HEAD_REFUSAL = {
+  exitCode: 65,
+  stdout: "",
+  stderr: "gh pr create: refusing to run without --head \u2014 could not resolve this box's branch, and falling back to the host repo's checked-out branch would open a PR for the wrong branch. Ensure the box branch is pushed, or pass --head <branch> explicitly.\n"
+};
 var GH_RPC_TIMEOUT_MS = 12e4;
 var GH_READY_CACHE_TTL_MS = 6e4;
 var ghReadyCache;
@@ -18383,36 +18400,31 @@ function isPromptAnswerBody(v) {
 async function resolveCloudBackend(name) {
   if (name === "daytona") {
     const pkg = "@agentbox/sandbox-daytona";
-    try {
-      const mod = await import(pkg);
-      return mod.daytonaBackend;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (/cannot find module|MODULE_NOT_FOUND/i.test(msg)) {
-        throw new Error(
-          `relay: cannot load '${pkg}' at runtime \u2014 install it alongside @agentbox/relay (the @madarco/agentbox CLI normally provides this dependency). Original: ${msg}`
-        );
-      }
-      throw err;
-    }
+    return loadCloudBackend(pkg, async () => (await import(pkg)).daytonaBackend);
   }
   if (name === "hetzner") {
     const pkg = "@agentbox/sandbox-hetzner";
-    try {
-      const mod = await import(pkg);
-      return mod.hetznerBackend;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (/cannot find module|MODULE_NOT_FOUND/i.test(msg)) {
-        throw new Error(
-          `relay: cannot load '${pkg}' at runtime \u2014 install it alongside @agentbox/relay (the @madarco/agentbox CLI normally provides this dependency). Original: ${msg}`
-        );
-      }
-      throw err;
-    }
+    return loadCloudBackend(pkg, async () => (await import(pkg)).hetznerBackend);
+  }
+  if (name === "vercel") {
+    const pkg = "@agentbox/sandbox-vercel";
+    return loadCloudBackend(pkg, async () => (await import(pkg)).vercelBackend);
   }
   throw new Error(`no host executor for cloud backend '${name}'`);
 }
+async function loadCloudBackend(pkg, load2) {
+  try {
+    return await load2();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/cannot find module|MODULE_NOT_FOUND/i.test(msg)) {
+      throw new Error(
+        `relay: cannot load '${pkg}' at runtime \u2014 install it alongside @agentbox/relay (the @madarco/agentbox CLI normally provides this dependency). Original: ${msg}`
+      );
+    }
+    throw err;
+  }
+}
 async function refreshCloudPreviewUrl(backendName, boxId, port) {
   try {
     const backend = await resolveCloudBackend(backendName);
@@ -18540,7 +18552,20 @@ async function runGhPrRpc(action, deps) {
       }
     }
   }
-  return runHostGh(["pr", op, ...args], lookup.workspacePath);
+  let finalArgs = args;
+  if (op === "create" && !args.some((a2) => a2 === "--head" || a2.startsWith("--head="))) {
+    const backend = await resolveCloudBackend(deps.backendName);
+    const handle = { sandboxId: lookup.cloudSandboxId };
+    const containerPath = params.path ?? "/workspace";
+    const branchProbe = await backend.exec(
+      handle,
+      `git -C ${shellQuote(containerPath)} rev-parse --abbrev-ref HEAD`
+    );
+    const branch = branchProbe.exitCode === 0 ? (branchProbe.stdout ?? "").trim() : "";
+    finalArgs = injectPrCreateHead(op, branch, args);
+  }
+  if (prCreateNeedsHead(op, finalArgs)) return PR_CREATE_NO_HEAD_REFUSAL;
+  return runHostGh(["pr", op, ...finalArgs], lookup.workspacePath);
 }
 async function runBrowserOpenMirror(action, deps) {
   const params = action.params ?? {};
@@ -19270,7 +19295,13 @@ function createRelayServer(opts) {
     const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "relay"}`);
     const route = `${req.method ?? "GET"} ${url.pathname}`;
     if (route === "GET /healthz") {
-      send(res, 200, { ok: true, boxes: registry.size(), events: events.size() });
+      send(res, 200, {
+        ok: true,
+        boxes: registry.size(),
+        events: events.size(),
+        pid: process.pid,
+        cliEntry: Boolean(process.env.AGENTBOX_CLI_ENTRY)
+      });
       return;
     }
     if (url.pathname.startsWith("/bridge/")) {
@@ -19928,7 +19959,9 @@ async function handleGhPrRpc(op, reg, params, prompts, subscribers, hostInitiate
       return { exitCode: 10, stdout: "", stderr: "denied by user\n" };
     }
   }
-  return runHostGh(["pr", op, ...args], worktree.hostMainRepo);
+  const finalArgs = injectPrCreateHead(op, worktree.branch, args);
+  if (prCreateNeedsHead(op, finalArgs)) return PR_CREATE_NO_HEAD_REFUSAL;
+  return runHostGh(["pr", op, ...finalArgs], worktree.hostMainRepo);
 }
 async function handleCpRpc(reg, method, params) {
   const entry = process.env.AGENTBOX_CLI_ENTRY;
@@ -20056,6 +20089,7 @@ var BUILT_IN_DEFAULTS = {
     defaultCheckpointDocker: "",
     defaultCheckpointDaytona: "",
     defaultCheckpointHetzner: "",
+    defaultCheckpointVercel: "",
     withPlaywright: false,
     withEnv: false,
     vnc: true,
@@ -20068,7 +20102,10 @@ var BUILT_IN_DEFAULTS = {
     cpus: 0,
     pidsLimit: 0,
     disk: "",
-    bundleDepth: void 0
+    bundleDepth: void 0,
+    vercelVcpus: 2,
+    vercelTimeoutMs: 27e5,
+    vercelNetworkPolicy: ""
   },
   checkpoint: {
     maxLayers: 3
@@ -20119,7 +20156,12 @@ var BUILT_IN_DEFAULTS = {
   },
   queue: {
     enabled: true,
-    maxConcurrent: 5
+    maxConcurrent: 5,
+    maxWorking: 0,
+    idleGraceSeconds: 15
+  },
+  cloud: {
+    useCurrentBranch: false
   },
   maintenance: {
     pruneProjectConfigs: true,
@@ -20130,8 +20172,8 @@ var KEY_REGISTRY = [
   {
     key: "box.provider",
     type: "enum",
-    enumValues: ["docker", "daytona", "hetzner"],
-    description: "Sandbox backend new boxes are created on: local Docker containers, Daytona Cloud sandboxes, or Hetzner Cloud VPSes."
+    enumValues: ["docker", "daytona", "hetzner", "vercel"],
+    description: "Sandbox backend new boxes are created on: local Docker containers, Daytona Cloud sandboxes, Hetzner Cloud VPSes, or Vercel Sandboxes."
   },
   {
     key: "box.hostSnapshot",
@@ -20161,6 +20203,12 @@ var KEY_REGISTRY = [
     description: "Per-provider override of `box.defaultCheckpoint` for hetzner. Wins over the global when set; set via `agentbox checkpoint set-default --provider hetzner`.",
     advanced: true
   },
+  {
+    key: "box.defaultCheckpointVercel",
+    type: "string",
+    description: "Per-provider override of `box.defaultCheckpoint` for vercel. Wins over the global when set; set via `agentbox checkpoint set-default --provider vercel`.",
+    advanced: true
+  },
   {
     key: "checkpoint.maxLayers",
     type: "int",
@@ -20234,6 +20282,21 @@ var KEY_REGISTRY = [
     type: "int",
     description: "Cap git bundle history shipped to cloud sandboxes (daytona, hetzner). 0 = full history. Unset = adaptive default (last 200 commits; re-bundle at 100 if the bundle exceeds 20 MB). Ignored for docker (which bind-mounts .git/)."
   },
+  {
+    key: "box.vercelVcpus",
+    type: "int",
+    description: "vCPUs for new --provider vercel boxes (Vercel couples RAM at 2048 MB/vCPU). Default 2. Vercel only accepts specific counts (e.g. 1, 2, 4, 8) \u2014 an unsupported value fails create with a 400. Vercel-only; ignored by other providers."
+  },
+  {
+    key: "box.vercelTimeoutMs",
+    type: "int",
+    description: "Max session length (ms) for new --provider vercel boxes before the VM auto-snapshots; persistent mode auto-resumes on the next call. Default 2700000 (45 min, the Hobby ceiling). Vercel-only."
+  },
+  {
+    key: "box.vercelNetworkPolicy",
+    type: "string",
+    description: "Egress lock for new --provider vercel boxes: 'allow-all' (default, unset), 'deny-all', or a comma-separated domain allowlist (e.g. 'github.com,*.npmjs.org') that denies everything else. Vercel-only; ignored by other providers."
+  },
   {
     key: "claude.sessionName",
     type: "string",
@@ -20351,6 +20414,21 @@ var KEY_REGISTRY = [
     type: "int",
     description: "Max number of simultaneously-running boxes (across providers) before background `-i` jobs queue up instead of starting immediately. Per-invocation override: `--max-running <n>`."
   },
+  {
+    key: "queue.maxWorking",
+    type: "int",
+    description: "Max agents actively working/thinking (quota-consuming) at once before background `-i` jobs queue. 0 = disabled (use the queue.maxConcurrent running-box gate). Counts all boxes, foreground + queued. Per-invocation override: `--max-working <n>`."
+  },
+  {
+    key: "queue.idleGraceSeconds",
+    type: "int",
+    description: "Seconds an agent must stay non-working before it frees its working slot (debounce against brief idle flaps between turns). Only used when queue.maxWorking > 0."
+  },
+  {
+    key: "cloud.useCurrentBranch",
+    type: "bool",
+    description: "On cloud providers (daytona/hetzner), start new boxes on the host's current branch instead of forking a new agentbox/<box-name> branch. Overridden by an explicit --use-branch / --from-branch."
+  },
   {
     key: "maintenance.pruneProjectConfigs",
     type: "bool",
@@ -20701,7 +20779,9 @@ async function loadQueueConfig() {
   const q = global3.queue ?? {};
   return {
     enabled: q.enabled ?? d.enabled,
-    maxConcurrent: q.maxConcurrent ?? d.maxConcurrent
+    maxConcurrent: q.maxConcurrent ?? d.maxConcurrent,
+    maxWorking: q.maxWorking ?? d.maxWorking,
+    idleGraceMs: (q.idleGraceSeconds ?? d.idleGraceSeconds) * 1e3
   };
 }
 async function writeJob(job) {
@@ -20747,6 +20827,70 @@ function selectNextRunnable(jobs, runningCount) {
   }
   return null;
 }
+var WORKING_AGENT_STATES = [
+  "working",
+  "idle",
+  "waiting",
+  "end-plan",
+  "question",
+  "compacting",
+  "error",
+  "unknown"
+];
+function isWorkingAgentState(v) {
+  return typeof v === "string" && WORKING_AGENT_STATES.includes(v);
+}
+var STARTUP_GRACE_MS = 9e4;
+function occupiesWorkingSlot(e, idleGraceMs) {
+  if (e.agentState === "working" || e.agentState === "compacting") return true;
+  if ((e.agentState === null || e.agentState === "unknown") && e.sinceCreateMs !== null && e.sinceCreateMs < STARTUP_GRACE_MS) {
+    return true;
+  }
+  if ((e.agentState === "idle" || e.agentState === "waiting" || e.agentState === "end-plan" || e.agentState === "question") && e.sinceUpdateMs !== null && e.sinceUpdateMs < idleGraceMs) {
+    return true;
+  }
+  return false;
+}
+function countWorkingSlots(entries, idleGraceMs) {
+  return entries.reduce((n2, e) => occupiesWorkingSlot(e, idleGraceMs) ? n2 + 1 : n2, 0);
+}
+function selectNextRunnableByWorking(jobs, workingCount, globalMaxWorking) {
+  for (const j of jobs) {
+    if (j.status !== "queued") continue;
+    const ceil = typeof j.maxWorking === "number" && j.maxWorking > 0 ? j.maxWorking : globalMaxWorking;
+    if (workingCount < ceil) return j;
+  }
+  return null;
+}
+function readActiveAgent(snap) {
+  if (!snap || typeof snap !== "object") return { state: null, updatedAt: null };
+  const candidates = [];
+  for (const key of ["claude", "codex", "opencode"]) {
+    const sub = snap[key];
+    if (!sub || typeof sub !== "object") continue;
+    const o2 = sub;
+    if (!isWorkingAgentState(o2.state)) continue;
+    candidates.push({
+      state: o2.state,
+      updatedAt: typeof o2.updatedAt === "string" ? o2.updatedAt : null
+    });
+  }
+  if (candidates.length === 0) return { state: null, updatedAt: null };
+  const active = candidates.find((c3) => c3.state === "working" || c3.state === "compacting");
+  if (active) return active;
+  candidates.sort((a2, b) => parseTime(b.updatedAt) - parseTime(a2.updatedAt));
+  return candidates[0];
+}
+function parseTime(iso) {
+  if (!iso) return 0;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? 0 : t;
+}
+function msSince2(iso) {
+  if (!iso) return null;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? null : Date.now() - t;
+}
 var DEFAULT_INTERVAL_MS2 = 2e3;
 function startQueueLoop(deps) {
   const loadConfig = deps.loadConfig ?? loadQueueConfig;
@@ -20754,8 +20898,10 @@ function startQueueLoop(deps) {
   const spawnWorker = deps.spawnWorker ?? defaultSpawnWorker;
   const intervalMs = deps.intervalMs ?? DEFAULT_INTERVAL_MS2;
   const { log, onStatusChange } = deps;
+  const countWorking = deps.countWorking ?? (deps.registry && deps.statusStore ? (idleGraceMs) => defaultCountWorkingBoxes(deps.registry, deps.statusStore, idleGraceMs) : null);
   let ticking = false;
   let stopped = false;
+  let warnedNoWorkingDeps = false;
   let inFlight = recoverOrphanedWorkers(log, onStatusChange).catch((err) => {
     log(`queue: orphan recovery failed: ${err instanceof Error ? err.message : String(err)}`);
   });
@@ -20768,10 +20914,26 @@ function startQueueLoop(deps) {
       const jobs = await loadQueue();
       const hasQueued = jobs.some((j) => j.status === "queued");
       if (!hasQueued) return;
+      let gateByWorking = cfg.maxWorking > 0;
+      if (gateByWorking && !countWorking) {
+        gateByWorking = false;
+        if (!warnedNoWorkingDeps) {
+          warnedNoWorkingDeps = true;
+          log("queue: maxWorking set but registry/statusStore not wired; using running-box gate");
+        }
+      }
       while (!stopped) {
-        const running = await countRunning();
-        const fresh = await loadQueue();
-        const next = selectNextRunnable(fresh, running);
+        let occupancy;
+        let next;
+        if (gateByWorking && countWorking) {
+          occupancy = await countWorking(cfg.idleGraceMs);
+          const fresh = await loadQueue();
+          next = selectNextRunnableByWorking(fresh, occupancy, cfg.maxWorking);
+        } else {
+          occupancy = await countRunning();
+          const fresh = await loadQueue();
+          next = selectNextRunnable(fresh, occupancy);
+        }
         if (!next) return;
         const current = await readJob(next.id);
         if (!current || current.status !== "queued") continue;
@@ -20788,8 +20950,9 @@ function startQueueLoop(deps) {
             const withPid = { ...updated, pid };
             await writeJob(withPid);
             onStatusChange?.(withPid);
+            const ceil = gateByWorking ? typeof updated.maxWorking === "number" && updated.maxWorking > 0 ? updated.maxWorking : cfg.maxWorking : updated.maxConcurrent;
             log(
-              `queue: started job ${updated.id} (${updated.agent}) as pid ${String(pid)}; running ${String(running + 1)}/${String(updated.maxConcurrent)}`
+              `queue: started job ${updated.id} (${updated.agent}) as pid ${String(pid)}; ${gateByWorking ? "working" : "running"} ${String(occupancy + 1)}/${String(ceil)}`
             );
           } else {
             log(`queue: started job ${updated.id} (${updated.agent}); pid unknown`);
@@ -20858,6 +21021,33 @@ function processAlive(pid) {
     return false;
   }
 }
+async function defaultCountWorkingBoxes(registry, statusStore, idleGraceMs) {
+  const boxes = registry.list();
+  const registeredIds = new Set(boxes.map((b) => b.boxId));
+  const entries = boxes.map((b) => {
+    const active = readActiveAgent(statusStore.get(b.boxId));
+    return {
+      key: b.boxId,
+      agentState: active.state,
+      sinceUpdateMs: msSince2(active.updatedAt),
+      sinceCreateMs: msSince2(b.createdAt)
+    };
+  });
+  let count2 = countWorkingSlots(entries, idleGraceMs);
+  let jobs;
+  try {
+    jobs = await loadQueue();
+  } catch {
+    return count2;
+  }
+  for (const j of jobs) {
+    if (j.status !== "running") continue;
+    if (j.boxId && registeredIds.has(j.boxId)) continue;
+    if (typeof j.pid === "number" && !processAlive(j.pid)) continue;
+    count2 += 1;
+  }
+  return count2;
+}
 var RUNNING_COUNT_CACHE_MS = 3e3;
 var runningCountCache = null;
 async function defaultCountRunningBoxes() {
@@ -20974,7 +21164,9 @@ program2.command("serve").description("Run the HTTP relay in the foreground").op
   });
   const queue = startQueueLoop({
     log: (line) => process.stdout.write(`agentbox-relay: ${line}
-`)
+`),
+    registry: handle.registry,
+    statusStore: handle.statusStore
   });
   handle.setQueuePoke(() => {
     queue.poke?.();

package/runtime/vercel/agentbox-checkpoint-cleanup

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Pre-`docker commit` cleanup: strip ephemeral / disposable state so the
+# captured checkpoint image is closer to "warm project state, nothing else".
+#
+# Invoked by the host via `docker exec --user root <container>
+# /usr/local/bin/agentbox-checkpoint-cleanup` right before
+# `docker commit`. Best-effort: every step is allowed to fail (a checkpoint
+# capture should never block on cleanup hiccups).
+#
+# What we DELIBERATELY keep:
+#   - /workspace                  the actual point of the checkpoint
+#   - /home/vscode/.npm           warm npm cache (next install is fast)
+#   - /home/vscode/.cache         pnpm/yarn/Cargo/etc. caches
+#   - /var/lib/docker             in-box dockerd's data root
+#   - /home/vscode/.claude        the named volume is bind-mounted; image
+#                                 layer never sees it anyway
+set +e
+
+# apt: drop downloaded .deb cache and the package index. The index is ~50MB
+# and gets refreshed on the next `apt-get update`; the .deb cache is reusable
+# only if we don't change versions, which we usually do.
+apt-get clean 2>/dev/null
+rm -rf /var/lib/apt/lists/* 2>/dev/null
+
+# Throwaway scratch dirs. Preserve /tmp/claude-* — that is the live in-box
+# Claude Code session's working tree (its per-task stdout/stderr files). The
+# agent that triggered this checkpoint *is* that session; deleting its task
+# output mid-run makes its harness see ENOENT, treat the command as failed,
+# and retry the checkpoint (observed: 5 duplicate auto-named checkpoints).
+# Stale claude-* dirs baked into the image are tiny and Claude Code prunes
+# them itself on the next session start.
+find /tmp /var/tmp -mindepth 1 -maxdepth 1 ! -name 'claude-*' -exec rm -rf {} + 2>/dev/null
+
+# Logs: truncate (don't delete) so the original file modes / ownerships stay
+# intact for the next run. Targets common rotated archives too.
+find /var/log -type f \( -name '*.log' -o -name '*.gz' -o -name '*.1' \) \
+  -exec truncate -s0 {} + 2>/dev/null
+find /var/log/agentbox -type f -exec truncate -s0 {} + 2>/dev/null
+
+# Bash history (root + vscode). Re-assert vscode ownership: `: >` run as root
+# (re)creates the file root-owned 0644 when it didn't exist, which the uid-1000
+# vscode user cannot append to, silently dropping all shell history.
+: > /root/.bash_history 2>/dev/null
+: > /home/vscode/.bash_history 2>/dev/null
+chown vscode:vscode /home/vscode/.bash_history 2>/dev/null
+chmod 600 /home/vscode/.bash_history 2>/dev/null
+
+# Anthropic's installer writes a transient marker; redundant once the binary
+# is in place. Safe to wipe.
+rm -rf /home/vscode/.claude-installer 2>/dev/null
+
+exit 0

package/runtime/vercel/agentbox-codex-hooks.json

@@ -0,0 +1,68 @@
+{
+  "$comment": "Codex 0.134.0 expects `~/.codex/hooks.json` to be `{ hooks: { Event: [...] } }` (matching the `HooksFile` Rust struct), NOT a top-level event map. The `hooks` feature flag must also be enabled (`codex --enable hooks`) and hook trust must be either persisted via the in-TUI dialog or bypassed at launch (`--dangerously-bypass-hook-trust`). startCodexSession() does both. In practice the hook firing on the JSON-config path is still unreliable in 0.134.0 (TUI mode skips them on at least some startup paths) — the real mechanism that lights up state in production is the tmux-pane scraper in packages/ctl/src/codex-scraper.ts. These hooks remain as a defense-in-depth seed so any future codex build that fixes the firing also lights up state without further work.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state waiting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state compacting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ]
+  }
+}

package/runtime/vercel/agentbox-open

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Routes in-box URL opens to `agentbox-ctl open`, which opens the link in the
+# box's own Chromium (agent-browser, visible via `agentbox screen`) and asks
+# the host user — in the footer/dashboard — whether to also open it on the
+# host. This script is installed at /usr/local/bin (earlier in PATH than
+# xdg-utils' /usr/bin/xdg-open, which it is also symlinked over) and is the
+# box's $BROWSER, so `xdg-open`, Claude Code's OAuth flow, `gh`,
+# `git web--browse`, python's webbrowser, etc. all land here.
+#
+# Only http(s) URLs are routed. Anything else (a file path, another scheme)
+# falls through to the real xdg-open, which resolves it locally in the box.
+
+set -uo pipefail
+
+target="${1:-}"
+
+case "$target" in
+  http://* | https://*)
+    exec agentbox-ctl open "$target"
+    ;;
+  *)
+    if [[ -x /usr/bin/xdg-open ]]; then
+      exec /usr/bin/xdg-open "$@"
+    fi
+    echo "agentbox-open: not an http(s) URL: $target" >&2
+    exit 1
+    ;;
+esac