@madarco/agentbox 0.7.0 → 0.9.0

package/runtime/vercel/scripts/provision.sh

@@ -0,0 +1,274 @@
+#!/usr/bin/env bash
+# AgentBox Vercel base-snapshot installer.
+#
+# Idempotent installer run once on a fresh Vercel Sandbox (Amazon Linux 2023,
+# node24 runtime) during `agentbox prepare --provider vercel`. After it
+# completes we `sandbox.snapshot()` the microVM — that snapshot is what every
+# per-box create boots from.
+#
+# Differences from the hetzner installer (packages/sandbox-hetzner/scripts/
+# install-box.sh), which this mirrors:
+#   - dnf, not apt (Amazon Linux 2023).
+#   - NO docker / dockerd / iptables — Vercel Sandbox blocks the namespace
+#     syscalls a container runtime needs, so DinD is impossible here.
+#   - The `vscode` user is created without forcing uid 1000 (the Vercel default
+#     user may already hold it; there are no bind mounts so the exact uid is
+#     irrelevant — only ownership of /workspace + /home/vscode matters).
+#
+# Required inputs (uploaded to /tmp before this runs):
+#   /tmp/agentbox-ctl                  -- prebuilt @agentbox/ctl bundle (cjs)
+#   /tmp/agentbox-vnc-start            -- VNC startup helper
+#   /tmp/agentbox-checkpoint-cleanup   -- pre-snapshot cleanup helper
+#   /tmp/agentbox-open                 -- in-box xdg-open shim
+#   /tmp/agentbox-gh-shim              -- in-box `gh` shim (routes to host gh)
+#   /tmp/agentbox-git-shim             -- in-box `git` shim (routes via relay)
+#   /tmp/agentbox-custom-CLAUDE.md     -- /etc/claude-code/CLAUDE.md content
+#   /tmp/agentbox-managed-settings.json -- /etc/claude-code/managed-settings.json
+#   /tmp/agentbox-codex-hooks.json     -- /usr/local/share/agentbox/codex-hooks.json
+#   /tmp/agentbox-setup-skill.md       -- /usr/local/share/agentbox/setup-guide.md
+#
+# Output: noisy progress to stdout (streamed into ~/.agentbox/logs/prepare.log).
+# Each major step prints `>>> BEGIN <step>` / `<<< END <step>`.
+
+set -euo pipefail
+
+step() { printf '\n>>> BEGIN %s\n' "$1"; }
+done_() { printf '<<< END %s\n' "$1"; }
+
+if [ "$(id -u)" -ne 0 ]; then
+  echo "provision.sh: must run as root (got uid $(id -u))" >&2
+  exit 64
+fi
+
+step "dnf base packages"
+# NOTE: do NOT request `curl` — AL2023 ships `curl-minimal` which provides the
+# `curl` binary, and asking for full `curl` conflicts with it and aborts the
+# whole (atomic) dnf transaction. `--allowerasing` lets dnf resolve any other
+# such conflict by swapping rather than failing. No `| tail || true` here: that
+# masks dnf's real exit code and lets the script march on with nothing
+# installed (the bug that broke the first bake).
+dnf install -y -q --allowerasing \
+  ca-certificates \
+  git \
+  tar \
+  gzip \
+  which \
+  shadow-utils \
+  sudo \
+  python3 \
+  python3-pip \
+  tmux \
+  vim \
+  libcap \
+  rsync
+done_ "dnf base packages"
+
+step "node 24 sanity"
+# Vercel's node24 runtime already ships node; just confirm it's on PATH.
+if ! command -v node >/dev/null 2>&1; then
+  echo "provision.sh: node not found on the node24 runtime — unexpected" >&2
+  exit 65
+fi
+node --version
+done_ "node 24 sanity"
+
+step "vscode user + sudoers"
+# No forced uid: the Vercel default user (`vercel-sandbox`) may already hold
+# 1000, and there are no bind mounts so uid-parity with the docker provider
+# doesn't matter. Ownership + passwordless sudo is what counts.
+if ! id vscode >/dev/null 2>&1; then
+  useradd -m -s /bin/bash vscode
+fi
+install -d -m 0755 -o vscode -g vscode /home/vscode
+echo 'vscode ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/90-agentbox-vscode
+chmod 0440 /etc/sudoers.d/90-agentbox-vscode
+# Vercel's AL2023 base ships /etc/sudoers WITHOUT an includedir for
+# /etc/sudoers.d (and with non-0440 perms), so the drop-in above is silently
+# ignored and `sudo -n` as vscode fails with "a password is required" — which
+# breaks the workspace seed, ctl-launch, and carry (all run as vscode and lean
+# on passwordless sudo). Wire the include in and normalise perms so the rule
+# actually loads, then fail loud if the result doesn't parse.
+if ! grep -qE '^[[:space:]]*[@#]includedir[[:space:]]+/etc/sudoers\.d' /etc/sudoers; then
+  printf '\n@includedir /etc/sudoers.d\n' >> /etc/sudoers
+fi
+chmod 0440 /etc/sudoers
+visudo -cf /etc/sudoers >/dev/null
+done_ "vscode user + sudoers"
+
+step "agentbox base dirs + /workspace ownership"
+mkdir -p /workspace /run/agentbox /var/log/agentbox /etc/agentbox /etc/claude-code \
+         /usr/local/share/agentbox
+chmod 755 /workspace
+chown vscode:vscode /workspace /run/agentbox /var/log/agentbox
+done_ "agentbox base dirs + /workspace ownership"
+
+step "node setcap (bind <1024 without root)"
+# The cloud WebProxy binds port 80; grant node the capability so it needn't run
+# as root. Best-effort — if setcap is unavailable the WebProxy can still be
+# launched via sudo.
+NODE_BIN="$(readlink -f "$(command -v node)")"
+setcap cap_net_bind_service=+ep "$NODE_BIN" || echo "provision.sh: setcap failed (continuing)"
+done_ "node setcap (bind <1024 without root)"
+
+step "corepack (pnpm + yarn shims)"
+npm install -g corepack@latest 2>&1 | tail -2 || true
+corepack enable pnpm yarn 2>/dev/null || true
+sudo -u vscode -H mkdir -p /home/vscode/.cache/node/corepack
+done_ "corepack (pnpm + yarn shims)"
+
+step "git system-wide safe.directory"
+# The Vercel node24 runtime's git is built with prefix /opt/git, so its system
+# config is /opt/git/etc/gitconfig and the parent dir may not exist — without
+# it `git config --system` fails with "could not lock config file" (exit 255).
+# Create the dir, then set it system-wide AND for the vscode user so workspace
+# git ops never trip "dubious ownership". All best-effort — a git-config quirk
+# must never abort the bake.
+mkdir -p /opt/git/etc 2>/dev/null || true
+git config --system --add safe.directory '*' 2>/dev/null || true
+sudo -u vscode -H git config --global --add safe.directory '*' 2>/dev/null || true
+done_ "git system-wide safe.directory"
+
+step "agentbox-ctl install"
+install -m 0755 /tmp/agentbox-ctl /usr/local/bin/agentbox-ctl
+done_ "agentbox-ctl install"
+
+step "baked helper scripts (vnc / cleanup / xdg-open)"
+install -m 0755 /tmp/agentbox-vnc-start          /usr/local/bin/agentbox-vnc-start
+install -m 0755 /tmp/agentbox-checkpoint-cleanup /usr/local/bin/agentbox-checkpoint-cleanup
+install -m 0755 /tmp/agentbox-open               /usr/local/bin/agentbox-open
+ln -sf /usr/local/bin/agentbox-open /usr/local/bin/xdg-open
+# NOTE: the gh + git shims are installed LAST (see "relay shims" near the end).
+# Installing them here would put the relay-routing `git` on PATH ahead of
+# /usr/bin/git and route provision.sh's own noVNC `git clone` through a relay
+# that doesn't exist during the bake.
+done_ "baked helper scripts (vnc / cleanup / xdg-open)"
+
+step "baked config files (claude / codex / setup guide / tmux.conf)"
+install -m 0644 /tmp/agentbox-custom-CLAUDE.md      /etc/claude-code/CLAUDE.md
+install -m 0644 /tmp/agentbox-managed-settings.json /etc/claude-code/managed-settings.json
+install -m 0644 /tmp/agentbox-codex-hooks.json      /usr/local/share/agentbox/codex-hooks.json
+install -m 0644 /tmp/agentbox-setup-skill.md        /usr/local/share/agentbox/setup-guide.md
+
+cat > /etc/tmux.conf <<'TMUX'
+set -g default-terminal "tmux-256color"
+set -as terminal-overrides ",*:Tc"
+set -as terminal-overrides ",*:RGB"
+set -as terminal-features ",*:hyperlinks"
+set -as terminal-features ",*:RGB"
+set -g allow-passthrough on
+set -g set-clipboard on
+set -g extended-keys on
+set -as terminal-features ",*:extkeys"
+set -g mouse on
+bind -T copy-mode    WheelUpPane   send -N2 -X scroll-up
+bind -T copy-mode    WheelDownPane send -N2 -X scroll-down
+bind -T copy-mode-vi WheelUpPane   send -N2 -X scroll-up
+bind -T copy-mode-vi WheelDownPane send -N2 -X scroll-down
+set -g history-limit 50000
+set -g escape-time 0
+TMUX
+done_ "baked config files (claude / codex / setup guide / tmux.conf)"
+
+step "credential pivot symlinks (vscode home)"
+sudo -u vscode -H mkdir -p \
+  /home/vscode/.claude \
+  /home/vscode/.claude/skills/agentbox-setup \
+  /home/vscode/.codex \
+  /home/vscode/.local/share/opencode \
+  /home/vscode/.agentbox-creds/claude \
+  /home/vscode/.agentbox-creds/codex \
+  /home/vscode/.agentbox-creds/opencode
+sudo -u vscode -H ln -sf /home/vscode/.agentbox-creds/claude/.credentials.json \
+  /home/vscode/.claude/.credentials.json
+sudo -u vscode -H ln -sf /home/vscode/.agentbox-creds/codex/auth.json \
+  /home/vscode/.codex/auth.json
+sudo -u vscode -H ln -sf /home/vscode/.agentbox-creds/opencode/auth.json \
+  /home/vscode/.local/share/opencode/auth.json
+sudo -u vscode -H ln -sf /home/vscode/.claude/_claude.json /home/vscode/.claude.json
+sudo -u vscode -H cp /usr/local/share/agentbox/setup-guide.md \
+  /home/vscode/.claude/skills/agentbox-setup/SKILL.md
+done_ "credential pivot symlinks (vscode home)"
+
+step "login-shell shim (/etc/profile.d/agentbox.sh)"
+cat > /etc/profile.d/agentbox.sh <<'PROFILE'
+# Auto-loaded by login shells; box.env is written at create time.
+if [ -r /etc/agentbox/box.env ]; then
+  set -a
+  . /etc/agentbox/box.env
+  set +a
+fi
+case ":$PATH:" in
+  *:/home/vscode/.local/bin:*) : ;;
+  *) PATH=/home/vscode/.local/bin:$PATH ;;
+esac
+# Force /usr/local/bin to win PATH. Vercel's AL2023 base prepends /opt/git/bin
+# AHEAD of /usr/local/bin, so the relay-routing shims at /usr/local/bin/{git,gh}
+# are otherwise shadowed by the real binaries and agent-typed `git push` /
+# `gh ...` bypass the host relay (backlog #19). A plain `case` prepend doesn't
+# help — /usr/local/bin is already on PATH, just not first — so strip any
+# existing occurrence and re-prepend.
+PATH=/usr/local/bin:$(printf '%s' "$PATH" | sed -e 's#:/usr/local/bin:#:#g' -e 's#^/usr/local/bin:##' -e 's#:/usr/local/bin$##' -e 's#^/usr/local/bin$##')
+export PATH
+export COLORTERM=${COLORTERM:-truecolor}
+export DISABLE_AUTOUPDATER=${DISABLE_AUTOUPDATER:-1}
+export DISPLAY=${DISPLAY:-:1}
+export AGENT_BROWSER_EXECUTABLE_PATH=${AGENT_BROWSER_EXECUTABLE_PATH:-/usr/local/bin/chromium}
+export BROWSER=${BROWSER:-/usr/local/bin/agentbox-open}
+PROFILE
+chmod 0644 /etc/profile.d/agentbox.sh
+done_ "login-shell shim (/etc/profile.d/agentbox.sh)"
+
+step "VNC stack (TigerVNC + websockify + noVNC)"
+# Best-effort: VNC is a convenience (agentbox screen). A package that isn't in
+# the AL2023 repos shouldn't fail the whole bake — the VNC daemon launch is
+# already best-effort on the create path.
+dnf install -y -q --allowerasing tigervnc-server xterm 2>&1 | tail -3 || \
+  echo "provision.sh: tigervnc-server install failed (VNC may be unavailable)"
+pip3 install --quiet websockify 2>&1 | tail -2 || \
+  echo "provision.sh: websockify install failed (VNC may be unavailable)"
+# noVNC static assets — clone shallow into a stable path the vnc-start script
+# can serve.
+if [ ! -d /usr/local/share/novnc ]; then
+  git clone --depth 1 https://github.com/novnc/noVNC /usr/local/share/novnc 2>&1 | tail -2 || \
+    echo "provision.sh: noVNC clone failed (VNC may be unavailable)"
+fi
+sudo -u vscode -H mkdir -p /home/vscode/.vnc
+done_ "VNC stack (TigerVNC + websockify + noVNC)"
+
+step "agent CLIs (codex + opencode + agent-browser, global npm)"
+npm install -g @openai/codex opencode-ai agent-browser 2>&1 | tail -3 || \
+  echo "provision.sh: one or more agent npm installs failed (continuing)"
+done_ "agent CLIs (codex + opencode + agent-browser, global npm)"
+
+step "Claude Code (native installer, run as vscode)"
+# Anthropic's canonical installer drops `claude` at /home/vscode/.local/bin/.
+sudo -u vscode -H bash -lc 'curl -fsSL https://claude.ai/install.sh | bash -s stable'
+done_ "Claude Code (native installer, run as vscode)"
+
+step "dnf cleanup"
+dnf clean all 2>/dev/null || true
+done_ "dnf cleanup"
+
+# Relay-routing shims, installed LAST — after every git/gh use in this script
+# (the noVNC `git clone` and any npm/installer step). At RUNTIME agent calls to
+# `gh ...` / `git push|pull|fetch|clone` must route through the host relay; the
+# login-shell shim above forces /usr/local/bin ahead of Vercel's /opt/git/bin so
+# these win (a plain install location is NOT enough on AL2023 — see #19). During
+# the bake there is no relay, so they must not shadow the real binaries until
+# provisioning is done. Installed from /tmp just before the trim step removes the
+# sources.
+step "relay shims (gh + git)"
+install -m 0755 /tmp/agentbox-gh-shim  /usr/local/bin/gh
+install -m 0755 /tmp/agentbox-git-shim /usr/local/bin/git
+done_ "relay shims (gh + git)"
+
+step "trim /tmp/agentbox-*"
+rm -f /tmp/agentbox-ctl /tmp/agentbox-vnc-start \
+      /tmp/agentbox-checkpoint-cleanup /tmp/agentbox-open \
+      /tmp/agentbox-gh-shim /tmp/agentbox-git-shim \
+      /tmp/agentbox-custom-CLAUDE.md /tmp/agentbox-managed-settings.json \
+      /tmp/agentbox-codex-hooks.json /tmp/agentbox-setup-skill.md
+mv /tmp/agentbox-provision.sh /var/log/agentbox/provision.sh 2>/dev/null || true
+done_ "trim /tmp/agentbox-*"
+
+printf '\n*** provision.sh: complete — microVM ready for snapshot.\n'

