@estebanforge/pi-antigravity-bridge 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.2] - 2026-09-01
+
+### Removed
+
+- The `legacy-sqlite` fallback engine: `src/runner.ts`, `src/poller.ts`, `src/protobuf.ts`, the `run-agy` and `decode-db` scripts, and the `engine` config key / `AGY_ENGINE` env var. agy 1.1.18 changed step-row storage to a two-phase write (a placeholder row first, grown in place later); the polling engine read each row once as an empty placeholder and never re-read it, so turns completed with the full reply in the database and zero text in pi (issue #1). The engine decoded an undocumented storage format, so every agy storage change risked repeating that failure silently. The stream-json engine shares none of that code path; verified live against agy 1.1.18-era storage (1.1.23 installed). A stale `engine` value in an existing `config.json` is ignored.
+  Reported by @imatimba in #1. Thanks for the exact repro and the root-cause analysis; the report drove this removal.
+
+### Changed
+
+- `scripts/test-provider.ts` wires the stream-json driver explicitly (it exercised the legacy path implicitly before).
+- `tests/provider-streaming.test.ts` covers effort mapping against a fake driver. The legacy event-mapping tests died with the engine; stream-json event coverage lives in `tests/stream-roundtrip.test.ts`.
+
+## [1.3.1] - 2026-08-31
+
+### Changed
+
+- Docs-only release. README and package description now describe the 1.3.0 reality: `stream-json` engine as default, no-patch tool bridge, `/agy doctor` + `/agy patch-cleanup`, live token usage. The 1.3.0 tarball shipped the pre-rewrite README, so npm and the pi.dev package gallery still showed the patch-era docs; this republish refreshes the registry metadata.
+
+
 ## [1.3.0] - 2026-08-31
 
 ### Added

package/README.md

@@ -8,25 +8,25 @@ If you also have [`@estebanforge/pi-ask-antigravity`](https://github.com/Esteban
 
 ## 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.
+You pick a Gemini model in pi's `/model` picker. pi routes each turn through this provider. A single persistent `agy` process runs in your workspace; pi feeds it each turn, parses its stream-json events, and streams the agent text back into pi token by token. Token usage is live.
 
 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.
+agy runs its own closed tool loop (`read_file`, `write_file`, `edit_file`, `run_command`) against `--add-dir`. Its read-only steps (`view_file`, `list_dir`, `grep_search`, `find_by_name`) re-run as real pi builtins (`read`, `ls`, `grep`, `find`) so their cards render natively; mutating steps never execute in pi - they replay through a display-only `antigravity` wrapper tool. What used to be a hard wall for pi's other tools is 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.
+- No cost accounting: cost stays zero because agy runs on your subscription quota. Token usage is live.
 
 ## 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.
 
-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.
+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 a `tools/call` routes into pi's own tool loop via the round-trip described below. 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.
 
 **No patch required.** Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a `toolUse` stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.
 
@@ -36,7 +36,7 @@ The bridge starts a localhost MCP server inside pi's process. `tools/list` retur
 
 **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.
 
-### Native cards, wrapper replay, and skills (stream-json engine)
+### Native cards, wrapper replay, and skills
 
 Read-only agy steps (view_file, list_dir, grep_search, find_by_name) re-run as
 real pi builtins (`read`, `ls`, `grep`, `find`) when those builtins are active,
@@ -48,35 +48,12 @@ anything with side effects.
 
 When the bridge is on, agy also gets one `activate_skill` tool whose enum is
 your pi Agent Skills catalog; calling it returns the SKILL.md body. The bridge
-answers it directly, no pi round-trip. `/agy doctor` prints engine state,
-driver counters, bridge port, and the last lifecycle events without spending
-tokens.
+answers it directly, no pi round-trip. `/agy doctor` prints driver counters,
+bridge port, and the last lifecycle events without spending tokens.
 
 ## 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).
+> **No patch required.** The bridge runs on pi's public APIs only; the extension never edits your pi install. If an older version of this extension patched your pi (adding `pi.invokeTool()`), the leftover is inert and a pi update removes it. The extension detects it once and offers `/agy patch-cleanup` to restore the original files from the backup immediately.
 
 Install with pi's package manager:
 
@@ -86,8 +63,6 @@ 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:
@@ -108,17 +83,16 @@ Model ids are slugified from the `agy models` output (`Gemini 3.6 Flash (Medium)
 
 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.
 
-### Engine and bridge surface
+### Bridge surface
 
-`config.json` selects the turn engine and the bridge surface:
+`config.json` selects the bridge surface:
 
 | Key | Values | Default |
 | --- | --- | --- |
-| `engine` | `stream-json` (persistent agy process, toolUse round-trips, live usage) or `legacy-sqlite` (spawn `agy -p`, poll its SQLite) | `stream-json` |
 | `bridgeTools` | `none` (bridge off), `mcp` (pi-mcp-adapter tools), `all` (every non-builtin tool, incl. other `Ask*` delegations) | `mcp` |
 | `digest` | `off` (stable prompts; agy's prompt cache hits) or `on` (inject a delta of pi-side context - compaction summaries, other-provider turns - into each agy prompt; the delta changes every turn, so agy re-bills the full context). Enable for mixed-provider sessions where agy must see pi-side context | `off` |
 
-Env overrides: `AGY_ENGINE`, `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`. The `legacy-sqlite` engine is kept as a fallback and is scheduled for removal once the stream-json engine has burned in.
+Env overrides: `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`.
 
 ### The /agy command
 
@@ -127,12 +101,14 @@ Env overrides: `AGY_ENGINE`, `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`. The `legacy-sqlit
 ```
 /agy                      status, or open the mode/permissions/model/thinking picker (TUI)
 /agy status               print current mode, permissions, model + session counts
+/agy doctor               bridge state, driver counters, bridge port, last lifecycle events
 /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 digest on|off        inject pi-side context into agy prompts (default off; see table above)
+/agy patch-cleanup        restore the original pi files if an older version patched them
 /agy clear                drop all session bindings (force fresh conversations)
 ```
 
@@ -140,7 +116,7 @@ Env overrides: `AGY_ENGINE`, `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`. The `legacy-sqlit
 
 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.
+Because agy runs non-interactively under this provider (nothing can answer a `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)).
 
@@ -162,13 +138,13 @@ For isolation when running any agent that executes commands without a confirmati
 
 ## 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).
+Build, test, and debug instructions live in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). For the internal architecture (engines, bridge round-trips, 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.
+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 what `agy` itself produces locally: its stream-json output. 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.
 

package/docs/ANTIGRAVITY-INTEGRATIONS.md

@@ -2,6 +2,8 @@
 
 Date: 2026-08-21. Sources: the official VSIX `Google.google-antigravity_1.0.0` (marketplace.visualstudio.com/items?itemName=Google.google-antigravity, unpacked at `~/Downloads/Google.google-antigravity_1.0.0`), Zed's external-agents registry cache (`~/Library/Application Support/Zed/external_agents/registry/registry.json`), the ACP release zip from `dl.google.com`, and the binaries installed on this machine. I verified everything below by direct inspection or live execution unless marked otherwise. Section 8 has the reproduction commands.
 
+> **2026-08-31 (1.3.0) update:** the roadmap sections below predate 1.3.0 and assume the `pi.invokeTool` patch (`src/patcher.ts`, `docs/PI-INVOKETOOL-PATCH.md`) stays. 1.3.0 removed the patch entirely: the MCP tool bridge now runs no-patch via the provider's toolUse round-trip, and `AGY_ENGINE=stream-json` (persistent process) is the default turn engine. Treat every patch-dependent step in sections 9.x as needing rework against the round-trip path; the reverse-engineered protocol facts (sections 1-8) are unaffected.
+
 ## 0. Executive summary
 
 Google ships two official mechanisms for driving Antigravity from an editor, plus one hidden one:

package/docs/ARCHITECTURE.md

@@ -2,46 +2,59 @@
 
 How the provider works internally. For build/test/debug workflow see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
+## Turn engine
+
+The provider runs one turn engine: a long-lived `agy --input-format stream-json --output-format stream-json` process per provider. Turns are fed over stdin; agy emits NDJSON events on stdout; the driver parses them and streams text into pi token by token. Conversation binding comes from the `init` event, tool steps arrive as typed events (no protobuf decoding), and token usage is live.
+
+Shared infrastructure: session binding (`sessions.json`), runtime config, the `AskAntigravity` tool, the MCP tool bridge surface, and the G1 context digest (off by default - see below).
+
 ## 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)
+extensions/index.ts   pi extension entry: provider registration, model discovery, /agy command, lifecycle notices
+src/provider.ts       streamSimple: pi Context -> agy turn -> pi event stream; owns the G9 round-trip store and the G1 digest
+src/driver.ts         stream-json driver: persistent agy process, turn serialization, conversation binding, idle/abort timers
+src/stream-events.ts  agy NDJSON event parser (init / step_update / result) + usage mapping onto pi's Usage
+src/native-tools.ts   maps agy read-only tool steps to real pi builtins (read/ls/grep/find) for native re-execution
+src/skills.ts         activate_skill bridge: exposes the pi Agent Skills catalog to agy, answered by the bridge directly
+src/patch-cleanup.ts  detects a leftover invokeTool patch from pre-1.3.0 installs; /agy patch-cleanup restores the backup
+src/discovery.ts      conversation-id binding for the AskAntigravity one-shot tool (agy -p never prints its conversation id)
+src/models.ts         agy models -> pi Model projection (full catalog, per-model effort)
+src/sessions.ts       atomic JSON store: pi session -> agy conversation + watermark
+src/config.ts         persisted runtime config (bridgeTools, digest, 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/mcp-server.ts     MCP tool bridge server: ferries tools/list + tools/call; calls park in the provider round-trip
 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.
+No generated protobuf code, no SQLite dependency.
 
-## The decode pipeline
+## Stream-json engine
 
-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.
+### Process and events
 
-### Step types
+The driver spawns `agy --input-format stream-json --output-format stream-json` once per provider and keeps it alive across turns (`/agy doctor` shows the reuse counter). A turn writes the prompt to stdin and reads NDJSON events until the terminal `result`:
 
-| step_type | meaning |
+| event | 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) |
+| `init` | conversation binding (`conversation_id`); the driver remembers it and resumes later turns via `--conversation <id>` |
+| `step_update` | `user_input` / `checkpoint` / `agent_response` / `tool` steps; agent text arrives as `text_delta` on live agy (1.1.13+), with `usage` attached |
+| `result` | terminal; live builds report status `SUCCESS` (older builds `OK` - both accepted) |
+
+Unknown event kinds parse as `{kind:"unknown"}` so a future agy release degrades instead of crashing the reader loop. Shapes were captured from live output and cross-checked against tianzuo/pi-antigravity `lib/events.ts` (MIT).
+
+Usage maps onto pi's `Usage` (input/output/thinking/cache-read tokens); cost stays zero because agy runs on subscription quota.
+
+### No-patch tool round-trip (G9)
 
-Status 3 = complete; anything else = in-flight.
+The MCP bridge server executes no tools itself. A `tools/call` parks in the provider's round-trip store; the provider ends the current pi assistant message with a `toolUse` stop reason for the real pi tool; pi executes it in its own loop (native cards, permissions, hooks); the `toolResult` completes the parked MCP response on the next stream call. No pi patch, no privileged API.
 
-## Polling
+Display follows the same split: agy read-only steps (`view_file`, `list_dir`, `grep_search`, `find_by_name`) re-run as real pi builtins via `native-tools.ts`, so their cards render with pi's own renderers. Mutating and agy-specialty steps replay through a display-only `antigravity` wrapper tool - recorded output only, nothing re-executes. The skills bridge exposes one `activate_skill` tool whose enum is the pi Agent Skills catalog; the bridge answers it directly, no round-trip.
 
-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.
+### Context digest (G1)
 
-## Conversation id discovery
+By default the prompt agy receives is only the latest user message: agy keeps its own history. When `config.digest` is on (`AGY_DIGEST`, `/agy digest on`), the provider prepends a DELTA digest of pi-side context agy was not spawned for - compaction summaries, other-provider turns, pi-tool results. Off by default because the digest changes every turn and defeats agy's server-side prompt cache (~25-30k tokens re-billed per turn). Enable it for mixed-provider sessions where agy must see pi-side context; pure antigravity sessions gain nothing, and bridge round-trips deliver tool results through the bridge, not the digest.
 
-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).
+### Removed: the legacy-sqlite engine (1.3.2)
 
