@madarco/agentbox 0.7.0 → 0.8.0

package/runtime/hetzner/custom-system-CLAUDE.md

@@ -1,27 +1,39 @@
-# AgentBox sandbox
+# AgentBox sandbox (hetzner provider)
 
-You are running inside an AgentBox sandbox: a Linux Docker container with
-docker-in-docker (run `docker` directly, no sudo). 
-Your user is `vscode` and you can use passwordless **sudo** to run commands as root.
-`/workspace` is your own per-box git worktree on branch `agentbox/<box-name>`:
-writes there stay in the container's writable layer and don't touch the host's working
-tree.
+You are running inside an AgentBox sandbox: a dedicated Linux VPS (Ubuntu) on
+Hetzner Cloud provisioned just for this box. Docker-in-docker is available
+(run `docker` directly, no sudo). Your user is `vscode` and you can use
+passwordless **sudo** to run commands as root. The whole VPS is yours — the
+user's host filesystem is not visible from here and nothing is bind-mounted.
 
-You can save the current filesystem state to be reused by future boxes by 
+You can save the current filesystem state to be reused by future boxes by
 running `agentbox-ctl checkpoint --set-default`. This doesn't need to be confirmed by the user.
 
-The main `.git/` is bind-mounted at the same absolute path as on
-the host, so local commits show up in the host's `git log` immediately.
-No SSH creds, no host gitconfig identity. For ops that need the user
-(push, fetch from private remotes), use `agentbox-ctl git push|fetch|pull
--- <args>` — it RPCs to the host, which runs git with the real SSH agent.
+`/workspace` is a normal git checkout seeded from the host repo at create
+time. Because there is no host bind-mount, plain `git` inside the box only
+affects this box-local repo — commits do **not** appear in the user's host
+`git log` until you hand them off. For any operation that must reach the host
+repo or its remotes (push, fetch, pull, picking up host-side changes), use
+`agentbox-ctl git push|fetch|pull -- <args>` — it RPCs to the host, which
+runs git with the real SSH agent and writes back into the host's worktree
+state. The wrapper already builds `git push <remote> <branch>` host-side from
+the registered worktree; the `-- <args>` slot is for extra flags only (e.g.
+`--force-with-lease`, `--tags`). Re-passing the remote or branch makes git
+treat them as refspecs and fails with `refs/remotes/origin/HEAD cannot be
+resolved to branch`.
+
+For GitHub PR work, use `agentbox-ctl git pr <op> [args...]` — same model,
+relay shells to host `gh`. Ops: `create`, `view`, `list`, `comment`,
+`review`, `merge`, `close`, `reopen`, `checkout`. `view` / `list` are
+read-only and run silently; everything else asks the user to confirm in
+the host wrapper (deny → exit 10).
 
 For ad-hoc file transfers between this box and the host, use
 `agentbox-ctl cp toHost <boxPath> <hostPath>` and
 `agentbox-ctl cp fromHost <hostPath> <boxPath>` or `agentbox-ctl download claude` / `download env` /
 `download config`. They RPC to the host and
 ask the user for confirmation on the wrapper that runs `agentbox claude`;
-deny returns exit 10 (`denied by user`). 
+deny returns exit 10 (`denied by user`).
 Don't put any timeout on the command, it will run forever and the user will be notified through multiple channels.
 
 Box identity: /etc/agentbox/box.env and the AGENTBOX_* env vars.

