antigravity-native-e2e-dev

# Antigravity native harness: end-to-end dev & testing (local server/runner)

The `antigravity-native` harness wraps the **real Antigravity `agy` TUI** (the
`agy` CLI, installed from `antigravity.google/cli/install.sh`). `omnigent
antigravity` ensures a host daemon, the daemon-spawned **runner** launches `agy`
in a runner-owned **tmux** terminal, and your TTY attaches to it. This is **not**
the in-process `antigravity` Gemini-SDK harness — that one runs `google-antigravity`
with a Gemini *API key*; this one drives the OAuth-only `agy` CLI and mirrors it
over **connect-RPC**. This skill is the proven recipe for running it **for real
against a live local server + runner** — not just the unit tests.

> Like the other native harnesses, the runner imports from your **current
> checkout**, so testing here exercises exactly the code you're on. (CWD/venv
> selects the code, not `PYTHONPATH`.)

## What actually runs where

```
your TTY ── (attach / pexpect) ──► omnigent antigravity (CLI, local)
                                        │ ensures
                                        ▼
                                  host daemon ──► local Omnigent server (AP)
                                        │ spawns                      ▲
                                        ▼                  connect-RPC │ HTTP
                                  runner ── launches ──► agy (TUI, in tmux)
                                        │                              │
                                        ├── write path: type web turns into the TUI
                                        │   (tmux bracketed paste → real USER_INPUT step)
                                        └── read path: RPC read driver mirrors agy's
                                            trajectory steps back into the session
```

Three transports, easy to confuse:

1. **Write path = typing into the TUI.** Every web/mobile turn is *typed* into the
   agy pane via tmux (`inject_user_message_via_tui`), creating a real
   `CORTEX_STEP_TYPE_USER_INPUT` step on the **same** cascade the TUI shows
   (#1156/#1158). It is **not** delivered over `SendUserCascadeMessage` (that
   headless RPC path was retired; the `antigravity_native.py` module header still
   says "delivered via the RPC" — that's stale doc-lag, the executor is authoritative).
2. **Read path = RPC.** `antigravity_native_reader` polls/streams agy's connect-RPC
   trajectory steps and mirrors them into the Omnigent session.
3. **Control = RPC.** Interrupt is `CancelCascadeSteps`; a tool/permission prompt
   is answered via `HandleCascadeUserInteraction` (surfaced as an Omnigent
   elicitation).

## Prerequisites (check these first)

1. **You're on the branch you want to test**, running from that checkout
   (`.venv/bin/omnigent` / `.venv/bin/python` from this repo).
2. **The `agy` CLI is on PATH** (or at `~/.local/bin/agy`) — the harness can't
   launch without it:
   ```bash
   which agy || ls -l ~/.local/bin/agy
   agy --version
   # install if missing (shell installer, NOT npm):
   #   curl -fsSL https://antigravity.google/cli/install.sh | bash   # then restart shell
   .venv/bin/python -c "from omnigent.onboarding.harness_readiness import harness_is_configured; print('antigravity-native ready:', harness_is_configured('antigravity-native'))"
   ```
3. **`agy` is signed in (OAuth).** agy is **OAuth-only** — it has no `agy login`;
   you authenticate by running bare `agy` once and completing the browser sign-in.
   It **ignores `GEMINI_API_KEY`** (API-key auth belongs to the separate
   `antigravity` SDK harness). Verify (no secrets printed):
   ```bash
   .venv/bin/python -c "from omnigent.onboarding.gemini_auth import gemini_login_detected; print('agy oauth token present:', gemini_login_detected())"
   agy models   # exits 0 and lists models only when signed in; else 'Please sign in'
   ```
   `False` / non-zero → run `agy` once and sign in. agy's token lives under
   `~/.gemini` (`oauth_creds.json` on macOS through 1.0.10,
   `antigravity-cli/antigravity-oauth-token` on Linux); agy 1.1.7+ on macOS
   writes no token file and keeps the credential in the Keychain, which is why
   `gemini_login_detected()` falls back to `agy models` there.
4. **`tmux` is on PATH.** The agy terminal is a runner-owned tmux pane; the CLI
   attaches to it and the executor drives it via `tmux send-keys`
   (`_preflight_local_tools` hard-fails without tmux).
5. **Network egress to Google's Antigravity backend.** A turn that hangs / fails
   to connect on a locked-down host is usually egress, not a harness bug.

> No `node` and no provider/gateway config are needed here (unlike pi/cursor
> native): agy is a self-hosted binary and auth is the inherited Google OAuth.

## Step 1 — start a local server (real server + runner)

```bash
cd /path/to/omnigent
.venv/bin/omni server --background          # detached managed server on a free loopback port
.venv/bin/omni server status         # prints the URL, e.g. http://127.0.0.1:6767
SERVER=http://127.0.0.1:6767         # use the printed URL below
curl -s "$SERVER/health"             # {"status":"ok"}
```

(`omnigent antigravity --server ""` also auto-spawns a persistent local server and
uses it — handy for a one-shot manual run, but a known `$SERVER` URL is better for
scripted API observation below.)

## Step 2 — launch the agy terminal against the local server

`omnigent antigravity` **attaches an interactive TUI**, so run it where you can
hold it open. Two patterns:

**A. Background terminal (recommended for scripted drives).** Launch in one
terminal, drive/observe from another:

```bash
.venv/bin/omnigent antigravity --server "$SERVER" 2>&1   # attaches the agy TUI; leave it running
# add a model:  --model gemini-2.5-pro   ;   pass-through agy args go at the end
```

It prints `Web UI: <url>` and a resume hint to stderr — grab the conversation id
(the `…/c/<conv_…>` segment) for the API calls below:

```bash
CONV=conv_xxxxxxxx   # from the "Web UI:" line /