-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.
+The pre-1.3.0 engine (spawn `agy -p`, poll the SQLite conversation DB, decode protobuf step payloads) was removed in 1.3.2. agy 1.1.18 changed the step-row storage to a two-phase write (a metadata-only placeholder row that grows in place), which the polling decoder read once as an empty placeholder and never re-read: turns completed with the full reply in the database and zero text streamed to pi (issue #1, reported by @imatimba). The engine reverse-engineered an undocumented storage format, so every agy storage change risked repeating that silent failure. The stream-json engine shares none of that code path and is unaffected by storage-format changes. `AGY_ENGINE` and the `engine` config key are gone; a stale value in an existing `config.json` is ignored.

package/docs/DEVELOPMENT.md

@@ -6,7 +6,7 @@ How to build, test, and debug this extension outside pi.
 
 ```bash
 npm install
-npm test          # unit tests (protobuf decoder, runner streaming/abort, mcp bridge)
+npm test          # unit tests via vitest (no agy spawn, no network)
 npm run build     # tsc --noEmit type check
 ```
 
@@ -14,22 +14,9 @@ The integration scripts below spawn a real `agy` process and need a logged-in ac
 
 ## Standalone scripts
 
-These exercise the pipeline without pi. Useful for isolating where a bug lives (decoder? poller? provider? pi loader?).
+These exercise the pipeline without pi. Useful for isolating where a bug lives (driver? 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.
@@ -42,23 +29,30 @@ 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
+
+# Live smoke for the stream-json engine. OPT-IN: spends a little Antigravity
+# quota. Proves the persistent process: init binds a conversation, text deltas
+# arrive, the result settles, and a second turn reuses the process.
+AGY_LIVE=1 node --experimental-strip-types scripts/smoke-stream-json.mjs
 ```
 
 ## 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.
+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 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 spawner swallows spawn ENOENT into the result's stderr, surfaced by the provider as an error event.
+3. **Conversation id never bound.** On `stream-json` the `init` event carries the id, so a missing binding means the turn never produced a result event. `/agy doctor` prints the last lifecycle events.
 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.
+- `tests/stream-roundtrip.test.ts` - the stream-json engine pieces: NDJSON parser, native re-exec mapping, and the no-patch toolUse round-trip store.
+- `tests/provider-streaming.test.ts` - drives streamSimple with an injected fake driver (no agy) and asserts how pi's reasoning level maps onto the agy `--effort` tier (forward, clamp, omit).
+- `tests/provider-digest.test.ts` - the G1 context digest builder: injects pi-side context without replaying agy's own history.
+- `tests/patch-cleanup.test.ts` - legacy-patch detection and restore, real fs via tmpdirs, no mocks.
+- `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. The provider owns the tool catalog and the round-trip; the server only ferries list/call.
 
 ## Module map
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for the module map and the decode-pipeline / polling internals.
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the module map and the engine internals (stream-json events, no-patch round-trip).

package/docs/PI-BRIDGE-GAPS.md

@@ -2,71 +2,48 @@
 
 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".
+Shipped work lives in `CHANGELOG.md` (most recently, 1.3.0: the stream-json
+engine and the no-patch toolUse round-trip that replaced `pi.invokeTool`).
+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).
+agy -> bridge MCP server `tools/call` -> the call parks in the provider's
+round-trip store -> the provider ends the pi assistant message with a
+`toolUse` stop reason for the real pi tool -> pi executes it in its own loop
+(native cards, permissions, hooks) -> the `toolResult` completes the parked
+MCP response on the next stream call. No pi patch. 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.
+tooling instead of its own. Tools run in pi's process with pi's own
+credentials, so a secret never crosses the bridge, and a long call renders in
+pi's native UI while it runs. agy's file edits surface as git-sourced diffs in
+pi's thinking stream. A delta digest of pi-side context (compaction summaries,
+other-provider turns) is available but OFF by default (`/agy digest on`): the
+digest changes every turn and defeats agy's server-side prompt cache.
 
 ## 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.
