@madarco/agentbox 0.13.0 → 0.15.0

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

@@ -0,0 +1,46 @@
+# AgentBox sandbox (e2b provider)
+
+You are running inside an AgentBox sandbox: an E2B microVM (Firecracker on
+Debian) provisioned just for this box. Your user is `vscode` and you can use
+passwordless **sudo** to run commands as root. The whole microVM is yours — the
+user's host filesystem is not visible from here and nothing is bind-mounted.
+
+**No containers.** E2B microVMs can't run nested containers, so `docker` /
+`podman` cannot run here — not even rootless. Don't try to start a container
+engine; run build/test/dev processes directly on the microVM instead.
+
+This box is **persistent**: stopping it pauses the microVM (cold-store) and
+resuming wakes it back up, so the filesystem survives a pause. You can also save
+the current filesystem state for future boxes with
+`agentbox-ctl checkpoint --set-default` — that calls E2B's `createSnapshot` to
+mint a reusable template snapshot. A checkpoint/snapshot PAUSES the box while
+it's captured, so use it only at the end of the setup wizard.
+
+`/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`). 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/e2b/gh-shim

@@ -0,0 +1,344 @@
+#!/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, diff, checks, 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 -- "$@"
+      ;;
+    diff)
+      strict_flags "gh pr diff" "--color|--name-only|--patch" "$@"
+      if [ -z "$(first_positional "--color" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr diff -- "$@"
+      ;;
+    checks)
+      strict_flags "gh pr checks" "--json|--required" "$@"
+      if [ -z "$(first_positional "--json" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr checks -- "$@"
+      ;;
+    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, diff, checks, create, comment, review, merge, checkout, close, reopen)"
+      ;;
+  esac
+}
+
+handle_run() {
+  local op="${1-}"; shift || true
+  if [ -z "$op" ]; then
+    die "missing subcommand for 'gh run'. Supported: list, view, rerun"
+  fi
+  case "$op" in
+    list)
+      strict_flags "gh run list" "--json|--limit|-L|--workflow|-w|--branch|-b|--status|--user" "$@"
+      exec "$CTL" gh run list -- "$@"
+      ;;
+    view)
+      strict_flags "gh run view" "--json|--log|--log-failed|--job" "$@"
+      # gh run view needs a run-id OR a --job <id>; refuse when neither is
+      # present (host-side gh would otherwise try an interactive picker and
+      # fail without a TTY).
+      if [ -z "$(first_positional "--json|--job" "$@")" ] && ! needle_present "--job" "$@"; then
+        die "'gh run view' requires a positional <run-id> (or --job <job-id>)"
+      fi
+      exec "$CTL" gh run view -- "$@"
+      ;;
+    rerun)
+      strict_flags "gh run rerun" "--failed|--job" "$@"
+      if [ -z "$(first_positional "--job" "$@")" ] && ! needle_present "--job" "$@"; then
+        die "'gh run rerun' requires a positional <run-id> (or --job <job-id>)"
+      fi
+      exec "$CTL" gh run rerun -- "$@"
+      ;;
+    watch)
+      die "'gh run watch' is not proxied (it blocks until CI finishes). Poll status with 'gh run view <run-id>' instead."
+      ;;
+    *)
+      die "'gh run $op' is not proxied (supported: list, view, rerun)"
+      ;;
+  esac
+}
+
+handle_api() {
+  local endpoint="${1-}"
+  if [ -z "$endpoint" ] || [ "${endpoint:0:1}" = "-" ]; then
+    die "'gh api' requires a positional <endpoint> (e.g. repos/:owner/:repo/pulls/:number/comments)"
+  fi
+  shift
+  # GET reads are proxied for any allowlisted endpoint; POST is proxied only to
+  # the PR review-comment endpoints (the relay enforces the endpoint + method
+  # policy). `--input` (stdin/file body) can't cross the relay — the host `gh`
+  # runs with stdin ignored — so reject it locally and point at -f/-F fields.
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --input|--input=*)
+        die "'gh api --input' (stdin/file body) isn't supported through the relay; use -f/-F fields"
+        ;;
+    esac
+  done
+  strict_flags "gh api" \
+    "--method|-X|-f|-F|--field|--raw-field|--jq|-q|--paginate|--cache|--hostname|-H|--header" "$@"
+  exec "$CTL" gh api "$endpoint" -- "$@"
+}
+
+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,diff,checks,create,comment,review,merge,checkout,close,reopen}, run {list,view,rerun}, api <endpoint>, 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,diff,checks,create,comment,review,merge,checkout,close,reopen}, run {list,view,rerun}, api <endpoint>, 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 "$@"
+    ;;
+  run)
+    shift
+    handle_run "$@"
+    ;;
+  api)
+    shift
+    handle_api "$@"
+    ;;
+  repo)
+    shift
+    handle_repo "$@"
+    ;;
+  *)
+    die "'gh $1' is not proxied (supported: pr {…}, run {…}, api <endpoint>, repo clone, auth status, --version)"
+    ;;
+esac

package/runtime/e2b/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