agentleFS
Omni-CraftOmni-Craft/OmniCraft/.claude/skills/antigravity-native-e2e-dev/SKILL.md

antigravity-native-e2e-dev

Skill1 starsChanged 4 months agoApache-2.0View on GitHub

Spin up a live local OmniCraft server + runner and exercise the native Antigravity (agy) TUI harness (antigravity-native) end-to-end — launch the real `agy` CLI via `omnicraft antigravity`, drive turns through the web UI, smoke-test, and bug-bash. Load when developing, testing, or debugging the antigravity-native harness (omnicraft/inner/antigravity_native_executor.py, omnicraft/antigravity_native.py, antigravity_native_bridge.py, antigravity_native_rpc.py, antigravity_native_reader.py, antigravity_native_launch.py) or its agy launch / RPC mirror / tmux delivery / OAuth / MCP-relay behavior. NOT the in-process `antigravity` Gemini SDK harness.

  • Pipes a download into a shell
  • Reads credentials
  • Deletes or force-pushes
  • Sends data out

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 0 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    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 …

    line 40
  2. Very specific:

    Type-driven smoke: instead of the POST, type a prompt directly in the attached agy TUI and confirm it answers + mirrors to …/items.

    line 157
  3. Very specific:

    It's a TUI, not omni run: Use omnicraft antigravity.

    line 203
  4. Very specific:

    config.yaml's server: defaults to a remote server: Always pass --server "$SERVER" (or --server "" for local).

    line 206
  5. Very specific:

    Isolated HOME: Don't expect your real ~/.gemini to change — agy runs under <bridge_dir>/agy-home.

    line 214
  6. Very specific:

    Never print/echo the OAuth token: Use the boolean/agy models probes.

    line 220
  7. Very specific:

    Placeholder until cold-start: Before agy mints its real cascade id, bridge state holds an agy_conv_* placeholder and RPC is skipped.

    line 263
  8. Very specific:

    If you can't reach a ready agy TUI (missing agy, not signed in, no tmux, headless limits, no egress), say so — don't claim a turn passed.

    line 289

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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). omnicraft 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) ──► omnicraft antigravity (CLI, local)
                                        │ ensures
                                        ▼
                                  host daemon ──► local OmniCraft 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 OmniCraft session.
  3. Control = RPC. Interrupt is CancelCascadeSteps; a tool/permission prompt is answered via HandleCascadeUserInteraction (surfaced as an OmniCraft elicitation).

Prerequisites (check these first)

  1. You're on the branch you want to test, running from that checkout (.venv/bin/omnicraft / .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:
    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 omnicraft.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):
    .venv/bin/python -c "from omnicraft.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, antigravity-cli/antigravity-oauth-token on Linux).
  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)

cd /path/to/omnicraft
.venv/bin/omni server start          # 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"}