+Two gaps remain. Both now sit on the no-patch round-trip path, so closing them
+means provider- or bridge-side work only; there is no pi dist patch to extend
+anymore. Ordered by impact.
 
-**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.
+**Numbering note:** the G1/G2 labels below are this living doc's renumbered
+open set, NOT the historical G-numbers. In the historical list (`CHANGELOG.md`
+and the comments in `src/provider.ts`) G1 = conversation-history digest
+(shipped 1.0.0, now opt-in via `config.digest`) and G9 = the no-patch toolUse
+round-trip (shipped 1.3.0).
 
 ---
 
-### 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]
+### G1. Expose pi's UI primitives [MEDIUM-HIGH IMPACT]
 
 **Status:** Open
 **Objective:** Let agy drive pi's native UI: confirm dialogs, toasts,
@@ -80,7 +57,9 @@ notification toast (for "task started" / "save ok"), native file picker
 for agy edits, that path is structurally closed (see G8 in `CHANGELOG.md`).
 
 **Scope:**
-- `docs/PI-INVOKETOOL-PATCH.md`: expose `AgentSession.ui` helpers.
+- pi-side: confirm a public API surface for these primitives. The old plan of
+  patching `AgentSession.ui` into pi's dist is dead; the bridge no longer
+  patches pi.
 - `src/mcp-server.ts`: wrappers for `pi_confirm`, `pi_notify`,
   `pi_select_file`, `pi_select_directory`, `pi_set_status`.
 