package/runtime/hetzner/gh-shim

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# agentbox `gh` shim — translates a strict subset of `gh` subcommands into
+# `agentbox-ctl gh ...` so the host's authenticated `gh` runs the operation
+# and only the result crosses back into the box. The in-box agent never sees
+# a GitHub token.
+#
+# This shim ships only what Claude Code's PR badge and our documented agent
+# flows need. Anything outside the subset below is rejected with a clear
+# error — better safe than compatible. Add ops deliberately, not by default.
+
+set -euo pipefail
+
+# Paths are constants in production; env overrides exist purely to let unit
+# tests substitute a stub `agentbox-ctl` on PATH without rewriting the shim.
+CTL="${AGENTBOX_CTL_PATH:-/usr/local/bin/agentbox-ctl}"
+REAL_GIT="${AGENTBOX_REAL_GIT_PATH:-/usr/bin/git}"
+
+die() {
+  printf 'agentbox gh shim: %s\n' "$*" >&2
+  exit 2
+}
+
+# Resolve the in-box current branch once. Used to inject the right ref into
+# `gh pr` commands so the host's `gh` (which runs in the host main repo, not
+# the box's worktree) doesn't fall back to the host's HEAD.
+box_branch() {
+  "$REAL_GIT" -C "$PWD" rev-parse --abbrev-ref HEAD 2>/dev/null || true
+}
+
+# Returns 0 if any element of "$@" equals "$1" (the needle).
+needle_present() {
+  local needle="$1"; shift
+  local arg
+  for arg in "$@"; do
+    if [ "$arg" = "$needle" ]; then return 0; fi
+  done
+  return 1
+}
+
+# Walk argv: if any arg starts with `-` and isn't in the allowed set, die.
+# Doesn't try to validate flag _values_ (e.g. `--json number,url`); that's
+# real gh's job — we only block flags we don't expect to see.
+strict_flags() {
+  local subcmd="$1"; shift
+  local allowed="$1"; shift
+  local re="^(${allowed})$"
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --) ;;
+      -*)
+        if ! [[ "$arg" =~ $re ]]; then
+          die "unsupported flag '$arg' for '$subcmd'. Allowed: ${allowed//|/, }"
+        fi
+        ;;
+    esac
+  done
+}
+
+# Returns the first true positional arg of "$@" (skipping flags AND their
+# values), or '' if none. $1 is a `|`-separated list of value-taking flags
+# for the current subcommand — e.g. "--json|--title|--body|--base" means the
+# token after any of those flags is a value, not a positional. Without this
+# we'd treat `--json number,url`'s field list as the positional and miss
+# branch injection (real bug: PR-badge lookups returned "no PR for main"
+# because the JSON field list looked positional).
+first_positional() {
+  local value_taking="$1"; shift
+  local re="^(${value_taking})$"
+  local arg
+  local skip_value=0
+  for arg in "$@"; do
+    if [ "$skip_value" = "1" ]; then
+      skip_value=0
+      continue
+    fi
+    case "$arg" in
+      --) ;;
+      -*)
+        if [[ -n "$value_taking" && "$arg" =~ $re ]]; then
+          skip_value=1
+        fi
+        ;;
+      *) printf '%s\n' "$arg"; return 0 ;;
+    esac
+  done
+}
+
+handle_pr() {
+  local op="${1-}"; shift || true
+  if [ -z "$op" ]; then
+    die "missing subcommand for 'gh pr'. Supported: view, list, create, comment, review, merge, checkout, close, reopen"
+  fi
+  local branch
+  branch="$(box_branch)"
+
+  case "$op" in
+    view)
+      strict_flags "gh pr view" "--json" "$@"
+      if [ -z "$(first_positional "--json" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr view -- "$@"
+      ;;
+    list)
+      strict_flags "gh pr list" "--json|--state" "$@"
+      if ! needle_present "--head" "$@" && [ -n "$branch" ]; then
+        set -- "$@" "--head" "$branch"
+      fi
+      exec "$CTL" gh pr list -- "$@"
+      ;;
+    create)
+      strict_flags "gh pr create" "--fill|--draft|--title|--body|--base" "$@"
+      if ! needle_present "--head" "$@" && [ -n "$branch" ]; then
+        set -- "$@" "--head" "$branch"
+      fi
+      exec "$CTL" gh pr create -- "$@"
+      ;;
+    comment)
+      strict_flags "gh pr comment" "--body" "$@"
+      if [ -z "$(first_positional "--body" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr comment -- "$@"
+      ;;
+    review)
+      strict_flags "gh pr review" "--approve|--request-changes|--comment|--body" "$@"
+      if [ -z "$(first_positional "--body" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr review -- "$@"
+      ;;
+    merge)
+      strict_flags "gh pr merge" "--squash|--merge|--rebase|--delete-branch" "$@"
+      if [ -z "$(first_positional "" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr merge -- "$@"
+      ;;
+    close)
+      strict_flags "gh pr close" "--delete-branch" "$@"
+      if [ -z "$(first_positional "" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr close -- "$@"
+      ;;
+    reopen)
+      strict_flags "gh pr reopen" "" "$@"
+      if [ -z "$(first_positional "" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr reopen -- "$@"
+      ;;
+    checkout)
+      # gh pr checkout takes a required ref (number / URL / branch). No
+      # auto-inject — the relay also refuses checkout by default
+      # (AGENTBOX_GH_PR_CHECKOUT=allow opt-in).
+      strict_flags "gh pr checkout" "" "$@"
+      if [ -z "$(first_positional "" "$@")" ]; then
+        die "'gh pr checkout' requires a positional ref (PR number, URL, or branch)"
+      fi
+      exec "$CTL" gh pr checkout -- "$@"
+      ;;
+    *)
+      die "'gh pr $op' is not proxied (supported: view, list, create, comment, review, merge, checkout, close, reopen)"
+      ;;
+  esac
+}
+
+handle_repo() {
+  local op="${1-}"; shift || true
+  if [ "$op" != "clone" ]; then
+    die "'gh repo $op' is not proxied (supported: clone)"
+  fi
+  # gh repo clone <repo> [<dir>] [--branch <n>] [--depth <n>]
+  strict_flags "gh repo clone" "--branch|--depth" "$@"
+  # Split argv into (repo, dir, flags). Pass positionals BEFORE options to the
+  # ctl so commander parses --branch/--depth as real options; using a `--`
+  # separator would force commander to treat them as extra positionals (the
+  # ctl `gh repo clone` command doesn't allowExcessArguments).
+  local repo='' dir=''
+  local -a flags=()
+  local pos=0
+  local skip_value=0
+  local arg
+  for arg in "$@"; do
+    if [ "$skip_value" = "1" ]; then
+      flags+=("$arg")
+      skip_value=0
+      continue
+    fi
+    case "$arg" in
+      --branch|--depth)
+        flags+=("$arg")
+        skip_value=1
+        ;;
+      -*)
+        flags+=("$arg")
+        ;;
+      *)
+        if [ $pos -eq 0 ]; then repo="$arg"
+        elif [ $pos -eq 1 ]; then dir="$arg"
+        else die "too many positionals for 'gh repo clone' (got '$arg' after repo + dir)"
+        fi
+        pos=$((pos+1))
+        ;;
+    esac
+  done
+  if [ -z "$repo" ]; then
+    die "'gh repo clone' requires a positional <repo> (owner/name or full URL)"
+  fi
+  if [ -n "$dir" ]; then
+    exec "$CTL" gh repo clone "$repo" "$dir" ${flags[@]+"${flags[@]}"}
+  else
+    exec "$CTL" gh repo clone "$repo" ${flags[@]+"${flags[@]}"}
+  fi
+}
+
+# Top-level dispatch.
+if [ $# -eq 0 ]; then
+  die "no subcommand. Supported: pr {view,list,create,comment,review,merge,checkout,close,reopen}, repo clone, auth status, --version"
+fi
+
+case "$1" in
+  --version|-v)
+    # Real gh prints something like:
+    #   gh version 2.40.0 (2023-10-26)
+    #   https://github.com/cli/cli/releases/tag/v2.40.0
+    # Tools that sniff "gh version" succeed with our shim line too.
+    printf 'gh version 2.0.0 (agentbox-shim)\n'
+    printf 'https://github.com/cli/cli\n'
+    ;;
+  --help|-h)
+    printf 'agentbox gh shim — strict subset.\n' >&2
+    printf 'Supported: pr {view,list,create,comment,review,merge,checkout,close,reopen}, repo clone, auth status, --version\n' >&2
+    printf 'Anything else is rejected. Run host `gh --help` for full upstream docs.\n' >&2
+    ;;
+  auth)
+    shift
+    case "${1-}" in
+      status)
+        # Real auth state is verified host-side on the next real RPC (relay's
+        # assertGhReady returns exit 4 if the host is logged out). We don't
+        # round-trip on every refresh-driven poll Claude Code does.
+        printf 'agentbox gh shim: logged in to github.com (via agentbox host relay)\n' >&2
+        ;;
+      *)
+        die "'gh auth ${1-}' is not proxied (supported: status)"
+        ;;
+    esac
+    ;;
+  pr)
+    shift
+    handle_pr "$@"
+    ;;
+  repo)
+    shift
+    handle_repo "$@"
+    ;;
+  *)
+    die "'gh $1' is not proxied (supported: pr {…}, repo clone, auth status, --version)"
+    ;;
+esac

