@estebanforge/pi-antigravity-bridge 1.3.3 → 1.4.0

package/docs/ARCHITECTURE.md

@@ -4,7 +4,9 @@ How the provider works internally. For build/test/debug workflow see [DEVELOPMEN
 
 ## 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.
+The provider ships two turn engines behind one contract (`TurnDriver`,
+`src/driver-types.ts`): the default **stream-json engine** (below) and the
+opt-in **ACP engine** (bottom of this doc). 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).
 
@@ -21,10 +23,15 @@ src/patch-cleanup.ts  detects a leftover invokeTool patch from pre-1.3.0 install
 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/config.ts         persisted runtime config (engine + acp block, 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 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
+src/diff-render.ts    stream-json: render agy's file edits as git diffs in pi's thinking stream; formatInlineDiff (no git) renders ACP's native diffs
+src/driver-types.ts   TurnDriver contract shared by both engines (request/handle/snapshot types)
+src/acp/jsonrpc.ts    NDJSON JSON-RPC 2.0 framing with line buffering and typed error results
+src/acp/connection.ts ACP server process + protocol (initialize, session/new+load, prompt with image/resource blocks, config options, cancel probing, auto permissions)
+src/acp/events.ts     session/update -> DriverActivity mapping (pure; probe-frame regressions pinned)
+src/acp/driver.ts     AcpDriver: serialized turns, remaining-budget timer pause, Gate D abort, connection-scoped exit handling, reconnect/agentInfo snapshots
 ```
 
 No generated protobuf code, no SQLite dependency.
@@ -58,3 +65,43 @@ By default the prompt agy receives is only the latest user message: agy keeps it
 ### Removed: the legacy-sqlite engine (1.3.2)
 
 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.
+
+## ACP engine (opt-in, official server)
+
+`config.engine: "acp"` (or `/agy engine acp`) routes turns through Google's
+official ACP server (`agy_acp_server.par`, registry id `antigravity-acp`)
+over JSON-RPC stdio. Off by default; stream-json remains the default and a
+supported secondary — phase-4 deletion is conditioned on upstream shipping
+usage fields (Gate B), per docs/ACP-ADOPTION-PLAN.md.
+
+Modules: `src/acp/jsonrpc.ts` (framing/correlation), `src/acp/connection.ts`
+(process + protocol methods + in-connection `auto` permission answering),
+`src/acp/events.ts` (update mapping, pure), `src/acp/driver.ts`
+(`AcpDriver`). Both engines implement `TurnDriver`; `provider.ts` depends on
+the interface only and is otherwise unchanged.
+
+Phase-2/3 additions (all ACP-only, verified live):
+
+- **Images**: pi image attachments ride as typed content blocks in the
+  prompt array; models advertise `input: ["text","image"]` only when the
+  engine is `acp` (decided at extension load). stream-json stays text-only.
+- **Digest delivery**: with `config.digest` on, ACP ships the G1 digest as
+  a native `embeddedContext` resource block (images → resource → text);
+  stream-json keeps it inline. Same cache churn either way.
+- **Tool display (Gate C)**: ACP tool steps render as thinking labels -
+  native re-exec and wrapper replay are retired on ACP turns (the server
+  already executed the tool). Edits render their server-supplied diff
+  (`tool_call content[]` → `formatInlineDiff`, no git subprocesses).
+- **Diagnostics**: the ACP snapshot reports reconnects (connections beyond
+  the first: Gate D kills + stale-exit replacements) and the handshake
+  `agentInfo` name/title; `/agy doctor` surfaces both.
+
+Engine-specific behavior: session ids are scoped per engine
+(`sid:<x>@acp`); model/effort ship as one full slug via
+`session/set_config_option` and are RE-APPLIED after every server restart
+(config does not persist); `session/load` history replay is swallowed (never
+live text); abort is teardown+kill+reload while `session/cancel` is
+unimplemented (RC01); usage tokens are absent (zero-usage fallback).
+Verified protocol shapes and the auth flow:
+docs/ACP-PROTOCOL-REFERENCE.md. Raw captures: `probe-logs/` (gitignored,
+local only).

package/docs/DEVELOPMENT.md

@@ -34,6 +34,35 @@ npm run smoke:pi
 # 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
+
+# Live smoke for the ACP engine through OUR driver stack. OPT-IN: spends a
+# little quota. Needs AGY_ACP_BIN (or acp on PATH) and a one-time
+# /agy acp-auth credential setup.
+AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
+  npx tsx scripts/smoke-acp.mjs
+
+# Live smoke for the Gate F bridge e2e: the real ACP server lists the bridge
+# catalog and completes a tool call through the registered mcpServers entry.
+AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
+  npx tsx scripts/smoke-acp-bridge.mjs
+
+# Live smoke for image prompts on the ACP engine: builds a 64x64 two-tone PNG
+# in-process and asserts the model identifies both halves through the full
+# driver stack.
+AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
+  npx tsx scripts/smoke-acp-image.mjs
+
+# Live probe: thought-chunk sparsity, tool_call content[]/rawInput shapes,
+# and the /plan command flow, captured to probe-logs/ (local only).
+AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
+  npx tsx scripts/probe-acp-phase2.mjs
+
+# Live parity run: the SAME scenario set (streaming, continuity, bridge
+# round-trip, effort switch, serialization, abort+recover, usage) through
+# BOTH engines. Needs the agy CLI AND the ACP binary. Spends ~13 flash-low
+# turns; prints a per-scenario matrix and exits non-zero on any mismatch.
+AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
+  npx tsx scripts/parity-live.mjs
 ```
 
 ## Debugging a hang or "stuck" turn
@@ -52,6 +81,10 @@ Most "stuck" reports trace to one of:
 - `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.
+- `tests/acp-jsonrpc.test.ts` - the JSON-RPC stdio session: id correlation, typed error results, server-to-client requests, notifications, line framing (partial frames buffered across chunk boundaries, garbage lines counted not fatal).
+- `tests/acp-events.test.ts` - ACP session/update mapping onto pi activities (text, thought, tool cards) and the session/load replay suppression.
+- `tests/acp-driver.test.ts` - the ACP driver over the fake server (`tests/helpers/fake-acp-server.mjs`, scenario-selected): happy flow, load-replay, permission auto-answer, Gate D abort (cancel probe, teardown, `cancelSupported` memory), the stale-exit race (a killed connection's late exit must not fail its replacement - `ACP_FAKE_SLOW_DEATH_MS`), auth errors, park/kickIdle timer pause with remaining budget.
+- `tests/acp-config.test.ts` - engine selection narrowing (`AGY_ENGINE`/`config.engine`), acp block parsing.
 
 ## Module map
 

package/docs/PI-BRIDGE-GAPS.md

@@ -1,133 +1,51 @@
 # 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, 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 `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, 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. The
-reverse direction is on by default (`/agy system-prompt off` to disable):
-pi's composed system prompt - its operating instructions plus the global
-agent-dir `AGENTS.md` and ancestor `AGENTS.md`/`CLAUDE.md` files - is
-prepended as a delimited block to the first prompt of each new agy
-conversation, once, so the prompt cache keeps hitting (G10 in
-`CHANGELOG.md`).
+Open capability gaps only — things the bridge cannot do today, each blocked
+on something outside this repo. For how the bridge works (engines, G9
+round-trip, digest), see [ARCHITECTURE.md](./ARCHITECTURE.md). For shipped
+work, see `CHANGELOG.md`. Historical gap labels (G1 digest, G8 edit diffs,
+G9 round-trip, G10 system prompt) live in the CHANGELOG and source comments;
+they are closed and not used here.
 
 ## Open gaps
 
-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.
+### pi UI primitives
 
-**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).
+**Status:** Open. **Blocked by:** pi exposing a public API surface for these
+without a patch (the old plan of patching `AgentSession.ui` into pi's dist is
+dead; the bridge no longer patches pi).
 