package/share/agentbox-setup/SKILL.md

@@ -14,7 +14,7 @@ Run `agentbox checkpoint --set-default` (similar to `docker commit`) to save any
 
 Some special folders:
 
-- **Host main repo's `.git/`** — If the box bind-mounted RW at its identical absolute host path. In-box commits land on the host's branch refs (visible to `git log` on the host immediately); the box itself carries no SSH/git creds, so `git push` goes through the host relay (`agentbox-ctl git push`). The host's **working tree is never written to** — only refs/objects under `.git/`.
+- **Host main repo's `.git/`** — If the box bind-mounted RW at its identical absolute host path. In-box commits land on the host's branch refs (visible to `git log` on the host immediately); the box itself carries no SSH/git creds, so `git push` goes through the host relay (`agentbox-ctl git push`). The host's **working tree is never written to** — only refs/objects under `.git/`. GitHub PR ops (`agentbox-ctl git pr create|view|list|comment|review|merge|close|reopen|checkout`) flow the same way through host `gh`; write ops require host confirmation (deny → exit 10), `merge` and `checkout` have additional opt-in guards.
 - **`~/.claude`** — and similar home folders for coding agents are seeded from the host's `~/.claude` on each create so auth, skills, and plugins persist without leaking the host's home dir.
 - **`agentbox.yaml`** — read by `agentbox-ctl` from `/workspace`. Tasks and services declared here are what the supervisor will run.
 