package/runtime/hetzner/git-shim

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# agentbox `git` shim — intercepts the four network ops (`push`, `pull`,
+# `fetch`, `clone`) and routes them through `agentbox-ctl git ...` so the
+# host runs the credential-touching part. Everything else (commit, status,
+# log, diff, add, checkout, branch, ...) falls through to the real
+# `/usr/bin/git` with zero overhead and zero shim output.
+#
+# Strict per-op flag whitelist — better safe than compatible. Adding a flag
+# is a deliberate decision, not a default.
+
+set -euo pipefail
+
+# Paths are constants in production; env overrides exist purely to let unit
+# tests substitute a stub `agentbox-ctl` on PATH without rewriting the shim.
+# NEVER `exec git` — would loop on this shim. Always exec the resolved $REAL_GIT.
+CTL="${AGENTBOX_CTL_PATH:-/usr/local/bin/agentbox-ctl}"
+REAL_GIT="${AGENTBOX_REAL_GIT_PATH:-/usr/bin/git}"
+
+die() {
+  printf 'agentbox git shim: %s\n' "$*" >&2
+  exit 2
+}
+
+# Walk argv: any arg matching `-*` must be in $allowed (regex alternation).
+# Doesn't validate flag _values_ (e.g. `--branch main`); that's git's job.
+strict_flags() {
+  local subcmd="$1"; shift
+  local allowed="$1"; shift
+  local re="^(${allowed})$"
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --) ;;
+      -*)
+        if ! [[ "$arg" =~ $re ]]; then
+          die "unsupported flag '$arg' for '$subcmd'. Allowed: ${allowed//|/, }"
+        fi
+        ;;
+    esac
+  done
+}
+
+# Network ops (push/pull/fetch): refuse positional remote/branch. The ctl
+# rebuilds them from the registered worktree; re-passing them as positionals
+# makes git treat them as refspecs and fail with
+# `refs/remotes/origin/HEAD cannot be resolved to branch` (documented at
+# packages/ctl/src/commands/git.ts:131).
+refuse_positionals() {
+  local subcmd="$1"; shift
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --) ;;
+      -*) ;;
+      *)
+        die "positional '$arg' not allowed for '$subcmd' (the box's remote and branch are taken from the registered worktree)"
+        ;;
+    esac
+  done
+}
+
+if [ $# -eq 0 ]; then
+  exec "$REAL_GIT"
+fi
+
+case "$1" in
+  push)
+    shift
+    strict_flags "git push" "--force-with-lease" "$@"
+    refuse_positionals "git push" "$@"
+    exec "$CTL" git push -- "$@"
+    ;;
+  pull)
+    shift
+    strict_flags "git pull" "--ff-only" "$@"
+    refuse_positionals "git pull" "$@"
+    exec "$CTL" git pull -- "$@"
+    ;;
+  fetch)
+    shift
+    strict_flags "git fetch" "--prune" "$@"
+    refuse_positionals "git fetch" "$@"
+    exec "$CTL" git fetch -- "$@"
+    ;;
+  clone)
+    shift
+    strict_flags "git clone" "--branch|--depth" "$@"
+    # Walk argv: split into (url, dir, flags) so we can hand them to ctl
+    # in commander's expected shape (positionals first, then options).
+    url=''
+    dir=''
+    flags=()
+    pos=0
+    skip_value=0
+    for arg in "$@"; do
+      if [ "$skip_value" = "1" ]; then
+        flags+=("$arg")
+        skip_value=0
+        continue
+      fi
+      case "$arg" in
+        --branch|--depth)
+          flags+=("$arg")
+          skip_value=1
+          ;;
+        -*)
+          flags+=("$arg")
+          ;;
+        *)
+          if [ $pos -eq 0 ]; then url="$arg"
+          elif [ $pos -eq 1 ]; then dir="$arg"
+          else die "too many positionals for 'git clone' (got '$arg' after url + dir)"
+          fi
+          pos=$((pos+1))
+          ;;
+      esac
+    done
+    if [ -z "$url" ]; then
+      die "'git clone' requires a positional <url> (github URL or owner/name shorthand)"
+    fi
+    # `set -u` + empty array: use the ${arr[@]+"${arr[@]}"} guard.
+    if [ -n "$dir" ]; then
+      exec "$CTL" git clone "$url" "$dir" ${flags[@]+"${flags[@]}"}
+    else
+      exec "$CTL" git clone "$url" ${flags[@]+"${flags[@]}"}
+    fi
+    ;;
+  *)
+    exec "$REAL_GIT" "$@"
+    ;;
+esac

