@estebanforge/pi-antigravity-bridge 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-07-29
+
+First release. A streaming Gemini model provider for pi, built on Google's
+`agy` CLI, plus an MCP tool bridge that lets agy use pi's installed tools
+(memory, codegraph, Slack, Asana, web, peer delegation, etc.) instead of its
+own. Registers `antigravity/*` models in pi's `/model` picker and streams
+responses by polling the SQLite database agy writes and decoding its
+protobuf step payloads. No generated protobuf code, no native SQLite
+dependency.
+
+### Added
+
+#### Streaming provider
+
+- **Gemini provider for pi.** `antigravity/gemini-*` models appear in pi's
+  `/model` picker, discovered live from `agy models` (with a fallback catalog
+  when discovery fails). Picking one routes each turn through the provider.
+- **Real streaming.** A concurrent poll loop (250ms, `PRAGMA data_version`
+  coalescing) reads agy's conversation DB while agy is still running, so text
+  and tool activity arrive during the turn, not replayed at exit. Three
+  trailing polls catch the final flush; abort skips them for prompt cancel.
+- **Hand-rolled protobuf decoder** for agy's `step_payload` blobs: agent text
+  at field 20.1, tool calls at field 5.4 (name@2/9, input@3), title at 30.4.
+  Field numbers verified against real agy 1.1.7 databases and cross-checked
+  against the shindgew/agy-acp and shubzkothekar/antigravity-acp decoders.
+  Unknown fields are skipped per protobuf wire rules.
+- **Multi-turn conversations.** A pi session is bound to an agy conversation
+  id (persisted at `~/.pi/agent/antigravity-bridge/sessions.json`) and
+  resumed via `--conversation <id>`. agy keeps its own history; only the latest
+  user message is sent each turn. Atomic, dirty-key-merged writes survive
+  concurrent pi processes.
+- **`/agy` slash command** with status, an interactive picker (mode,
+  permissions), and direct subcommands. Settings persist to
+  `~/.pi/agent/antigravity-bridge/config.json`.
+- **Configurable execution mode** (`accept-edits` default, or `plan`) and
+  permissions, overridable by `AGY_MODE` /
+  `AGY_SKIP_PERMISSIONS` env vars.
+- **`--dangerously-skip-permissions` passed by default.** Technically
+  required: `accept-edits` auto-approves file edits but not shell commands,
+  so a `run_command` would otherwise hang on an unanswerable `y/n` prompt in
+  non-interactive `-p` mode (upstream google-antigravity/antigravity-cli#318).
+  Consistent with pi's own no-confirmation-gate design.
+- **Conversation-id discovery** by snapshot/diff of agy's conversations dir
+  (agy `-p` never prints the id). Refuses to bind on ambiguity.
+- **Tool-activity visibility.** agy's closed tool loop surfaces in pi's
+  thinking panel as `[agy tool: <name>]`. agy edits/commands land on disk;
+  pi's tools never fire (architectural wall, documented).
+- **Cross-turn context continuity.** agy keeps its own history, but it now
+  also receives pi-side context it wasn't spawned for (compaction summaries,
+  turns from other providers or pi's own tools) as a brief digest with the
+  prompt each turn, so multi-turn work and provider switches stay coherent.
+- **Edit diffs in the thinking stream.** When agy writes a file, pi's thinking
+  panel shows a line-numbered diff of the change as it lands. Works across
+  nested repos, submodules, and multi-repo workspaces; degrades cleanly for
+  binary, off-repo, or unchanged files.
+- **Tests.** Unit tests for the protobuf decoder; a
+  deterministic fake-agy test that asserts events stream during the run and
+  that abort returns promptly (guards the "provider did not actually stream"
+  regression class).
+
+#### MCP tool bridge (agy -> pi tools)
+
+- **`AskAntigravity` tool** is now provided by this extension (ported from
+  `pi-ask-antigravity` v1.1.0). The bridge ships BOTH the streaming
+  antigravity provider AND the one-shot delegation tool - the same combined
+  shape as `pi-claude-bridge`. Model aliases (flash/pro/gemini, tier/version
+  qualifiers), one-shot vs continued-conversation modes, and the `mode`/
+  `digest` params are all preserved.
+- **Cross-extension clash avoidance.** When both this bridge and
+  `pi-ask-antigravity` are installed, the bridge wins and
+  `pi-ask-antigravity` silently registers nothing (it detects the bridge via
+  package resolution, order-independent). The `AskAntigravity` tool is never
+  duplicated.
+- **`/agy` gains `model` and `thinking` subcommands + picker rows** for the
+  tool's defaults (alias flash/pro/gemini; tier low/medium/high). Persisted
+  alongside the provider settings in `config.json`.
+- **MCP tool bridge.** agy runs as pi's Gemini provider; the bridge exposes
+  pi's installed tools to agy over a Streamable HTTP MCP server so agy can
+  call them (memory, codegraph, Slack, Asana, web, peer delegation, etc.)
+  instead of doing the work itself. Per-pid config directory at
+  `~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`, written into agy's
+  `--add-dir` path so agy reads `.agents/mcp_config.json` from there.
+  Global agy config is never touched.
+- **Capability gate.** The bridge checks for `pi.invokeTool` at startup and
+  silently no-ops the MCP server if the patch is absent (clean pi reinstall
+  drops the patch; bridge still runs as a provider).
+- **Tool filtering.** Builtin tools that agy already has natively (read,
+  write, edit, bash, ls, grep, find) are filtered out so agy does not double
+  up on its own equivalents; `AskAntigravity` is filtered to avoid recursion.
+  Every other registered tool is exposed.
+- **Security.** Shared-secret `x-bridge-token` header, request body size cap,
+  per-call `AbortController` so agy can cancel in-flight tool calls, full
+  request handler `try/catch`, rawHeaders rewrite for Hono's protocol clamp.
+
+#### Documentation
+
+- `docs/ARCHITECTURE.md` - bridge design and per-pid config layout.
+- `docs/DEVELOPMENT.md` - how to run tests, rebuild, and iterate.
+- `docs/PI-INVOKETOOL-PATCH.md` - the local patch to pi's dist that the
+  bridge depends on.
+- `docs/PI-BRIDGE-GAPS.md` - capability gaps, as actionable tasks (G1-G10).
+  G1 (conversation history) and G8 (edit diffs) are closed via no-patch,
+  provider/decode-side work; the rest (streaming progress, UI primitives,
+  MCP-server double-exposure, etc.) remain open, triaged by effort and payoff.
+
+### Fixed
+
+- **Protocol-version clamp for the MCP bridge.** agy negotiates a protocol
+  version newer than the SDK this bridge ships: `@modelcontextprotocol/sdk`
+  1.29.0 tops out at `2025-11-25`, but agy sends `2026-07-28`. `initialize` is
+  exempt from the transport's header check and the SDK downgrades its body
+  version itself, yet every follow-up (`tools/list`, `tools/call`,
+  `notifications/initialized`) is validated against the `MCP-Protocol-Version`
+  header and rejected with `400 Bad Request: Unsupported protocol version`,
+  surfaced as a `transport-error` on every turn. The bridge now rewrites any
+  unsupported header value to `LATEST_PROTOCOL_VERSION` before the transport
+  sees it. The server is stateless (a fresh transport per request), so it
+  cannot track the negotiated version across requests; clamping to LATEST is
+  the correct downgrade. Hono's Node->Web conversion reads `req.rawHeaders`,
+  not the parsed `req.headers` object, so the value is rewritten in the raw
+  array (and mirrored on `req.headers` for other readers).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EstebanForge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# pi-antigravity-bridge
+
+A Gemini model provider **and** the `AskAntigravity` delegation tool for [pi](https://github.com/earendil-works/pi-coding-agent), both built on Google's `agy` CLI. It registers `antigravity/gemini-*` models in pi's `/model` picker (streaming), and provides the `AskAntigravity` tool for one-shot delegation - the same combined shape as `pi-claude-bridge`.
+
+<img width="3024" height="1774" alt="image" src="https://github.com/user-attachments/assets/9fc2f368-7292-4dde-851b-db2bd579263c" align="center" />
+
+If you also have [`@estebanforge/pi-ask-antigravity`](https://github.com/EstebanForge/pi-ask-antigravity) installed, this bridge takes over: pi-ask-antigravity detects the bridge and registers nothing, so the `AskAntigravity` tool is never duplicated.
+
+## What it does
+
+You pick a Gemini model in pi's `/model` picker. pi routes each turn through this provider. The provider spawns `agy -p` in your workspace, polls the SQLite database agy writes as it works, decodes the protobuf step payloads, and streams the agent text back into pi token by token.
+
+Multi-turn works. The provider binds a pi session to an agy conversation id (persisted under `~/.pi/agent/antigravity-bridge/sessions.json`) and resumes it on the next turn via `--conversation <id>`. agy keeps its own history, so only the latest user message is sent each turn.
+
+## What it cannot do
+
+agy runs its own closed tool loop (`read_file`, `write_file`, `edit_file`, `run_command`) against `--add-dir`. By default pi's own `read`/`write`/`edit`/`bash` do not fire for agy's file and shell work, and that is fine: agy has capable native equivalents. What used to be a hard wall for everything else is now bridgeable; see [MCP tool bridge](#mcp-tool-bridge-agy-uses-pis-tools) below.
+
+Residual limits (with or without the bridge):
+
+- agy's own edits still land directly on disk; pi's inline diff review does not engage for them.
+- agy commands run without per-action approval, same as every other tool in pi. See [Permissions](#permissions) below.
+- No token usage or cost accounting. agy does not expose token counts, so usage reports as zero.
+
+## MCP tool bridge (agy uses pi's tools)
+
+While agy is the active model it normally cannot see pi's universe of extensions: agentmemory, codegraph, web search, slack/asana, the `Ask*` delegations, and any other installed pi tool. This extension optionally bridges that gap.
+
+When the capability is present the bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and `tools/call` executes them via `pi.invokeTool()`. agy discovers the server through a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the provider passes that dir as an extra `--add-dir` when it spawns agy. The user's global agy config (`~/.gemini/config/mcp_config.json`) is never touched, so standalone agy outside pi is unaffected.
+
+**Capability requirement.** `pi.invokeTool()` is not (yet) part of upstream pi. On first load with the patch missing, the extension **asks you once** whether to apply it (see [Install](#install)); once applied it activates after a full `pi` restart. Without it the bridge detects the missing capability at load time, skips the MCP server, and everything else works unchanged. See [docs/PI-INVOKETOOL-PATCH.md](docs/PI-INVOKETOOL-PATCH.md) for what the patch is, and `/agy patch status|apply|restore` to inspect, force, or undo it.
+
+**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. The `AskAntigravity` tool spawns its own agy with just the workspace, so that inner agy starts plain (no pi tools) and cannot re-enter. `AskAntigravity` is also filtered from the exposed tool list. Standalone agy is unaffected because nothing is written to its global config.
+
+**Cost / fan-out.** Every registered pi tool except builtins (and `AskAntigravity`) is exposed, including other delegation tools like `AskClaude`/`AskCodex`. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.
+
+**Security.** The MCP server binds to `127.0.0.1` only and requires a per-session shared-secret header (`x-bridge-token`) that agy sends from the bridge config; browsers cannot set custom headers on a simple cross-origin POST, so this blocks web CSRF against the loopback server. Request bodies are size-capped. This is intended for single-user developer machines: any local process running as the same user can read the token from the per-pid config and call the exposed tools, so do not run it on a shared host where you do not trust other same-user processes.
+
+## Install
+
+> ⚠️ **Heads-up: this extension patches your `pi` install.** When it loads and
+> the running pi lacks `pi.invokeTool()`, it **asks you once** whether to edit
+> files inside your globally-installed `@earendil-works/pi-coding-agent/dist/`
+> (adding one method) to enable the MCP tool bridge. This is, for now, the only
+> way agy can use Pi internal tooling.
+>
+> - **Yes** → applies the patch (reversible via `/agy patch restore`) and tells
+>   you to restart pi. The bridge starts on the next launch.
+>
+> - **No** → it remembers your choice and stays silent; it won't ask again until
+>   you run `/agy patch apply`. The provider and AskAntigravity tool keep working;
+>   only the MCP tool bridge stays off.
+>
+> - The apply is **idempotent & safe** (only what's missing; aborts cleanly if a
+>   pi update moved the code), **backed up** (under
+>   `~/.pi/agent/antigravity-bridge/pi-patch-backup/`), and **self-healing** (a
+>   `pi` reinstall/update wipes `dist/`; re-applied on the next start).
+>
+> The patch only takes effect after a **full `pi` restart** (quit + relaunch) —
+> `/reload` is **not** enough, because pi caches its compiled core for the
+> process.
+>
+> Details for the patch can be found in [docs/PI-INVOKETOOL-PATCH.md](docs/PI-INVOKETOOL-PATCH.md).
+
+Install with pi's package manager:
+
+```bash
+pi install npm:@estebanforge/pi-antigravity-bridge
+```
+
+Requires the **`agy` CLI** installed and authenticated. If you don't have it, follow Google's [official install guide](https://antigravity.google/docs/cli/install) for your platform, then run `agy` once to complete Google OAuth. The extension resolves `agy` on `$PATH`, or via the `AGY_BIN` environment variable.
+
+Also requires Node 22.5 or newer (uses the built-in `node:sqlite`).
+
+## Usage
+
+Pick a model and talk to pi as usual:
+
+```
+/model
+```
+
+Look for the models namespaced as: antigravity
+
+Or specify a model directly:
+
+```
+/model antigravity/gemini-3-6-flash-medium
+```
+
+Model ids are slugified from the `agy models` output (`Gemini 3.6 Flash (Medium)` becomes `gemini-3-6-flash-medium`). Discovery runs once at extension load. Run `/reload` after an `agy update` to refresh the list.
+
+If `agy models` fails at load (binary missing, auth not done, network stall), a fallback catalog still populates the picker so you get a clear runtime error instead of an empty list.
+
+### The /agy command
+
+`/agy` configures the provider at runtime. Settings persist to `~/.pi/agent/antigravity-bridge/config.json` and take effect on the next turn.
+
+```
+/agy                      status, or open the mode/permissions/model/thinking picker (TUI)
+/agy status               print current mode, permissions, model + session counts
+/agy mode plan            review-only: agy plans but writes nothing
+/agy mode accept-edits    agy applies edits directly (default)
+/agy permissions on|off   auto-approve / prompt for tool calls (see warning)
+/agy model flash|pro|gemini   default model alias for the AskAntigravity tool
+/agy thinking low|medium|high default thinking tier for the AskAntigravity tool
+/agy patch status|apply|restore   inspect / force / undo the pi.invokeTool patch
+/agy clear                drop all session bindings (force fresh conversations)
+```
+
+### Permissions
+
+pi itself has no built-in approval gate. Unlike codex, claude, or agy running interactively, pi does not prompt you to confirm each tool action before it runs. That is the host environment this extension lives in.
+
+Because agy in `-p` (print) mode cannot answer an interactive `y/n` prompt, this extension passes `--dangerously-skip-permissions` by default. It is technically necessary: `accept-edits` auto-approves file edits but not shell commands, so a `run_command` would otherwise hang forever waiting for a prompt nothing can answer (upstream [google-antigravity/antigravity-cli#318](https://github.com/google-antigravity/antigravity-cli/issues/318)). The net effect is that agy executes commands the same way pi already executes your other tools: without per-action review.
+
+If you want agy to execute nothing, use `/agy mode plan`. Do not combine `--sandbox` with skip-permissions ([#36](https://github.com/google-antigravity/antigravity-cli/issues/36)).
+
+### Run pi inside a sandbox
+
+For isolation when running any agent that executes commands without a confirmation gate, run pi inside [**construct-cli**](https://github.com/EstebanForge/construct-cli) - EstebanForge's sandbox for AI agents. Isolated container, no path escape, ephemeral filesystem, `strict` / `offline` network modes, secret redaction. The blast radius of a bad command stays in the container, not your host. Install and usage instructions are in that repo.
+
+### Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `AGY_BIN` | Path to the agy binary. Defaults to `agy` on PATH. |
+| `AGY_EXTRA_ARGS` | Extra args appended to every invocation. Whitespace-split. |
+| `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |
+| `AGY_MODE` | Override execution mode: `plan` (review-only) or `accept-edits` (default). Wins over the config file. |
+| `AGY_SKIP_PERMISSIONS` | `1`/`true` (default) to pass `--dangerously-skip-permissions` so commands don't hang on an unanswerable prompt in `-p` mode. `0`/`false` to prompt (hangs any `run_command` non-interactively). Wins over the config file. |
+| `AGY_DEFAULT_MODEL` | Default model alias for the `AskAntigravity` tool (`flash`/`pro`/`gemini`, or a tier/version qualifier). Wins over the config file. |
+| `AGY_DEFAULT_THINKING` | Default thinking tier for the `AskAntigravity` tool: `low`/`medium`/`high`. Anything else falls back to `medium`. Wins over the config file. |
+
+## Development
+
+Build, test, and debug instructions live in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). For the internal architecture (decode pipeline, polling, conversation discovery) see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## Terms of Service notice
+
+Google's [Antigravity ToS](https://antigravity.google/terms) (Section 6) prohibits accessing the service "in connection with products not provided by us", and names as its example using tools like Hermes/OpenClaw with Antigravity OAuth. That targets reusing your credentials in a non-Google harness that calls Google's backend directly.
+
+This extension does not do that. It spawns the official, unmodified `agy` binary as a subprocess; `agy` performs its own OAuth and makes its own calls to Google. This code never sees, extracts, or reuses your token, and never contacts Antigravity's backend. It only reads the local SQLite file `agy` writes. From Google's server-side view there is no signal that distinguishes "agy launched by pi" from "agy launched by a terminal, an IDE task runner, or cron": same signed binary, same authenticated calls.
+
+Google's reported enforcement to date (the February 2026 suspensions) targeted token-reuse tools, not spawning the official CLI.
+
+pi-antigravity-bridge practical risk is low, near zero. But not zero: the "in connection with" wording is broad, and Google can suspend accounts at its discretion regardless of whether a breach is provable. Grey area. Safe for now. You should read "news" about this online from time to time.
+
+This is engineering analysis, not legal advice. Use against your own Antigravity account at your own risk; I am not responsible for any consequence to your account.
+
+## License
+
+MIT.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,48 @@
+# Architecture
+
+How the provider works internally. For build/test/debug workflow see [DEVELOPMENT.md](./DEVELOPMENT.md).
+
+## Module map
+
+```
+extensions/index.ts   registerProvider + model discovery + /agy command (entry)
+src/provider.ts       streamSimple: pi Context -> agy turn -> pi event stream
+src/runner.ts         spawn agy -p, concurrent poll loop, abort/timeout, emit events
+src/poller.ts         read-only node:sqlite handle over one conversation DB
+src/protobuf.ts       hand-rolled varint walker + extractors (field 20.1 = text)
+src/discovery.ts      snapshot/diff to bind the conversation id agy never prints
+src/models.ts         agy models -> pi Model projection
+src/sessions.ts       atomic JSON store: pi session -> agy conversation + last step
+src/config.ts         persisted runtime config (mode, permissions, model/thinking defaults)
+src/ask-tool.ts       the AskAntigravity one-shot delegation tool (model/thinking defaults)
+src/mcp-server.ts     MCP tool bridge: exposes pi's tools to agy over Streamable HTTP
+src/patcher.ts        Auto-applies the pi.invokeTool local patch to enable the MCP tool bridge
+src/diff-render.ts    render agy's file edits as git diffs in pi's thinking stream
+```
+
+No generated protobuf code, no native SQLite dependency.
+
+## The decode pipeline
+
+agy writes each step to a SQLite row with a protobuf blob in `step_payload`. The text we want lives at field 20, submessage field 1. Tool calls live at field 5, submessage field 4, with the name at field 2 or 9 and the raw input JSON at field 3. These field numbers are reverse-engineered facts (cross-checked against the shindgew/agy-acp and shubzkothekar/antigravity-acp decoders, then verified against real databases on agy 1.1.7). They are load-bearing. Unknown fields are skipped per protobuf wire rules, so a future agy that adds fields will not break decoding.
+
+### Step types
+
+| step_type | meaning |
+| --- | --- |
+| 15 | agent text (payload field 20 -> field 1) |
+| 14 | thinking |
+| 23 | title update (payload field 30 -> field 4) |
+| 5, 7, 8, 9, 17, 21, 33, 101, 132, 138 | tool run (payload field 5 -> field 4 -> name@2/9, input@3) |
+
+Status 3 = complete; anything else = in-flight.
+
+## Polling
+
+The runner spawns `agy -p`, then polls its conversation DB on a 250ms interval concurrent with the running process (this is what makes the provider actually stream, not replay at exit). Each tick issues a single `PRAGMA data_version` check; while agy is thinking and has not committed, that check is false and no row SELECT runs at all (neither the new-row read nor the in-place re-read of the step agy is currently extending). Only when a commit lands do both reads fire in one pass. Three trailing polls at 100ms after agy exits catch the last flush; on abort these are skipped so cancellation is prompt.
+
+## Conversation id discovery
+
+agy `-p` does not print the conversation id. On a fresh run the runner snapshots the `*.db` stems in the conversations dir before spawn, then diffs after. Exactly one new file = ours; zero new = refuse to bind (surfaced as an error rather than a guess).
+
+When **more than one** new file appears (a concurrent agy or subagent started in parallel), the runner passes its spawned pid to `newConversationId`, which scans the process tree's open file descriptors (`/proc/<pid>/fd` on Linux) to find the single candidate `.db` our own agy is writing to. This is the authoritative disambiguator: mtime cannot separate two *active* concurrent runs, and the user-message payload (`step_type 98`) is undocumented and deeply nested, so content-matching would risk a silent misbind. When the pid is unavailable, the platform is not Linux, the process has already exited (the AskAntigravity tool binds post-exit), or the scan itself is ambiguous, discovery fails safe to null rather than guessing.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,64 @@
+# Development & Debugging
+
+How to build, test, and debug this extension outside pi.
+
+## Build, test, typecheck
+
+```bash
+npm install
+npm test          # unit tests (protobuf decoder, runner streaming/abort, mcp bridge)
+npm run build     # tsc --noEmit type check
+```
+
+The integration scripts below spawn a real `agy` process and need a logged-in account. The unit tests (`npm test`) need neither.
+
+## Standalone scripts
+
+These exercise the pipeline without pi. Useful for isolating where a bug lives (decoder? poller? provider? pi loader?).
+
+```bash
+# Decode any conversation DB and print agent text + tool calls.
+# Accepts a UUID (resolved against ~/.gemini/antigravity-cli/conversations/)
+# or an absolute path. Fastest way to check the protobuf decoder against
+# real data. No agy spawn, no network.
+npm run decode-db -- <uuid-or-path>
+
+# Spawn agy and stream decoded events to stdout with timestamps. Proves the
+# concurrent poll loop actually streams (events arrive during the run, not
+# only at exit). Use this to reproduce a hang or a missing-event bug.
+npm run run-agy -- "Say hello"
+npm run run-agy -- --model "Gemini 3.6 Flash (Medium)" --mode plan "Review src/protobuf.ts"
+npm run run-agy -- --conversation <uuid> "follow up"   # resume a turn
+
+# Drive the provider's streamSimple directly (no pi TUI) and assert the
+# full event lifecycle: start -> text_start -> text_delta -> text_end ->
+# done. The closest thing to a pi turn without pi.
+npx tsx scripts/test-provider.ts
+
+# Load the extension through a mock ExtensionAPI and assert registerProvider
+# + registerCommand (/agy) fire with the right shape. No agy spawn.
+npx tsx scripts/test-extension.ts
+
+# Load the extension through pi's REAL loader and confirm the antigravity/*
+# models register. This is the in-pi smoke test.
+npm run smoke:pi
+```
+
+## Debugging a hang or "stuck" turn
+
+Most "stuck" reports trace to one of:
+
+1. **agy blocked on a permission prompt.** `accept-edits` auto-approves file edits but NOT shell commands. Any `run_command` prompts `y/n`, which hangs forever in non-interactive `-p` mode. The provider passes `--dangerously-skip-permissions` by default to avoid this. If you turned it off (`/agy permissions off`), that is why. See the README Permissions section.
+2. **agy never started.** Check `AGY_BIN` is on PATH (or set explicitly). The runner swallows spawn ENOENT into the result's stderr, surfaced by the provider as an error event.
+3. **Conversation id never bound.** The snapshot/diff discovery refuses to bind if more than one new `.db` appears (ambiguous). `scripts/decode-db.ts` against the suspected DB confirms agy wrote steps.
+4. **Print-mode environmental hang.** `pi -p` can hang with zero output in some containers (upstream [google-antigravity/antigravity-cli#318](https://github.com/google-antigravity/antigravity-cli/issues/318)). It affects built-in providers too, not this extension. Validate the turn with `scripts/test-provider.ts` instead.
+
+## Regression tests worth knowing
+
+- `tests/protobuf.test.ts` - pure decoder math (varint, field walking, nested submessages).
+- `tests/runner-streaming.test.ts` - a fake agy writes rows on a delay; asserts events arrive DURING the run (not all at exit) and that abort returns promptly. This is the test that guards the "provider did not actually stream" class of bug.
+- `tests/mcp-server.test.ts` - the MCP tool bridge end-to-end against a real (port 0) server: capability gate, per-pid config lifecycle, shared-secret token gate, 1 MB body cap, protocol-version clamp, and tool-call dispatch through `pi.invokeTool`. Guards the security and transport-correctness of the bridge.
+
+## Module map
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the module map and the decode-pipeline / polling internals.

package/docs/PI-BRIDGE-GAPS.md

@@ -0,0 +1,186 @@
+# pi-antigravity-bridge: capability gaps
+
+Status of the MCP tool bridge between agy (Antigravity CLI, used as pi's Gemini
+provider) and pi's extension/builtin tools. This doc tracks **open gaps only**.
+Shipped work lives in `CHANGELOG.md` (most recently: a conversation-history
+delta digest, and git-sourced edit diffs). Ideas that were weighed and rejected
+are listed at the end under "Discarded ideas".
+
+## What the bridge already does
+
+agy -> bridge MCP server -> `pi.invokeTool(name, args)` -> pi's tool registry
+-> result returned through MCP -> agy model context. The chain was verified
+end-to-end with `memory_search` and `ask_user_question`. The bridge exposes
+pi's extension tools (builtins are filtered out since agy has native
+equivalents; `AskAntigravity` is filtered to avoid recursion).
+
+What this means in practice: agy can read/write files, use memory, navigate
+code with codegraph, search the web, post to Slack, create Asana tasks, spawn
+subagents, prompt the user with `ask_user_question`, and delegate to peer
+reviewers (Claude, Codex, Antigravity), all by going through pi's installed
+tooling instead of its own. Tools run in pi's process with pi's own credentials,
+so a secret never crosses the bridge. agy's file edits surface as git-sourced
+diffs in pi's thinking stream, and each turn agy receives a delta digest of
+pi-side context (compaction summaries, other-provider turns) it was not spawned
+for.
+
+## Open gaps
+
+Three gaps remain. Every one either needs a pi dist patch (the maintenance cost
+the shipped gaps deliberately avoided) or a verify-before-build step. Ordered by
+former G-number.
+
+**Numbering note:** the G1/G2/G3 labels below are this living doc's renumbered
+open set, NOT the historical G1-G10 in `CHANGELOG.md`. In that historical list
+G1 = conversation-history digest and G8 = edit diffs; both are now closed
+(shipped in 1.0.0) and so dropped from here, leaving the three renumbered below.
+
+---
+
+### G1. Stream progress for long tool calls [HIGH IMPACT]
+
+**Status:** Open
+**Objective:** Stop blocking on long tools (`web_research`, `librarian`,
+`codegraph_explore` on big repos). Push partial output back to agy so pi's UI
+shows live progress instead of a frozen spinner.
+
+**Why:** Today the bridge blocks until the tool returns. The user has no signal
+that work is happening. This is partly a pi-side gap (most long tools do not
+emit progress) and partly a bridge-transport gap.
+
+**Scope:**
+- `docs/PI-INVOKETOOL-PATCH.md`: expose pi's progress bus.
+- `src/mcp-server.ts`: switch from blocking `invokeTool` to a streaming RPC
+  using MCP `notifications/progress` (or a `pi_tool_progress` SSE channel).
+- pi-side: audit long tools and add progress emission where missing.
+
+**Acceptance criteria:**
+- [ ] A tool that runs >1s emits at least one progress notification.
+- [ ] pi's TUI spinner updates during the call, not only on completion.
+- [ ] Result content is identical to the blocking path (no data loss).
+- [ ] Fallback: if a tool does not emit progress, behavior matches today.
+
+**Effort:** Large. Touches pi's progress bus and the MCP transport.
+
+**Blocks:** None. **Blocked by:** None.
+
+---
+
+### G2. Expose pi's UI primitives [MEDIUM-HIGH IMPACT]
+
+**Status:** Open
+**Objective:** Let agy drive pi's native UI: confirm dialogs, toasts,
+file/directory pickers, status/footer updates.
+
+**Why:** agy can already `ask_user_question`. Missing: confirm/permission
+dialog for destructive ops (agy falls back to its own out-of-theme dialog),
+notification toast (for "task started" / "save ok"), native file picker
+(replaced today by asking for a path in text), and status-bar updates
+("Antigravity: working on X"). Note: this does NOT unlock a native diff viewer
+for agy edits, that path is structurally closed (see G8 in `CHANGELOG.md`).
+
+**Scope:**
+- `docs/PI-INVOKETOOL-PATCH.md`: expose `AgentSession.ui` helpers.
+- `src/mcp-server.ts`: wrappers for `pi_confirm`, `pi_notify`,
+  `pi_select_file`, `pi_select_directory`, `pi_set_status`.
+
+**Acceptance criteria:**
+- [ ] `pi_confirm(message)` pops pi's native confirm UI and returns boolean.
+- [ ] `pi_notify(message)` shows a toast.
+- [ ] `pi_select_file`/`pi_select_directory` return chosen paths or null.
+- [ ] `pi_set_status(text)` updates the footer; clears on empty string.
+- [ ] Tests cover each primitive with a mocked `ui` seam.
+
+**Effort:** Medium-large. Each primitive is a small pi patch plus a wrapper.
+
+**Blocks:** None. **Blocked by:** None.
+
+---
+
+### G3. Lifecycle event subscription [MEDIUM IMPACT]
+
+**Status:** Open
+**Objective:** Let a long-lived agy session observe pi events: `turn_start`,
+`turn_end`, `tool_call`, `tool_result`, `compaction`.
+
+**Why:** Today the bridge handles only `session_start` and `session_shutdown`.
+agy is fire-and-forget per turn. Event subscription would enable a class of
+"observer" tooling.
+
+**Caveat:** agy is request-response per turn (`-p`), not event-reactive. Before
+building, confirm there is a real consumer that can act on an async event
+stream; otherwise this risks the same "no consumer" failure that sank
+file-watching (see Discarded ideas).
+
+**Scope:**
+- `docs/PI-INVOKETOOL-PATCH.md`: add an event-emitter seam on `AgentSession`.
+- `src/mcp-server.ts`: `pi_subscribe(event)` returns a stream id; an SSE
+  channel pushes events.
+
+**Acceptance criteria:**
+- [ ] `pi_subscribe("tool_call")` returns a stream id and subsequent tool calls
+  arrive on the channel.
+- [ ] Unsubscribe cleans up the stream (no leak).
+- [ ] At least three event types supported at close.
+- [ ] No perf regression on the event hot path.
+
+**Effort:** Large. Non-trivial pi-side patching.
+
+**Blocks:** None. **Blocked by:** Confirm a real event-driven consumer exists.
+
+---
+
+## Discarded ideas (not worth it)
+
+Weighed and rejected; kept here as a graveyard so they are not re-proposed. Full
+reasoning is in project memory.
+
+- **Expose pi's other MCP clients** — REMOVED. pi has no native
+  MCP-client support and no MCP extension is in use, so there are no pi
+  MCP-client tools to double-expose. The bridge already surfaces every tool pi
+  actually registers.
+- **Refresh tool list mid-session** — DECLINED. The bridge already
+  re-queries `pi.getAllTools()` on every `tools/list` (stateless server), and
+  agy reconnects and re-lists every turn (`-p`), so a tool registered
+  mid-session appears next turn. The heartbeat would only help a long-lived
+  client that caches the list, and there is none.
+- **Settings, env, and secrets access** — DECLINED. Tools exposed via
+  the bridge run in pi's process (`pi.invokeTool` -> `tool.execute`) and
+  self-authenticate with pi's own credentials, so agy already uses pi's creds
+  for every tool; a credential never crosses the bridge. A `pi_get_setting`
+  accessor was predicated on credential reuse that does not apply.
+- **Image / binary content blocks** — NOT NEEDED. pi shares the
+  path to any image it produces (e.g. `/tmp/pi-clipboard-<uuid>.png`), and agy
+  reaches and reads those files directly via the bridge's `read` tool, so
+  returning image content blocks over the transport would duplicate a path
+  that already works end-to-end. No agy transport change or pi patch required.
+- **File-watching / live state** — DECLINED. agy is request-response
+  per turn, not event-reactive; nothing consumes a file-watch SSE stream, and
+  re-reads are cheap and correct. Watchers would add inotify/FSEvents handles,
+  races, and cleanup for no gain.
+
+## How to close a gap
+
+For each open gap, the default shape:
+
+1. Identify the pi-side API to expose (or add).
+2. Extend the patch in `docs/PI-INVOKETOOL-PATCH.md` with a read (or write)
+   accessor.
+3. Add a bridge tool wrapper in `src/mcp-server.ts` that calls the patched API.
+4. Register the tool name with the bridge (it appears in agy's tool catalog on
+   the next session).
+5. Add a test under `tests/mcp-server.test.ts` that round-trips a real call.
+6. Tick the gap's acceptance checkboxes.
+
+Most need no change to agy, only the bridge (and, for some, pi's dist). Note:
+the two shipped gaps were closed without any pi dist patch or new MCP tool, by
+working provider/decode-side (`src/provider.ts`, `src/diff-render.ts`); the
+shape above is a default, not a requirement.
+
+## Cross-references
+
+- `docs/ARCHITECTURE.md` — bridge design and per-pid config layout.
+- `docs/PI-INVOKETOOL-PATCH.md` — the local patch to pi that this whole
+  feature depends on.
+- `docs/DEVELOPMENT.md` — how to run tests, rebuild, and iterate.
+- `CHANGELOG.md` — shipped work (conversation-history digest, edit diffs).