package/share/host-skills/agentbox/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: agentbox
+description: "Fork the current agent session into a new VM or local Docker container with all the project files, agent settings and session teleported into."
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+allowed-tools: Bash
+---
+<!-- agentbox-managed:v1 -->
+
+Fork the current Claude Code session into a fresh AgentBox box.
+
+1. **Resolve the provider flag from `$ARGUMENTS`:**
+   - empty → no flag (uses the default docker provider)
+   - `docker` | `daytona` | `hetzner` → pass `--provider $ARGUMENTS`
+   - anything else → stop and tell the user the valid values are `docker`, `daytona`, `hetzner`
+
+2. **Fork.** Run, via the Bash tool, exactly one command:
+
+   ```
+   agentbox fork --session ${CLAUDE_SESSION_ID} [--provider $ARGUMENTS]
+   ```
+
+3. **Report.** In one line, give the user the new box name (parse it from the command output) and confirm their host session is unaffected. Do not summarize the conversation — the fork already carries it.
+
+## Troubleshooting
+
+- If agentbox command fails, tell the user to install AgentBox by writing `! npm -g install @madarco/agentbox` in the chat.
+- If `AGENTBOX_RELAY_URL` is set in the environment, you are running *inside* a box. This command is host-only in v1; tell the user box→box fork is not supported yet.