package/runtime/hetzner/opencode-agentbox-plugin.js

@@ -0,0 +1,76 @@
+// AgentBox state-reporting plugin for OpenCode (sst/opencode).
+//
+// Subscribes to OpenCode's plugin event bus and reports each lifecycle
+// transition to `agentbox-ctl opencode-state <state>`. The ctl daemon then
+// publishes the state to the host relay's status.json, which is what
+// `agentbox agent state` / `agent wait-for` consume on the host side.
+//
+// Fire-and-forget — a missing/late `agentbox-ctl` must never disturb the
+// OpenCode session. The spawned process is detached + unrefed so a slow
+// ctl response never blocks an event handler.
+//
+// Seeded by `seedOpencodePlugin` (packages/sandbox-docker/src/opencode.ts)
+// from the image-baked copy at /usr/local/share/agentbox/opencode-plugin/
+// into the box's `$OPENCODE_CONFIG_DIR/plugins/agentbox-state.js` on every
+// create / start. Idempotent overwrite.
+//
+// Event coverage (mirrors the Claude / Codex state machine):
+//   working   — agent is generating. Driven by `message.part.delta` (streamed
+//               tokens) — these fire only DURING active generation, never after
+//               the turn ends, so they don't fight the `session.idle` end
+//               signal. (Empirically `tool.execute.before` does NOT reach the
+//               plugin event bus in opencode 1.15, and `message.updated` fires
+//               once AFTER `session.idle` — so neither is safe to map to
+//               working.)
+//   idle      — turn complete / ready for input (`session.idle`, plus
+//               `session.created` as a baseline at session start).
+//   waiting   — user input required (`permission.asked`).
+//   error     — `session.error`.
+//   compacting — opencode has no PreCompact event; `session.compacted` fires
+//                AFTER compaction completes, so it maps to `working` (the next
+//                event supersedes) rather than `compacting`.
+//
+// The plugin shape comes from https://opencode.ai/docs/plugins/ — `event` is
+// a single handler that receives `{ event }` with a `type` field. Multiple
+// exports = multiple plugin functions; we ship one.
+
+import { spawn } from 'node:child_process';
+
+const EVENT_TO_STATE = {
+  'session.created': 'idle',
+  'session.idle': 'idle',
+  'session.error': 'error',
+  'session.compacted': 'working',
+  'permission.asked': 'waiting',
+  'permission.replied': 'working',
+  'message.part.delta': 'working',
+  // tool.execute.before kept as a defensive mapping — harmless if a future
+  // opencode build starts surfacing it (it doesn't today).
+  'tool.execute.before': 'working',
+};
+
+// Dedupe: `message.part.delta` fires dozens of times per streamed turn. Only
+// spawn agentbox-ctl when the mapped state actually changes, so a turn costs
+// ~2 spawns (working on the first delta, idle on session.idle) instead of ~50.
+let lastState = null;
+
+function pushState(state) {
+  if (!state || state === lastState) return;
+  lastState = state;
+  try {
+    const p = spawn('agentbox-ctl', ['opencode-state', state], {
+      stdio: 'ignore',
+      detached: true,
+    });
+    p.unref();
+  } catch {
+    // Fire-and-forget. A missing agentbox-ctl bin (test env, older box image)
+    // must not throw out of this handler.
+  }
+}
+
+export const AgentboxStatePlugin = async () => ({
+  event: async ({ event }) => {
+    pushState(EVENT_TO_STATE[event?.type]);
+  },
+});