----
-
-### G1. 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`).
+file/directory pickers, status/footer updates. agy can already
+`ask_user_question`; missing are confirm/permission dialogs for destructive
+ops, notification toasts, native file pickers, and status-bar updates. This
+does NOT unlock a native diff viewer for agy edits — on stream-json that path
+is closed (G8 renders diffs as thinking text); on ACP the server supplies
+edit diffs in `tool_call content[]`, rendered the same way.
 
-**Scope:**
-- 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`.
+**Scope when unblocked:** wrappers in `src/mcp-server.ts`
+(`pi_confirm`, `pi_notify`, `pi_select_file`, `pi_select_directory`,
+`pi_set_status`), each parking through the provider round-trip; tests with a
+mocked `ui` seam per primitive.
 
-**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.
+### Lifecycle event subscription
 
-**Effort:** Medium-large, gated on pi exposing the primitives without a patch.
+**Status:** Open. **Blocked by:** a confirmed real consumer.
 
-**Blocks:** None. **Blocked by:** pi-side API availability.
-
----
-
-### 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`.
-Event subscription would enable a class of "observer" tooling.
-
-**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:**
-- 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.
+`turn_end`, `tool_call`, `tool_result`, `compaction`. Today the bridge
+handles only `session_start` and `session_shutdown`. Scope would be a
+provider-side event tap plus a `pi_subscribe(event)` bridge tool with an SSE
+channel.
 
-**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.
+**Caveat:** agy is request-response per turn even when the engine keeps a
+process alive. Before building, confirm a consumer that can act on an async
+event stream; otherwise this risks the same "no consumer" failure that sank
+file-watching (see graveyard).
 
-**Effort:** Large.
+## Discarded ideas (graveyard)
 
-**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
-reasoning is in project memory.
+Weighed and rejected; kept so they are not re-proposed.
 
 - **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
@@ -140,36 +58,19 @@ reasoning is in project memory.
   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 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
+  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 over the bridge** — 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.
+  Update (2026-09-04): user-provided image *attachments* now ride natively on
+  the ACP engine as typed prompt content blocks (see README, Two
+  engines); the stream-json CLI prompt stays text-only, and the bridge
+  direction above is unchanged.
 - **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 (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 or the provider.
-
-## Cross-references
-
-- `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.

package/extensions/index.ts

@@ -37,9 +37,12 @@ import {
 import { SessionStore } from "../src/sessions.js";
 import { ToolRoundTrips, WrapperReplay, createStreamSimple } from "../src/provider.js";
 import { AgyDriver } from "../src/driver.js";
-import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type BridgeTools, type ThinkingTier } from "../src/config.js";
+import { AcpDriver } from "../src/acp/driver.js";
+import { resolveAcpBinary } from "../src/acp/connection.js";
+import type { TurnDriver } from "../src/driver-types.js";
+import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
 import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
-import { startMcpServer, type McpServerHandle } from "../src/mcp-server.js";
+import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
 	ACTIVATE_SKILL_TOOL_NAME,
 	activateSkillSchema,
@@ -79,14 +82,54 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	const toolModels = toolModelsFromRaw(raw);
 	const usingFallback = discovered.length === 0;
 	const entries: AgyModelEntry[] = usingFallback ? FALLBACK_MODELS : discovered;
-	const models = entries.map(toPiModel);
+	// Engine latched at load: /agy engine takes effect on the next pi start
+	// (documented). Everything below resolves from THIS value - per-call
+	// config reads would let a mid-session flip leave ToolRoundTrips,
+	// kickIdle, and reentry pointing at the other engine (round-7 finding).
+	const engine: Engine = loadConfig().engine;
+	// Engine switching requires a restart, so the catalog-time engine read is
+	// authoritative for input advertising: image attach rides only when turns
+	// will run on the ACP engine (the legacy CLI prompt is text-only).
+	const modelInput: Array<"text" | "image"> = engine === "acp" ? ["text", "image"] : ["text"];
+	const models = entries.map((e) => toPiModel(e, modelInput));
 
 	const store = new SessionStore();
-	// Persistent stream-json engine + the no-patch pi-tool round-trip store.
-	// The MCP bridge parks calls here; the provider emits them as real pi
-	// toolUse turns and completes them from the next call's toolResult.
-	const driver = new AgyDriver();
-	const roundTrips = new ToolRoundTrips(driver);
+	// MCP bridge handle, declared early: the ACP engine reads the bridge port
+	// at session/new / session/load time.
+	let mcpHandle: McpServerHandle | null = null;
+	// Two turn engines behind one contract (plan §9): stream-json (tested
+	// default) and the official ACP server (opt-in via config.engine, off by
+	// default). Neither spawns anything until its first turn.
+	const legacyDriver = new AgyDriver();
+	const acpDriver = new AcpDriver({
+		bin: resolveAcpBinary(loadConfig().acp.bin),
+		log: (msg, data) =>
+			console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`),
+		mcpServers: () => {
+			const handle = mcpHandle;
+			if (!handle) return [];
+			// The bridge 403s any request without the shared-secret header; the
+			// legacy engine carries it via mcp_config.json, ACP via headers[].
+			return [
+				{
+					name: "pi-bridge",
+					type: "http",
+					url: `http://127.0.0.1:${handle.port}/mcp`,
+					headers: [{ name: TOKEN_HEADER, value: handle.token }],
+				},
+			];
+		},
+	});
+	// The active engine is resolved from the latched load-time value.
+	const activeDriver = (): TurnDriver => (engine === "acp" ? acpDriver : legacyDriver);
+	// The provider's stream-json slot gets the LEGACY driver explicitly - never
+	// activeDriver(), or a load-time acp engine would make deps.driver and
+	// deps.acpDriver the same object and break the engine identity check.
+	const driver = legacyDriver;
+	// The no-patch pi-tool round-trip store: the MCP bridge parks calls here;
+	// the provider emits them as real pi toolUse turns and completes them from
+	// the next call's toolResult.
+	const roundTrips = new ToolRoundTrips(activeDriver);
 	const replay = new WrapperReplay();
 	// Native re-exec only emits for builtins actually active in the session;
 	// anything else (or an unknown name) falls back to the wrapper card.
@@ -99,9 +142,20 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		}
 	};
 	// A settled turn cannot answer its parked calls; the driver never sees
-	// ToolRoundTrips, so the provider bridges the two here.
-	driver.onTurnEnd = () => roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
-	const streamSimple = createStreamSimple({ entries, store, driver, roundTrips, replay, nativeActive });
+	// ToolRoundTrips, so the provider bridges the two here (both engines).
+	const onTurnEnd = () => roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+	legacyDriver.onTurnEnd = onTurnEnd;
+	acpDriver.onTurnEnd = onTurnEnd;
+	const streamSimple = createStreamSimple({
+		entries,
+		store,
+		driver,
+		acpDriver,
+		roundTrips,
+		replay,
+		nativeActive,
+		engine,
+	});
 
 	pi.registerProvider("antigravity", {
 		name: "Antigravity (agy)",
@@ -122,7 +176,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		streamSimple,
 	});
 
-	registerAgyCommand(pi, { entries, store, usingFallback, driver, getMcpPort: () => mcpHandle?.port ?? null });
+	registerAgyCommand(pi, {
+		entries,
+		store,
+		usingFallback,
+		driver,
+		acpDriver,
+		engine,
+		getMcpPort: () => mcpHandle?.port ?? null,
+	});
 
 	// AskAntigravity tool: one-shot delegation to agy (ported from
 	// pi-ask-antigravity). When both extensions are installed, the bridge wins
@@ -153,7 +215,6 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// Calls park in the provider's round-trip store and complete through pi's
 	// normal toolUse loop (native cards, permissions, hooks) - no patch, no
 	// privileged API. Started on session_start, torn down on session_shutdown.
-	let mcpHandle: McpServerHandle | null = null;
 	pi.on("session_start", async (_event, ctx) => {
 		// Legacy cleanup: users who ran the old consent-gated patcher still
 		// carry pi.invokeTool in their installed pi. Inert, but tell them once
@@ -266,7 +327,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		mcpHandle = null;
 		await h?.close();
 		roundTrips.failAll("antigravity session shut down");
-		await driver.close("shutdown");
+		await legacyDriver.close("shutdown");
+		await acpDriver.close("shutdown");
 	});
 }
 
@@ -276,7 +338,10 @@ interface AgyCommandCtx {
 	entries: AgyModelEntry[];
 	store: SessionStore;
 	usingFallback: boolean;
-	driver: AgyDriver;
+	driver: TurnDriver;
+	acpDriver: AcpDriver;
+	/** Engine latched at extension load (see the provider wiring note). */
+	engine: Engine;
 	getMcpPort: () => number | null;
 }
 
@@ -293,6 +358,7 @@ function statusText(ctx: AgyCommandCtx): string {
 	const perm = config.skipPermissions ? "auto-approved (DANGEROUS)" : "prompt (hangs in -p)";
 	return [
 		"Antigravity bridge",
+		`  engine:        ${config.engine}${config.engine === "acp" ? " (official server, opt-in)" : ""}`,
 		`  models:        ${ctx.entries.length} ${source}`,
 		`  mode:          ${config.mode}`,
 		`  permissions:   ${perm}`,
@@ -304,7 +370,7 @@ function statusText(ctx: AgyCommandCtx): string {
 		`  digest:        ${config.digest ? "on" : "off"}`,
 		`  system prompt: ${config.systemPrompt ? "on" : "off"}`,
 		"",
-		"Subcommands: /agy mode plan|accept-edits, /agy permissions on|off, /agy model flash|pro|gemini, /agy thinking low|medium|high, /agy digest on|off, /agy system-prompt on|off, /agy clear",
+		"Subcommands: /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy model flash|pro|gemini, /agy thinking low|medium|high, /agy digest on|off, /agy system-prompt on|off, /agy acp-auth, /agy patch-cleanup, /agy clear",
 	].join("\n");
 }
 
@@ -312,7 +378,7 @@ function statusText(ctx: AgyCommandCtx): string {
 function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	pi.registerCommand("agy", {
 		description:
-			"Antigravity provider: status, doctor, mode picker, clear sessions. Usage: /agy [status|doctor|mode [plan|accept-edits]|digest on|off|system-prompt on|off|patch-cleanup|clear]",
+			"Antigravity provider: status, doctor, engine picker, mode picker, clear sessions. Usage: /agy [status|doctor|engine stream-json|acp|mode [plan|accept-edits]|permissions on|off|digest on|off|system-prompt on|off|acp-auth|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
 			const mode = cmdCtx.mode;
@@ -345,19 +411,60 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				);
 				return;
 			}
+			if (sub === "engine") {
+				if (val === "acp" || val === "stream-json") {
+					const next = saveConfig({ engine: val });
+					ui?.notify(
+						`engine set to ${next.engine}. Takes effect on the next pi start (or /reload).${next.engine === "acp" ? "\nRequires the official ACP server binary (AGY_ACP_BIN or acp.bin) and a one-time auth: /agy acp-auth" : ""}`,
+						"info",
+					);
+				} else {
+					ui?.notify(`current engine: ${loadConfig().engine}\nusage: /agy engine stream-json|acp`, "info");
+				}
+				return;
+			}
+			if (sub === "acp-auth") {
+				ui?.notify(
+					[
+						"ACP engine authentication (one-time):",
+						"1. Install the server binary (agy_acp_server.par from the ACP registry",
+						"   build URL) and point acp.bin or AGY_ACP_BIN at it.",
+						"2. Pick one credential path:",
+						'   - oauth-personal: put {"auth":{"type":"oauth-personal"}} in',
+						"     ~/.gemini/antigravity-acp/settings.json, run one turn, and open the",
+						"     login URL the server produces (headless: tunnel 127.0.0.1:<port>",
+						"     over ssh, then open the URL on your machine).",
+						'   - gemini-api-key: export GEMINI_API_KEY and set',
+						'     {"auth":{"type":"gemini-api-key"}} (headless-friendly; metered).',
+						"   The agent never reads or writes your credentials.",
+						"3. Run one turn; /agy doctor shows the server version when auth is OK.",
+					].join("\n"),
+					"info",
+				);
+				return;
+			}
 			if (sub === "doctor") {
 				const config = loadConfig();
-				const snap = ctx.driver.snapshot();
+				const engine = ctx.engine;
+				const snap = (engine === "acp" ? ctx.acpDriver : ctx.driver).snapshot();
 				const port = ctx.getMcpPort();
 				const lines = [
 					"Antigravity doctor (no tokens spent)",
+					`  engine:        ${engine}`,
 					`  bridge:        ${config.bridgeTools}${port ? ` (port ${port})` : " (not running)"}`,
-					`  driver:        ${snap.state}${snap.pid ? ` pid=${snap.pid}` : ""}${snap.conversationId ? ` conv=${snap.conversationId.slice(0, 8)}` : ""}`,
+					`  driver:        ${snap.state}${snap.pid ? ` pid=${snap.pid}` : ""}${snap.conversationId ? ` session=${snap.conversationId.slice(0, 8)}` : ""}`,
 					`  driver stats:  spawns=${snap.stats.spawns} turns=${snap.stats.turns} reused=${snap.stats.reused} recycles=${snap.stats.recycles}${snap.stats.lastRecycleReason ? ` (last: ${snap.stats.lastRecycleReason})` : ""}`,
 					`  sessions:      ${ctx.store.size} bound`,
 					`  models:        ${ctx.entries.length} ${ctx.usingFallback ? "FALLBACK (agy models failed)" : "discovered"}`,
 					`  config:        ${CONFIG_PATH}`,
 				];
+				if (snap.engine === "acp" && snap.acp) {
+					lines.push(
+						`  acp session:   ${snap.acp.sessionId ?? "(none)"}`,
+						`  acp server:    ${snap.acp.serverVersion ?? "unknown"}${snap.acp.agentTitle ? ` (${snap.acp.agentTitle})` : ""}`,
+						`  acp stats:     prompts=${snap.acp.prompts} created=${snap.acp.sessionsCreated} loaded=${snap.acp.sessionsLoaded} kills=${snap.acp.kills} reconnects=${snap.acp.reconnects} cancel=${snap.acp.cancelSupported === null ? "unprobed" : snap.acp.cancelSupported ? "supported" : "unsupported (kill+reload)"}`,
+					);
+				}
 				if (snap.lifecycle.length > 0) {
 					lines.push("  lifecycle (last 5):");
 					for (const entry of snap.lifecycle.slice(-5)) lines.push(`    ${entry}`);

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.3.3",
-  "description": "Streaming Gemini provider for pi, built on the agy CLI. Registers antigravity/* models in pi's /model picker; drives agy through its stream-json protocol (persistent process, tool round-trips, live usage).",
+  "version": "1.4.0",
+  "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. antigravity/* models in Pi's /model picker, no-patch MCP bridge: agy runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",
     "pi-extension",
     "antigravity",
+    "antigravity-acp",
     "agy",
     "gemini",
     "google",
+    "google-acp",
+    "acp",
+    "agent-client-protocol",
+    "mcp",
+    "mcp-server",
     "provider",
     "streaming"
   ],