package/share/host-skills/agentbox-info/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: agentbox-info
+description: "Spin up isolated sandboxes (\"boxes\") for coding agents, run them in parallel, queue background runs with -i, and push commits safely through the host relay. Use when the user wants to run Claude Code / Codex / OpenCode in a sandbox, start more boxes, attach to a running box, or otherwise operate the `agentbox` CLI on their laptop."
+user-invocable: false
+---
+<!-- agentbox-managed:v1 -->
+
+# AgentBox (host-side)
+
+You are operating on the **user's host machine** (laptop / dev workstation), not inside a box. Use the `agentbox` CLI to provision isolated sandboxes for coding agents and to attach to them.
+
+If you find yourself *inside* a box (`/workspace` exists and `AGENTBOX_RELAY_URL` is set in the env), this is the wrong skill — use the in-box `/agentbox-setup` skill instead.
+
+## What AgentBox is, in one paragraph
+
+AgentBox spins up one isolated sandbox per agent run — a local Docker container (default), a Daytona cloud sandbox (`--provider daytona`), or a Hetzner VPS (`--provider hetzner`). Each box has its own `/workspace`, but the host's `.git/` is shared, so commits made inside the box land on the host immediately. The agent inside the box has **no host credentials** — `git push`, opening URLs in the host browser, capturing checkpoints, and all other host-side operations flow through a small host process called the **relay** that runs alongside the CLI.
+
+## The two starting commands
+
+### `agentbox create`
+
+Provision a box and stop. The box exists and is ready, but nothing is launched inside it.
+
+```sh
+agentbox create                       # docker, auto-named after the workspace
+agentbox create -n review             # docker, friendly name
+agentbox create --provider hetzner    # cloud VPS (requires `agentbox prepare --provider hetzner` once)
+agentbox create --attach              # drop into a shell inside the box after create
+```
+
+Useful flags: `-n <name>` (friendly box name), `--provider docker|daytona|hetzner`, `--attach`, `-w <path>` (workspace to mount; defaults to `cwd`), `--snapshot <ref>` (start from a checkpoint).
+
+Non-docker providers require a one-time `agentbox prepare --provider <name>` to bake the base image / snapshot.
+
+### `agentbox claude`
+
+Provision (same as `create`) and launch **Claude Code** inside the box, in a detachable tmux session. This is the main entry point most users want.
+
+```sh
+agentbox claude                       # docker, attaches your terminal
+agentbox claude -n review             # second box, named
+agentbox claude --provider hetzner    # cloud
+agentbox claude -- --model sonnet     # extra args after `--` go to claude itself
+```
+
+While attached: **`Ctrl+a d`** detaches without killing claude. The box keeps running. Reattach with `agentbox claude attach <name|n>`.
+
+Variants with the same shape for other agents: **`agentbox codex`**, **`agentbox opencode`**.
+
+## `-i` / `--initial-prompt`: background queue
+
+With `-i "<prompt>"`, `agentbox claude` (and `codex` / `opencode`) does **not** attach. It writes a job manifest to `~/.agentbox/queue/<id>.json` and exits immediately, printing the job id and log path. The host relay's queue loop drains these manifests respecting `queue.maxConcurrent` (global config; override per invocation with `--max-running <n>`).
+
+Use this to fan out parallel agent runs:
+
+```sh
+agentbox claude -i "fix the failing test in src/auth and open a PR"
+agentbox claude -i "draft a CHANGELOG entry from the last 20 commits"
+agentbox claude -i "audit our dependencies for known CVEs"
+```
+
+Each call returns instantly. The queue drains them concurrently up to `queue.maxConcurrent`. Inspect / attach later:
+
+```sh
+agentbox dashboard                    # TUI with status + leader-key actions
+agentbox claude attach <name|n>       # reattach to a specific box
+```
+
+Caveats: `-i` is currently **docker-only** (cloud sessions only start on attach, so background-mode has no place to seed the prompt). The host must have valid Claude Code credentials.
+
+## Forking the current session into a box
+
+From host Claude, run the **`/agentbox`** slash command (optional arg: `docker` | `daytona` | `hetzner`) to snapshot the *current* Claude Code session into a brand-new box that resumes it. With tmux or iTerm it opens in a new terminal tab; otherwise it starts in the background. The host session is unaffected — you get two parallel timelines. The underlying CLI is `agentbox fork` (`agentbox fork --help`); `/agentbox` requires `agentbox install` to have been run once. This is distinct from `-i`, which seeds a *new* prompt rather than resuming the live conversation.
+
+## Driving one agent from another (`drive`, `agent`, `queue wait-for`)
+
+When *you* are the host-side agent and want to orchestrate other agents running inside boxes — read what they're doing, send them a prompt, wait until they're done or need input — use these three command families. Everything is stateless / one-shot, and the human-text default switches to machine-friendly JSON with `--json`.
+
+### `agentbox drive <box>` — terminal driving
+
+Targets the running tmux session inside a box (auto-picks the agent session: `claude` → `codex` → `opencode` → the only running session; override with `--session <name>`). Provider-uniform — works the same on docker / daytona / hetzner.
+
+```sh
+agentbox drive snapshot 1                          # print rendered TUI as plain text
+agentbox drive snapshot 1 --with-cursor            # JSON envelope: { session, cols, rows, cursor, screen }
+agentbox drive snapshot 1 --ansi --rows -200:-1    # include color, walk into scrollback
+agentbox drive keypress 1 "<C-c>"                  # DSL: <Enter>, <C-x>, <Tab>, <F5>, <Up>, etc.
+agentbox drive send-text 1 "hello"                 # literal text, no DSL parsing, no trailing Enter
+agentbox drive prompt 1 "summarize /workspace/README" # type + Enter (the convenience action)
+agentbox drive wait 1 --text "✓" --timeout 60000   # block until <text> appears on screen
+agentbox drive resize 1 200 60
+```
+
+`keypress` uses a small DSL: `<Enter>`, `<Tab>`, `<Esc>`, `<Space>`, `<BS>`, `<Del>`, `<Up>/<Down>/<Left>/<Right>`, `<Home>/<End>/<PageUp>/<PageDown>`, `<F1>`–`<F12>`, `<C-a>`..`<C-z>`. Use `<<` for a literal `<`. Multiple args concatenate with no spaces (`"ls" "<Enter>"` → `ls\r`).
+
+### `agentbox agent <box>` — agent state introspection (Claude / Codex / OpenCode)
+
+Sub-second latency. State source by agent:
+
+- **Claude Code**: lifecycle hooks (`UserPromptSubmit`, `PreToolUse`, `Stop`, `Notification`, `ExitPlanMode`, `AskUserQuestion`, `PreCompact`/`PostCompact`, `StopFailure`, `SubagentStart`/`SubagentStop`).
+- **Codex**: tmux-pane scraper inside the box (codex 0.134.0's own hook firing is unreliable; staged hooks remain for the day that's fixed upstream).
+- **OpenCode**: a plugin (`agentbox-state.js`) seeded into the OpenCode config volume, subscribing to OpenCode's event bus.
+
+All three feed the same status pipeline; `agent state` / `agent wait-for` work the same regardless of which agent runs inside the box. Reports come from `~/.agentbox/boxes/<id>/status.json` and the relay event stream.
+
+```sh
+agentbox agent state 1                # → working | idle | waiting | end-plan | question | prompt | compacting | error
+agentbox agent state 1 --json         # full BoxStatusClaude (state, updatedAt, sessionTitle, plan?, question?)
+
+agentbox agent wait-for prompt 1 --timeout 600000      # block until Claude is at the input box, no pending plan/question
+agentbox agent wait-for end-plan 1                     # Claude just called ExitPlanMode; user has to approve
+agentbox agent wait-for question 1                     # AskUserQuestion picker is up
+agentbox agent wait-for idle 1                         # Stop hook fired (turn complete)
+agentbox agent wait-for compacting 1                   # Claude is summarizing context (PreCompact fired)
+agentbox agent wait-for error 1                        # Claude's turn ended with a failure (StopFailure)
+
+agentbox agent get-plan-question 1            # print the plan body OR question + options (human)
+agentbox agent get-plan-question 1 --json     # structured payload
+```
+
+The `prompt` state is derived: `idle` AND tmux session alive AND no pending plan/question — i.e. "ready for the next user message". Use it as the natural sync point after sending a new prompt.
+
+The `end-plan` and `question` matchers tolerate the race where Claude's `Notification:permission_prompt` hook flips the raw state to `waiting` immediately after the matcher hook fires — both states still match while the plan/question payload is pending, and only the matching `PostToolUse` (handled internally with `--clear-pending`) resets them.
+
+### `agentbox queue wait-for <event>` — queue + box lifecycle
+
+```sh
+agentbox queue wait-for new-box                          # any new box gets registered
+agentbox queue wait-for empty-queue --timeout 1800000    # all queued/running jobs settled
+agentbox queue wait-for box-running --box review
+agentbox queue wait-for box-paused  --box 2
+agentbox queue wait-for box-stopped --box 2
+agentbox queue wait-for job-done --job b45f1603841bd2b5  # terminal status (done/failed/cancelled)
+```
+
+All wait-for commands exit 0 on match, exit 1 on timeout, and accept `--json` for parseable output.
+
+### Recipe: queue a plan, then act per turn
+
+This is the canonical "drive a Claude Code from another Claude Code" loop. You queue an initial planning prompt, wait for the plan to land, capture it, decide, send the next message, repeat.
+
+```sh
+# 1. Kick off a box with a planning prompt.
+agentbox claude -n design -i "Plan how to add an OAuth login flow to apps/web, then enter plan mode. Don't start coding."
+
+# 2. Wait until Claude is at the ExitPlanMode approval prompt.
+agentbox agent wait-for end-plan design --timeout 600000
+
+# 3. Read the plan back as text (or JSON) and decide.
+PLAN=$(agentbox agent get-plan-question design)
+echo "$PLAN"
+
+# 4. Approve via tmux — option 1 ("Yes, and use auto mode") is already highlighted.
+agentbox drive keypress design "<Enter>"
+
+# 5. Wait for the turn to finish.
+agentbox agent wait-for prompt design --timeout 1200000
+
+# 6. Fan out follow-up work to a fresh box, in background, while reviewing this one.
+agentbox claude -i "Write the OAuth provider unit tests in apps/web/test/auth/"
+
+# 7. Block until everything settles before reporting back.
+agentbox queue wait-for empty-queue --timeout 3600000
+```
+
+The same shape covers `agent wait-for question` + `agent get-plan-question` (read the choices, send the answer index via `drive keypress 1 "<Down><Enter>"`, then `wait-for prompt`).
+
+### Quick mental model
+
+- `drive` = "send keystrokes / read screen" — provider-uniform tmux capture-pane / send-keys.
+- `agent` = "what is the Claude TUI currently doing" — hook-driven, race-free, machine-readable.
+- `queue wait-for` = "block on queue or box lifecycle transitions" — poll-based, no new endpoint.
+- All three commands are **stateless** — safe to invoke from any script, any agent, in parallel.
+- `--json` everywhere. Default human text is for the operator; an agent should pass `--json`.
+
+## Git through the host relay
+
+**The box has no SSH keys, GPG keys, or git remote credentials.** Don't ask the user to add any. When an in-box agent (or a script you run inside the box) does `git push` or `git pull`, the AgentBox-provided `agentbox-ctl git` wrapper POSTs a JSON-RPC call to the host relay (`POST /rpc`, bearer-auth, loopback-only). The relay runs the **real** `git push origin …` on the host, using the user's `SSH_AUTH_SOCK`, `~/.gitconfig`, and identity — and streams stdout/stderr back into the box's terminal. The box's exit code matches the host's.
+
+Implications for you, the host-side agent:
+
+- Inside the box you can `git commit … && git push` exactly as normal. No setup needed.
+- Pushes are gated host-side: the relay can require a confirm prompt for destructive operations (the user sees it in the dashboard footer, ~25 s TTL). If a push appears to hang, tell the user to check the dashboard.
+- The relay process is started lazily by the first `agentbox create` / `agentbox claude` and persists across runs (PID at `~/.agentbox/relay.pid`, log at `~/.agentbox/relay.log`). You normally don't need to manage it.
+
+## Other commands worth knowing
+
+| Command | What it does |
+| --- | --- |
+| `agentbox dashboard` | TUI status + switcher across all boxes. The leader is **`Ctrl+a`** (e.g. `Ctrl+a u` opens the box's web URL; `Ctrl+a s` opens the in-box browser; `Ctrl+a q` quits). |
+| `agentbox shell [n\|name]` | Interactive `bash -l` inside the box (also wrapped in tmux by default — detach with `Ctrl+a d`). |
+| `agentbox url [n\|name]` | Open the box's web app URL (`<box-name>.localhost` via Portless) in the host browser. |
+| `agentbox screen [n\|name]` | Open the box's **own** Chromium via VNC — useful for OAuth flows the agent inside the box initiates. |
+| `agentbox code [n\|name]` | Open VS Code / Cursor pointed at the box. |
+| `agentbox prepare --provider <name>` | One-time base image / snapshot build for `daytona` or `hetzner`. With no `--provider`, prints status across all providers. |
+| `agentbox prune --provider <name>` | Clean up orphan boxes / images / snapshots for a provider (docker + daytona supported; hetzner pending). |
+
+Per-project numeric index (`1`, `2`, …) and friendly name (`review`, `smoke`) both work wherever `<box>` is accepted. Index `1` is the first box created in the current workspace.
+
+## Operating principles
+
+1. **Never assume the host needs SSH keys forwarded into a box** — git is handled by the relay, by design.
+2. **Use `-i` whenever the user asks for parallel agent work** rather than spawning multiple foreground sessions. Then point them at `agentbox dashboard` to watch progress.
+3. **Pick the provider deliberately.** `docker` is the fast default. `--provider hetzner` gives a real VPS (heavier, isolated, requires `agentbox prepare --provider hetzner` once). `--provider daytona` is the managed cloud option.
+4. **Cross-check before recommending a command.** If a flag isn't listed here, run `agentbox <command> --help` (it's safe and read-only) before suggesting it to the user.
+5. **`/agentbox-setup` is a different skill.** It runs *inside* a box to generate `/workspace/agentbox.yaml`. Don't conflate it with `/agentbox` (host-side fork) or this reference skill.
+
+## Reference
+
+- Full docs live in the repo at `docs/` — start with `docs/architecture.md` and `docs/create-and-checkpoints.md` for the model, `docs/host-relay.md` for the relay, `docs/cloud-providers.md` for the cloud paths.
+- npm package: `@madarco/agentbox` — `npm -g install @madarco/agentbox` (or `npx @madarco/agentbox <command>`).

