pi-native-e2e-dev

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

The `pi-native` harness wraps the **real Pi coding-agent TUI**
(`@earendil-works/pi-coding-agent`, the `pi` CLI). Unlike the SDK harnesses
(cursor / copilot / antigravity), it does **not** run in-process: `omnigent pi`
ensures a host daemon, the daemon spawns a **runner** that launches `pi` inside a
runner-owned **tmux** terminal, and your TTY attaches to it. Omnigent's web-UI
turns are forwarded into that live `pi` process through a **file-inbox bridge** +
a packaged **JS extension** (`pi.sendUserMessage`). 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 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 pi (CLI, local)
                                        │ ensures
                                        ▼
                                  host daemon ──► local Omnigent server (AP)
                                        │ spawns                      ▲
                                        ▼                             │ HTTP
                                  runner ── launches ──► pi (TUI, in tmux)
                                                              │ loads
                                                              ▼
                                                 omnigent pi-native extension (JS)
```

Two ways a turn reaches Pi — test both:

1. **Type in the TUI** (your attached terminal). Exercises Pi natively; the
   extension mirrors the transcript back to the server (`POST …/events`).
2. **Web / API message.** Server → runner → **`PiNativeExecutor.run_turn`** →
   `enqueue_user_message()` writes `inbox/<ordinal>_msg_*.json` → the resident
   extension polls the inbox → `pi.sendUserMessage(...)`. This is the
   harness-specific path most worth covering.

## Prerequisites (check these first)

1. **You're on the branch you want to test**, and running from that checkout
   (`.venv/bin/omnigent` / `.venv/bin/python` from this repo).
2. **The `pi` CLI is on PATH** — the harness can't launch without it:
   ```bash
   which pi && pi --version
   # install if missing:  npm install -g @earendil-works/pi-coding-agent
   # or point at an explicit binary:  export OMNIGENT_PI_PATH=/path/to/pi
   .venv/bin/python -c "from omnigent.onboarding.harness_readiness import harness_is_configured; print('pi-native ready:', harness_is_configured('pi-native'))"
   ```
3. **`tmux` is on PATH.** The native wrapper attaches your TTY to the
   runner-owned Pi tmux pane (`_preflight_local_tools` hard-fails without it).
4. **`node` is on PATH.** The extension is JS executed inside Pi (also required
   by the e2e extension tests). `node --version`.
5. **Auth is resolvable (booleans/ids only — never print keys).** Native Pi
   normally logs in from its own `~/.pi/agent`. Omnigent bridges the provider you
   set with `omnigent setup` instead, writing a managed per-session `models.json`
   and passing `--provider omnigent --model <resolved>`. Verify what it will use:
   ```bash
   .venv/bin/python -c "from omnigent.pi_native_credentials import resolve_pi_native_provider as r; p=r(); print('provider:', getattr(p,'provider_id',None), '| api:', getattr(p,'api',None), '| model:', getattr(p,'model',None))"
   ```
   `None` → no omnigent provider configured; Pi falls back to its own `/login`
   (run `omnigent setup`, or log into `pi` directly). A Databricks default
   resolves to the AI-Gateway `anthropic-messages` surface with a refreshed
   bearer token.
6. **Network egress to the model backend.** A turn that hangs/fails to connect on
   a locked-down host is usually egress, not a harness bug.

## 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 pi --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 native Pi terminal against the local server

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

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

```bash
.venv/bin/omnigent pi --server "$SERVER" 2>&1   # attaches the Pi TUI; leave it running
```

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

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

**B. PTY driver (fully automated).** Drive it under `pexpect` exactly like the
`claude-native-e2e-test` skill's `cuj_driver.py` (a proven, generalizable base):
spawn `omnigent pi --server <url>` in a PTY with `cwd=<checkout>`, capture the
conv id from the printed URL, send keystrokes / poll the API, then **tear down
the whole process tree** (see Teardown — pexpect Ctrl-C only *detaches* tmux).

Pass-through Pi CLI args go after the command (persisted as
`terminal_launch_args`), e.g. `omnigent pi --server "$SERVER" -- --model <id>`;
omnigent still injects `--provider omnigent --model <resolved>` when a provider
is configured (see `pi_native_credentials.py`).

## Step 3 — drive a turn (and smoke-test)

**Via the web/bridge path (exercises `PiNativeExecutor`).** Post a user message
to the running session; the runner routes it through the harness → bridge inbox →
extension → `pi.sendUserMessage`: