@estebanforge/pi-antigravity-bridge 1.2.6 → 1.3.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+
+- Stream-json engine: one persistent `agy --input-format stream-json` process per provider; conversation binding from the `init` event (no more SQLite snapshot diffing), native tool-step events (no protobuf decoding), and token usage mapped onto pi's usage when agy reports it. `AGY_ENGINE=legacy-sqlite` keeps the old engine for one release.
+- No-patch MCP tool bridge: bridge calls park in a round-trip store; the provider emits them as real pi `toolUse` turns, pi executes with native cards/permissions/hooks, and the toolResult completes the parked MCP response on the next stream call. `bridgeTools` config selects the surface: `none` / `mcp` (default) / `all`.
+- Native re-execution of agy read-only tools as real pi builtins (native cards, live output).
+- Display-only `antigravity` wrapper tool: mutating agy steps land as real toolCall/toolResult pairs via recorded-output replay.
+- Skills bridge: `activate_skill` tool exposing the pi Agent Skills catalog to agy, answered by the bridge directly.
+- `/agy doctor`: engine, bridge, driver counters, and lifecycle tail, zero tokens.
+- Legacy patch cleanup: `src/patch-cleanup.ts` detects a leftover invokeTool patch, one-time notice on session start, and `/agy patch-cleanup` restores the original files from the versioned backup.
+
+### Changed
+
+- The MCP tool bridge no longer patches pi. The `pi.invokeTool` round-trip is replaced by the provider-owned park/emit/resolve flow above.
+
+### Fixed
+
+- Live stream-json protocol shapes against real agy: terminal status is `SUCCESS` (not `OK`) and agent text arrives as `text_delta`. The first burn-in turn failed on both; both are pinned by a regression test.
+- Native re-exec tool calls include the `reasoning` argument pi requires on read/edit-class builtins; without it pi rejected every native `read` card at validation.
+- Peer-review round 2 (engine): parked bridge calls suspend the stdout idle timer (a >5-minute permission prompt no longer kills the turn); turn lifetimes are serialized (a second `run()` can no longer orphan an open turn); the cumulative-text guard points the right direction; a settled turn fails round-trips parked against it.
+- Peer-review round 2 (cleanup): backup selection prefers an exact version match over newest-by-mtime (stacked multi-version backups made legitimate restores refuse); `WrapperReplay` entries are single-use (no unbounded growth, no enumerable stale outputs); `rt`-kind round-trips are removed on turn death; the one-time leftover-patch notice is headless-safe (`ctx.hasUI` gate with stderr fallback) and set after surfacing, not before.
+
+### Removed
+
+- `pi.invokeTool` patch: `src/patcher.ts`, the load-time consent prompt, `/agy patch` subcommands, `docs/PI-INVOKETOOL-PATCH.md`, and the `invokeToolPatchDeclined` config flag.
+
+
 ## [1.2.6] - 2026-08-28
 
 ### Changed

package/README.md

@@ -8,27 +8,27 @@ 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. The default `stream-json` engine runs one persistent agy process in your workspace, feeds it each turn, parses its stream-json events, and streams the agent text back into pi token by token. Token usage is live. A `legacy-sqlite` fallback engine (spawn `agy -p`, poll its SQLite conversation DB, decode its protobuf steps) still exists; see [Engine and bridge surface](#engine-and-bridge-surface).
 
 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 on the `stream-json` engine; the `legacy-sqlite` fallback reports usage 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.
+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.
 
-**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.
+**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.
 
 **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.
 
@@ -36,31 +36,25 @@ When the capability is present the bridge starts a localhost MCP server inside p
 
 **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)
+
+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,
+so their cards render with pi's own renderers. Mutating and agy-specialty steps
+render through a display-only `antigravity` wrapper tool: its `execute()`
+replays the output agy already recorded, so the transcript gets proper
+toolCall/toolResult pairs without any double execution. Neither path re-runs
+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.
+
 ## 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:
 
@@ -92,6 +86,18 @@ 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
+
+`config.json` selects the turn engine and 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.
+
 ### 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.
@@ -99,12 +105,14 @@ If `agy models` fails at load (binary missing, auth not done, network stall), a
 ```
 /agy                      status, or open the mode/permissions/model/thinking picker (TUI)
 /agy status               print current mode, permissions, model + session counts
+/agy doctor               engine 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 engine table)
+/agy patch-cleanup        restore the original pi files if an older version patched them
 /agy clear                drop all session bindings (force fresh conversations)
 ```
 
@@ -112,7 +120,7 @@ If `agy models` fails at load (binary missing, auth not done, network stall), a
 
 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)).
 
@@ -134,13 +142,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 on the default engine, its SQLite conversation DB on the fallback engine. 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,27 +2,70 @@
 
 How the provider works internally. For build/test/debug workflow see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
+## Engines
+
+The provider runs one of two turn engines (`config.engine`, default `stream-json`):
+
+- **`stream-json` (default):** one 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.
+- **`legacy-sqlite` (fallback):** the pre-1.3.0 engine - spawn `agy -p`, poll its SQLite conversation DB on a 250 ms interval, decode the protobuf step payloads. Kept as a fallback and scheduled for removal once `stream-json` has burned in (`AGY_ENGINE=legacy-sqlite` selects it).
+
+Shared by both engines: 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/runner.ts         legacy engine: spawn agy -p, concurrent poll loop, abort/timeout, emit events
+src/poller.ts         legacy engine: read-only node:sqlite handle over one conversation DB
+src/protobuf.ts       legacy engine: hand-rolled varint walker + extractors (field 20.1 = text)
+src/discovery.ts      legacy engine: snapshot/diff + pid fd-scan to bind the conversation id agy -p never prints
+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 (engine, 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/patcher.ts        Auto-applies the pi.invokeTool local patch to enable the MCP tool bridge
+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 native SQLite dependency (`node:sqlite` covers the legacy engine's reads).
+
+## Stream-json engine (default)
+
+### Process and events
+
+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`:
+
+| event | meaning |
+| --- | --- |
+| `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)
+
+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.
+
+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.
+
+### Context digest (G1)
+
+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.
+
+## Legacy-sqlite engine internals
+
+The sections below describe the `legacy-sqlite` fallback only (`AGY_ENGINE=legacy-sqlite`). The stream-json engine shares none of this code path.
 
-## The decode pipeline
+### 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.
 
@@ -37,11 +80,11 @@ agy writes each step to a SQLite row with a protobuf blob in `step_payload`. The
 
 Status 3 = complete; anything else = in-flight.
 
-## Polling
+### 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
+### 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).
 

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
 ```
 
@@ -42,23 +42,32 @@ 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 (both engines). 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. On `legacy-sqlite` the snapshot/diff discovery refuses to bind if more than one new `.db` appears (ambiguous). `npm run decode-db` 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.
+- `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 runner (no agy) and asserts the exact event sequence: text/thinking close-on-switch, tool labels through the thinking block, empty-turn fallback.
+- `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/runner-streaming.test.ts` - (legacy engine) a fake agy writes rows on a delay; asserts events arrive DURING the run (not all at exit) and that abort returns promptly. Guards the "provider did not actually stream" class of bug.
+- `tests/protobuf.test.ts` - (legacy engine) pure decoder math (varint, field walking, nested submessages).
+- `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, legacy decode/polling).

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.