package/share/host-skills/codex/agentbox.md

@@ -0,0 +1,35 @@
+---
+description: Fork the current Codex session into a new AgentBox box and resume it there (opens in a new terminal tab).
+argument-hint: [provider]
+---
+<!-- agentbox-managed:v1 -->
+
+Fork the current Codex session into a fresh AgentBox box running Codex.
+
+Optional provider argument: `$ARGUMENTS` (docker | daytona | hetzner; default docker).
+
+## Steps
+
+1. **Pre-flight (stop on either):**
+   - If `AGENTBOX_RELAY_URL` is set in the environment, you are running *inside* a box — box→box fork is not supported yet; stop and tell the user.
+   - If `which agentbox` fails, tell the user to install AgentBox (`npm -g install @madarco/agentbox`) and stop.
+
+2. **Find the current Codex session id.** Codex exposes no session-id variable, so resolve it from the most recently written rollout file (that is the live session). Run via your shell tool:
+
+   ```
+   ls -t "$HOME"/.codex/sessions/*/*/*/rollout-*.jsonl 2>/dev/null | head -1 \
+     | xargs -I{} basename {} .jsonl \
+     | grep -oE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+   ```
+
+   That prints the session `<uuid>`. If it prints nothing, stop and tell the user no Codex session was found for this machine.
+
+3. **Resolve the provider flag from `$ARGUMENTS`:** empty → none; `docker` | `daytona` | `hetzner` → `--provider $ARGUMENTS`; anything else → stop and report the valid values.
+
+4. **Fork.** Run, via your shell tool:
+
+   ```
+   agentbox fork --agent codex --session <uuid> [--provider <from step 3>]
+   ```
+
+5. **Report** the new box name from the command output. Your current Codex session is unaffected — you now have two parallel timelines.