(omnicraft 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

omnicraft 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:

.venv/bin/omnicraft 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:

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

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

The runner owns the agy terminal: binding a runner auto-creates the antigravity terminal for the session, and the CLI reattaches rather than launching its own. Don't hand-launch a second agy against the same session — a double launch 500s and clobbers the runner's bridge state (web-turn injection then fails "bridge state is missing").

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

Via the web path (exercises AntigravityNativeExecutor). Post a user message to the running session; the runner routes it to the harness, whose _deliver types it into the agy TUI (real USER_INPUT step):

curl -s -X POST "$SERVER/v1/sessions/$CONV/events" \
  -H 'content-type: application/json' \
  -d '{"type":"message","data":{"role":"user","content":[{"type":"input_text","text":"Reply with exactly the single word: PONG"}]}}'

Then observe the mirrored transcript (the RPC read driver posts agy's steps back):

sleep 25
curl -s "$SERVER/v1/sessions/$CONV/items" | python -m json.tool | tail -40

A healthy run shows your user message and a non-empty assistant reply (PONG) mirrored into the session — proving the full stack: server → runner → executor → tmux paste → agy turn → connect-RPC read driver → transcript mirror. You'll also see the prompt + reply render in the attached agy TUI (parity is the whole point of the TUI-typing write path).

  • Type-driven smoke: instead of the POST, type a prompt directly in the attached agy TUI and confirm it answers + mirrors to …/items.
  • Model: select a model with agy's TUI /model; the next web turn echoes that choice (the executor reads it from the latest USER_INPUT step).

Inspect the bridge (debugging)

Per-session bridge state lives under a hashed dir (keyed by bridge id, which defaults to the OmniCraft conversation id):

.venv/bin/python -c "from omnicraft.antigravity_native_bridge import bridge_dir_for_bridge_id as d; print(d('$CONV'))"
# ~/.omnicraft/antigravity-native/<sha256(bridge_id)[:32]>/
#   state.json     <- {session_id, conversation_id (agy's real UUID once minted), active_turn_id}
#   tmux.json      <- {socket_path, tmux_target} the executor types into (send-keys)
#   bridge.json    <- token for the OmniCraft MCP relay (sys_* tools)
#   agy-home/.gemini/...  <- per-session ISOLATED HOME: a COPY of your OAuth token
#                            + onboarding markers + config/mcp_config.json (relay)

Key facts:

  • agy mints its own UUID cascade; a fresh launch seeds an agy_conv_* placeholder until cold-start StartCascades the real id and writes it to state.json (and PATCHes it as external_session_id). RPC calls against a placeholder are skipped — "not ready yet".
  • The isolated HOME (agy-home/) is why your real ~/.gemini is never touched: the relay's mcp_config.json and agy's per-session state live there. agy's /mcp panel should show ✓ omnicraft with the sys_* tools.
  • Env vars: HARNESS_ANTIGRAVITY_NATIVE_BRIDGE_DIR, HARNESS_ANTIGRAVITY_NATIVE_REQUEST_SESSION_ID.

Targeted scenarios

GoalHow
Web→TUI deliveryPOST a message (Step 3); confirm it renders in the agy TUI AND mirrors to …/items
Native tools (shell/edit/read)prompt agy to create→read→edit a file + run a command; confirm it touches disk
OmniCraft MCP relay (sys_*)in the agy TUI run /mcp → expect ✓ omnicraft; prompt agy to sys_session_list / spawn a sub-agent
Permission elicitationwith a tool that needs approval, agy's request-review surfaces as an OmniCraft elicitation (interaction bridge); answer it in the web UI and confirm the tool runs
Interruptmid-turn, hit stop in the UI → CancelCascadeSteps (RUNNING cascades only; a step WAITING on an interaction is unblocked by a DENY, not cancel)
Model echo/model in the TUI, then a web turn — confirm the new model is used (latest USER_INPUT step's planModel)
Resumestop, omnicraft antigravity --server "$SERVER" --resume "$CONV"; --resume (no value) opens the antigravity-native picker
Concurrency / leaksdrive several sessions; sweep for orphaned agy / tmux after teardown

Gotchas (these cost real time)

  1. It's a TUI, not omni run. Use omnicraft antigravity. The executor only delivers into the live agy pane — agy must be running (attached) for a turn to process.
  2. config.yaml's server: defaults to a remote server. Always pass --server "$SERVER" (or --server "" for local). If a local server rejects antigravity-native, it's stale — restart it from your checkout (allowlist: omnicraft/spec/_omnicraft_compat.py).
  3. OAuth-only. agy ignores GEMINI_API_KEY; if agy models says "sign in", no web turn will get a real answer. Run bare agy once first.
  4. tmux must be reachable from the CLI process for the direct attach; the executor's send-keys run on the runner side against the advertised socket.
  5. Isolated HOME. Don't expect your real ~/.gemini to change — agy runs under <bridge_dir>/agy-home. Look there (and ~/.gemini/antigravity-cli for agy's own conversation store) when debugging.
  6. Don't double-launch agy for a session — the runner owns the terminal (see Step 2).
  7. Turns take ~20–120s — wrap scripted waits/timeout generously.
  8. Never print/echo the OAuth token. Use the boolean/agy models probes.

Code & tests

  • Executor (write path — types into the TUI): omnicraft/inner/antigravity_native_executor.py
  • Harness wrap (harness: antigravity-native): omnicraft/inner/antigravity_native_harness.py
  • CLI launch / daemon-runner / tmux attach: omnicraft/antigravity_native.py (run_antigravity_native); CLI command antigravity(...) in omnicraft/cli.py
  • agy argv / auth-mode / permission flag: omnicraft/antigravity_native_launch.py
  • Bridge (state, tmux delivery, isolated HOME, MCP relay): omnicraft/antigravity_native_bridge.py
  • connect-RPC client (port discovery, send/cancel/interaction): omnicraft/antigravity_native_rpc.py
  • RPC read driver (trajectory mirror): omnicraft/antigravity_native_reader.py
  • Steps / interactions / audit: omnicraft/antigravity_native_steps.py, omnicraft/antigravity_native_interactions.py, omnicraft/antigravity_native_audit.py
  • OAuth detection: omnicraft/onboarding/gemini_auth.py
  • Design/plan docs: docs/antigravity-native-rpc-core-design.md, docs/antigravity-native-rpc-core-plan.md
.venv/bin/python -m pytest \
  tests/test_antigravity_native.py \
  tests/test_antigravity_native_bridge.py \
  tests/test_antigravity_native_launch.py \
  tests/test_antigravity_native_rpc.py \
  tests/test_antigravity_native_reader.py \
  tests/test_antigravity_native_steps.py \
  tests/test_antigravity_native_interactions.py \
  tests/test_antigravity_native_audit.py \
  tests/inner/test_antigravity_native_executor.py -q

Bug-bash (fan out)

Stress the harness against the same $SERVER: the web→TUI delivery path (lost / duplicated turns, the attended-TUI paste race), the RPC read mirror (does every agy step reach …/items? duplicates after a reader restart?), the MCP relay (sys_* reachable + gated), permission elicitations, interrupt (CancelCascadeSteps) vs. a WAITING-on-interaction step, model echo, resume, and orphaned agy/tmux after teardown. Cross-check the API — a start failure can leave the TUI empty while the session records an error.

Watch-outs from the code (verify live)

  • Placeholder until cold-start. Before agy mints its real cascade id, bridge state holds an agy_conv_* placeholder and RPC is skipped; a turn fired too early just queues into the TUI.
  • Permission gating is all-or-nothing + post-hoc. agy honors only --dangerously-skip-permissions (no firing pre-tool hook), so a headless launch auto-bypasses and the genuine OmniCraft gate is the elicitation + post-hoc audit (antigravity_native_audit), not a per-tool pre-empt.
  • Stale module header. antigravity_native.py's top docstring says web turns go over SendUserCascadeMessage RPC — the live executor types into the TUI instead (#1156/#1158). Trust antigravity_native_executor.py.

Teardown — non-negotiable

A pexpect Ctrl-C detaches from tmux; the runner, tmux server, and agy keep running. Tear down the process tree from the child PID (ps --ppid … → SIGTERM/SIGKILL) and separately tmux -S <sock> kill-server. Then verify:

.venv/bin/omni server stop                 # stop the managed server + local daemon
pgrep -af "(^|/)agy( |$)|harnesses\._runner|runner\._entry|tmux"   # confirm no orphans
# clean a session's bridge dir (incl. its isolated agy HOME) if you want a reset:
# rm -rf "$(.venv/bin/python -c "from omnicraft.antigravity_native_bridge import bridge_dir_for_bridge_id as d; print(d('$CONV'))")"

Honesty

If you can't reach a ready agy TUI (missing agy, not signed in, no tmux, headless limits, no egress), say so — don't claim a turn passed. The strongest evidence is the round trip observed over the API: your user message and a non-empty assistant reply mirrored into GET /v1/sessions/$CONV/items, plus the turn rendering in the attached agy TUI.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.