docs(sandbox): auto-clone the kagenti-extensions plugin in 01-build-images.sh

Drop the manual "check out kagenti-extensions" prerequisite. When EXT_DIR is
unset, the script now clones the placeholder-resolve plugin itself from
EXT_REPO @ EXT_REF (default huang195/kagenti-extensions @
feat/placeholder-resolve-plugin; switch to canonical main once PR NVIDIA#626 merges).
EXT_DIR still wins for a local checkout. The supervisor side needs no checkout
step — it builds from this OpenShell repo (you're already on feat/authbridge-egress).

- 01-build-images.sh: EXT_DIR optional; add EXT_REPO/EXT_REF; clone-or-reuse
  before the build; fail-fast message points at EXT_REPO/EXT_REF.
- README + guide: prereq #2 is just the OpenShell branch; the plugin is cloned
  for you; drop the EXT_DIR export from the quick-start; document EXT_REPO/EXT_REF.

Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>
Signed-off-by: Hai Huang <huang195@gmail.com>

Author: huang195

docs/sandboxes/authbridge-egress.mdx

@@ -88,11 +88,12 @@ internal proxy to the AuthBridge sidecar.
   **[Kagenti Sandbox Guide](https://github.com/kagenti/kagenti/blob/main/docs/sandbox-guide.md)**
   (Kind cluster, shared infra, a tenant gateway, the CLI configured and logged in).
   This guide assumes you can already create a normal sandbox in `team1`.
-- **Check out the feature branches this integration depends on (both unmerged):** this
-  OpenShell repo on **`feat/authbridge-egress`** (`NetworkMode::External`), and a
-  kagenti-extensions checkout on **`feat/placeholder-resolve-plugin`** (the plugin). See
-  *Where the images come from* below; `01-build-images.sh` fails fast if either checkout
-  is missing its feature.
+- **This OpenShell repo on the `feat/authbridge-egress` branch** (`NetworkMode::External`) —
+  you're already on it if you're reading this, and the supervisor is built from it. The
+  kagenti-extensions **`placeholder-resolve`** plugin is **cloned automatically** by
+  `01-build-images.sh` (from `huang195/kagenti-extensions @ feat/placeholder-resolve-plugin`
+  by default; override with `EXT_REPO`/`EXT_REF`, or set `EXT_DIR` to a local checkout). See
+  *Where the images come from* below; the script fails fast if the resolved source lacks the plugin.
 - `kubectl`, `jq`, `openssl`, and `podman` (or Docker) on your machine.
 - An LLM endpoint that accepts `Authorization: Bearer <token>` (e.g. a LiteLLM
   proxy) and the corresponding token.
@@ -102,9 +103,9 @@ endpoint exported once:
 
 ```bash
 cd examples/authbridge-egress
-export EXT_DIR=~/src/kagenti-extensions      # kagenti-extensions @ feat/placeholder-resolve-plugin
 export KAGENTI_DIR=~/src/kagenti             # kagenti repo (lets Step 1 redeploy the gateway)
 export LLM_URL=https://your-litellm.example.com
+# kagenti-extensions is cloned for you; set EXT_DIR=~/src/kagenti-extensions to reuse a local checkout
 ```
 
 The tenant namespace is `team1` and the kind cluster is `kagenti`. Override with the
@@ -122,15 +123,17 @@ merged to mainline**, so the images are built from local checkouts of those bran
 | authbridge-proxy (built here) | kagenti-extensions `feat/placeholder-resolve-plugin` (`ca8cbd8`) | `placeholder-resolve` + `inference-parser` (Anthropic) + the SSE-relay fix + the session API — all stacked on this branch |
 | gateway (prebuilt, pulled) | image tag `mvp-v2-7784be8` (commit `7784be8`, the base of `feat/authbridge-egress`) | the `inference-scoped-provider-lookup` fix — **not** in the chart default `v0.0.56-rc.3` |
 
-Until these branches are merged (or tagged), reproducing the demo means checking them
-out at (or after) the commits above and pinning the gateway tag as shown in Step 1.
+Until these branches are merged (or tagged), the supervisor is built from this OpenShell
+checkout and the plugin is cloned from `EXT_REPO`/`EXT_REF` (Step 1), with the gateway tag
+pinned as shown.
 
 ## Step 1: Build and load the images
 
 [`01-build-images.sh`](https://github.com/kagenti/OpenShell/tree/feat/authbridge-egress/examples/authbridge-egress)
-compiles the External-capable supervisor binary in a `rust:1.95` builder container,
-wraps it in a `scratch` image, builds the AuthBridge proxy image, loads both into kind,
-and — when `KAGENTI_DIR` is set — redeploys the `team1` gateway for you:
+clones the kagenti-extensions `placeholder-resolve` plugin (unless `EXT_DIR` points at a
+local checkout), compiles the External-capable supervisor binary in a `rust:1.95` builder
+container, wraps it in a `scratch` image, builds the AuthBridge proxy image, loads both into
+kind, and — when `KAGENTI_DIR` is set — redeploys the `team1` gateway for you:
 
 ```bash
 ./01-build-images.sh        # uses $EXT_DIR; with $KAGENTI_DIR set, also redeploys the gateway

examples/authbridge-egress/01-build-images.sh

@@ -6,8 +6,13 @@
 # load both into the kind cluster, and (optionally) point the tenant gateway at
 # them with the gateway tag correctly pinned.
 #
-# Env knobs (all optional except EXT_DIR):
-#   EXT_DIR           kagenti-extensions checkout (feat/placeholder-resolve-plugin)   [required]
+# Env knobs (all optional):
+#   EXT_DIR           Local kagenti-extensions checkout (feat/placeholder-resolve-plugin).
+#                     Used as-is if set; if unset, the script clones EXT_REPO @ EXT_REF.
+#   EXT_REPO          Repo to clone the plugin from when EXT_DIR is unset
+#                     (default: https://github.com/huang195/kagenti-extensions; switch to
+#                      https://github.com/kagenti/kagenti-extensions once PR #626 merges).
+#   EXT_REF           Branch/ref to clone (default: feat/placeholder-resolve-plugin; 'main' post-merge).
 #   KAGENTI_DIR       kagenti repo checkout. If set, this script also runs
 #                     deploy-tenant.sh to redeploy the gateway with the new
 #                     supervisor image and the pinned gateway tag. If unset, it
@@ -24,7 +29,9 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 OPENSHELL_DIR="${OPENSHELL_DIR:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-EXT_DIR="${EXT_DIR:?set EXT_DIR to your kagenti-extensions checkout (feat/placeholder-resolve-plugin)}"
+EXT_DIR="${EXT_DIR:-}"
+EXT_REPO="${EXT_REPO:-https://github.com/huang195/kagenti-extensions}"
+EXT_REF="${EXT_REF:-feat/placeholder-resolve-plugin}"
 ARCH="${ARCH:-arm64}"
 CLUSTER="${CLUSTER:-kagenti}"
 NS="${NS:-team1}"
@@ -38,6 +45,21 @@ case "$ARCH" in
   *) echo "unsupported ARCH '$ARCH' (use arm64 or amd64)" >&2; exit 1 ;;
 esac
 
+mkdir -p "$OUT"
+
+# Resolve the kagenti-extensions source for the AuthBridge image: use EXT_DIR if
+# given, otherwise clone EXT_REPO @ EXT_REF (the plugin is on an unmerged branch).
+if [ -z "$EXT_DIR" ]; then
+  EXT_DIR="$OUT/kagenti-extensions"
+  if [ -d "$EXT_DIR/.git" ]; then
+    echo "==> Updating $EXT_DIR ($EXT_REF from $EXT_REPO)..."
+    git -C "$EXT_DIR" fetch --depth 1 "$EXT_REPO" "$EXT_REF" && git -C "$EXT_DIR" checkout -f FETCH_HEAD
+  else
+    echo "==> Cloning $EXT_REPO ($EXT_REF) -> $EXT_DIR..."
+    git clone --depth 1 --branch "$EXT_REF" "$EXT_REPO" "$EXT_DIR"
+  fi
+fi
+
 # The supporting commits are NOT merged to mainline — fail fast if the checkouts
 # don't actually contain them, rather than silently building feature-less images.
 if ! grep -rqs "OPENSHELL_EXTERNAL_PROXY" "$OPENSHELL_DIR/crates/openshell-sandbox/src/"; then
@@ -47,12 +69,10 @@ if ! grep -rqs "OPENSHELL_EXTERNAL_PROXY" "$OPENSHELL_DIR/crates/openshell-sandb
 fi
 if [ ! -d "$EXT_DIR/authbridge/authlib/plugins/placeholderresolve" ]; then
   echo "ERROR: $EXT_DIR has no placeholder-resolve plugin." >&2
-  echo "       Check out the kagenti-extensions 'feat/placeholder-resolve-plugin' branch, or set EXT_DIR." >&2
+  echo "       Check EXT_REPO/EXT_REF, or point EXT_DIR at a checkout that has it." >&2
   exit 1
 fi
 
-mkdir -p "$OUT"
-
 echo "==> [1/4] Compiling the supervisor binary ($RUST_TARGET) in a builder container..."
 podman run --rm \
   -v "$OPENSHELL_DIR":/src:ro -w /src \

examples/authbridge-egress/README.md

@@ -30,23 +30,25 @@ Full walkthrough and concepts: **[docs/sandboxes/authbridge-egress.mdx](../../do
 
 1. A working OpenShell install with a `team1` tenant gateway, per the
    [Kagenti Sandbox Guide](https://github.com/kagenti/kagenti/blob/main/docs/sandbox-guide.md).
-2. **Check out the unmerged feature branches this integration depends on:**
-   - this repo (OpenShell) on **`feat/authbridge-egress`** (adds `NetworkMode::External`);
-   - a [kagenti-extensions](https://github.com/kagenti/kagenti-extensions) checkout on
-     **`feat/placeholder-resolve-plugin`** (the `placeholder-resolve` plugin).
-
-   `01-build-images.sh` fails fast if a checkout is missing its feature.
+2. **This OpenShell repo on the `feat/authbridge-egress` branch** (adds
+   `NetworkMode::External`) — you're already on it if you're reading this, and the
+   supervisor image is built from it.
+
+   The kagenti-extensions **`placeholder-resolve`** plugin is **cloned automatically** by
+   `01-build-images.sh` (from `huang195/kagenti-extensions @ feat/placeholder-resolve-plugin`
+   by default — override with `EXT_REPO`/`EXT_REF`, or set `EXT_DIR` to a local checkout).
+   The script fails fast if the resolved source is missing the plugin.
 3. `kubectl`, `jq`, `openssl`, and `podman` (or Docker).
 
 ## Quick start
 
 ```bash
 cd examples/authbridge-egress
 
-# Set these once: your checkouts + your upstream LLM endpoint.
-export EXT_DIR=~/src/kagenti-extensions        # kagenti-extensions @ feat/placeholder-resolve-plugin
+# Set these once: your kagenti checkout + your upstream LLM endpoint.
 export KAGENTI_DIR=~/src/kagenti               # kagenti repo (lets step 1 redeploy the gateway)
 export LLM_URL=https://your-litellm.example.com
+# kagenti-extensions is cloned for you; set EXT_DIR=~/src/kagenti-extensions to reuse a local checkout
 
 # 1. Build + load both images AND redeploy the team1 gateway (gateway tag auto-pinned),
 #    then log back in (the gateway restart expires your CLI token).
@@ -76,7 +78,9 @@ SANDBOX=<sandbox-name>
 
 | Var | Default | Used by |
 |-----|---------|---------|
-| `EXT_DIR` | _(required)_ | 01 |
+| `EXT_DIR` | _(optional — local kagenti-extensions checkout; else auto-cloned)_ | 01 |
+| `EXT_REPO` | `https://github.com/huang195/kagenti-extensions` | 01 |
+| `EXT_REF` | `feat/placeholder-resolve-plugin` | 01 |
 | `KAGENTI_DIR` | _(optional — if set, 01 auto-redeploys the gateway)_ | 01 |
 | `NS` | `team1` | 01, 02, 03, 04 |
 | `CLUSTER` | `kagenti` | 01 |