package/share/host-skills/opencode/agentbox.md

@@ -0,0 +1,26 @@
+---
+description: Spawn a parallel AgentBox box running OpenCode for this project (opens in a new terminal tab). Note - the current OpenCode session is not resumed yet; this starts a fresh session.
+---
+<!-- agentbox-managed:v1 -->
+
+Spawn a new AgentBox box running OpenCode for the current project, in a new terminal tab.
+
+Optional provider argument: `$ARGUMENTS` (docker | daytona | hetzner; default docker).
+
+**Note:** resuming an OpenCode session into a box isn't supported yet (sessions live in a shared SQLite DB), so this starts a **fresh** OpenCode session in the box — it does not carry the current conversation.
+
+## Steps
+
+1. **Pre-flight (stop on either):**
+   - If `AGENTBOX_RELAY_URL` is set in the environment, you are running *inside* a box — not supported; stop and tell the user.
+   - If `which agentbox` fails, tell the user to install AgentBox (`npm -g install @madarco/agentbox`) and stop.
+
+2. **Resolve the provider flag from `$ARGUMENTS`:** empty → none; `docker` | `daytona` | `hetzner` → `--provider $ARGUMENTS`; anything else → stop and report the valid values.
+
+3. **Fork.** Run, via your shell tool:
+
+   ```
+   agentbox fork --agent opencode [--provider <from step 2>]
+   ```
+
+4. **Report** the new box name from the command output.

package/dist/_cloud-attach-DMVH6GWO.js

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-import {
-  buildCloudAttachInnerCommand,
-  cloudAgentAttach
-} from "./chunk-7KOEFGN2.js";
-import "./chunk-NAVL4R34.js";
-import "./chunk-UK72UQ5U.js";
-export {
-  buildCloudAttachInnerCommand,
-  cloudAgentAttach
-};
-//# sourceMappingURL=_cloud-attach-DMVH6GWO.js.map