@@ -91,29 +70,30 @@ for agy edits, that path is structurally closed (see G8 in `CHANGELOG.md`).
 - [ ] `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.
+**Effort:** Medium-large, gated on pi exposing the primitives without a patch.
 
-**Blocks:** None. **Blocked by:** None.
+**Blocks:** None. **Blocked by:** pi-side API availability.
 
 ---
 
-### G3. Lifecycle event subscription [MEDIUM IMPACT]
+### G2. 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.
+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).
+**Caveat:** agy is still request-response per turn, even though the
+stream-json engine keeps one process alive across turns. 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`.
+- Provider-side event tap (no pi patch): relay pi event callbacks into the
+  bridge.
 - `src/mcp-server.ts`: `pi_subscribe(event)` returns a stream id; an SSE
   channel pushes events.
 
@@ -124,12 +104,20 @@ file-watching (see Discarded ideas).
 - [ ] At least three event types supported at close.
 - [ ] No perf regression on the event hot path.
 
-**Effort:** Large. Non-trivial pi-side patching.
+**Effort:** Large.
 
 **Blocks:** None. **Blocked by:** Confirm a real event-driven consumer exists.
 
 ---
 
+## Closed by 1.3.0 (moved out of the open set)
+
+- **Stream progress for long tool calls** (the former top open gap): closed by
+  the no-patch round-trip. Bridged tools no longer block inside the MCP
+  server; they execute as real pi tools in pi's own loop, so pi's native
+  card/spinner UX shows progress while the call runs, and the result content
+  is identical to the old blocking path.
+
 ## Discarded ideas (not worth it)
 
 Weighed and rejected; kept here as a graveyard so they are not re-proposed. Full
@@ -145,10 +133,10 @@ reasoning is in project memory.
   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.
+  the bridge run in pi's process 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
@@ -163,24 +151,19 @@ reasoning is in project memory.
 
 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.
+1. Identify the pi-side API (must be public; the bridge does not patch pi).
+2. Add a bridge tool wrapper in `src/mcp-server.ts` that parks a call through
+   the provider's round-trip store, or answers bridge-side when no pi tool is
+   needed (see `src/skills.ts` for that pattern).
+3. Register the tool name with the bridge (it appears in agy's tool catalog on
+   the next turn).
+4. Add a test under `tests/mcp-server.test.ts` that round-trips a real call.
+5. 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.
+Most need no change to agy, only the bridge or the provider.
 
 ## 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/ARCHITECTURE.md` — engine internals, round-trip design, per-pid config layout.
 - `docs/DEVELOPMENT.md` — how to run tests, rebuild, and iterate.
-- `CHANGELOG.md` — shipped work (conversation-history digest, edit diffs).
+- `CHANGELOG.md` — shipped work.