package/runtime/hetzner/scripts/install-box.sh

@@ -13,6 +13,8 @@
 #   /tmp/agentbox-dockerd-start        -- DinD 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 via relay)
+#   /tmp/agentbox-git-shim             -- in-box `git` shim (routes push/pull/fetch/clone 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
@@ -159,13 +161,19 @@ done_ "agentbox-ctl install"
 # *before* Chromium sidesteps the issue and keeps the snapshot complete.
 # Tracked as Phase-7 follow-up in docs/hertzner_backlog.md.
 
-step "baked helper scripts (vnc / dockerd / cleanup / xdg-open shim)"
+step "baked helper scripts (vnc / dockerd / cleanup / xdg-open / gh + git shims)"
 install -m 0755 /tmp/agentbox-vnc-start          /usr/local/bin/agentbox-vnc-start
 install -m 0755 /tmp/agentbox-dockerd-start      /usr/local/bin/agentbox-dockerd-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
-done_ "baked helper scripts (vnc / dockerd / cleanup / xdg-open shim)"
+# gh + git shims — same files baked by Dockerfile.box for the docker provider.
+# The shim wins on PATH (default /usr/local/bin precedes /usr/bin) so any agent
+# call to `gh ...` / `git push|pull|fetch|clone` routes through the relay; the
+# git shim execs /usr/bin/git for everything else, no overhead.
+install -m 0755 /tmp/agentbox-gh-shim            /usr/local/bin/gh
+install -m 0755 /tmp/agentbox-git-shim           /usr/local/bin/git
+done_ "baked helper scripts (vnc / dockerd / cleanup / xdg-open / gh + git shims)"
 
 step "baked config files (claude / codex / setup guide / tmux.conf)"
 install -m 0644 /tmp/agentbox-custom-CLAUDE.md      /etc/claude-code/CLAUDE.md
@@ -356,6 +364,7 @@ step "trim /tmp/agentbox-*"
 # re-read which lines actually executed against which source.
 rm -f /tmp/agentbox-ctl /tmp/agentbox-vnc-start /tmp/agentbox-dockerd-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
 # Move install-box.sh into the persistent location for diagnostics.