@estebanforge/pi-antigravity-bridge 1.4.10 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.0] - 2026-09-08
+
+### Added
+
+- First-run engine picker. The choice of engine is left to the user: on a fresh install (no `config.json`, no `AGY_ENGINE`), the first interactive pi start opens a modal that explains both engines - stream-json needs the `agy` CLI installed and authenticated; ACP needs a second Google sign-in plus a ~1.5 GB server binary downloaded from Google. stream-json is preselected as the default; `esc` defers (nothing is written, the modal reappears next start). Headless sessions and existing installs are never asked.
+- The ACP pick chains setup immediately instead of waiting for a restart: the ~1.5 GB server binary downloads right away (live percent in the status bar, phase milestones as chat lines), the Google sign-in opens when it lands, and a restart applies the engine. The next start's self-heal sees binary + auth settled and stays silent.
+- `/agy engine` with no arguments (TUI) opens the same picker modal with identical semantics: plan mode blocks acp, an acp pick chains the download + sign-in, same-engine picks ack, esc acknowledges. Direct `/agy engine acp|stream-json` and the headless usage line are unchanged.
+- Missing-CLI warning: while the stream-json engine is active and the `agy` binary cannot be found (PATH or `AGY_BIN`), every pi start warns with the official install URL (toast in the TUI, stderr headless) until the binary is detected. Auth state is not checked, presence only.
+
+### Fixed
+
+- The picker's ACP line no longer claims "adds image input and native diffs": tool-result images ride both engines (probe-verified 2026-09-07) and stream-json has its own diff rendering. A negative test pin keeps the claim from returning.
+
+### Changed
+
+- README streamlined: the engine capability table, switching, and setup/auth details moved to docs/ENGINES.md; the approval-gate mechanics, configuration, and sample extension moved to docs/APPROVAL-GATE.md. Both stay linked from the README, which now carries the quick surface and states that engine choice is the user's.
+- Dependencies: fast-uri 3.1.5 → 3.1.7 clears four high-severity advisories (repeated hostname percent-decoding SSRF, malformed IPv6 normalization SSRF, percent-encoded scheme and IDN host confusion; in-range lockfile bump under ajv's `^3.0.1`), qs 6.15.3 → 6.16.0 clears a moderate pair (via express, dev surface). npm audit reports zero.
+
 ## [1.4.10] - 2026-09-07
 
 ### Added

package/README.md

@@ -21,35 +21,13 @@ Multi-turn works. The provider binds a pi session to an agy conversation id (per
 Turns run through one of two engines behind the same provider surface (`config.engine`, default `stream-json`):
 
 - **stream-json** (default): the persistent `agy` CLI process. The tested default; live token usage; conversation resume via `--conversation`.
-- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows zero) and no cancel (abort tears the server down and reloads it next turn).
+- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows client-side ESTIMATES until Google ships usage; `acp.usageEstimate` off to keep zeros) and no cancel (abort tears the server down and reloads it next turn).
 
-Engine-dependent features: pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text. The `AskAntigravity` delegation tool is unaffected by `config.engine` and runs the `stream-json` CLI (`agy -p`) across both configurations.
+The choice of engine is left to the user, with the trade-offs explained in the tool: a first-run picker modal asks once on a fresh install (stream-json preselected; `esc` defers, and the modal reappears next start), and `/agy engine` with no arguments reopens it anytime. An `acp` pick downloads the ~1.5 GB server binary and starts the Google sign-in immediately; a restart applies the engine. With stream-json active and the `agy` binary missing, pi warns on every start until the binary is found.
 
-| Capability | `stream-json` (default) | `acp` (beta) |
-| --- | --- | --- |
-| Show thinking text | No (token count only, floor 64, no text body) | Yes (streams thought text via `agent_thought_chunk`; sparse on RC01 where reasoning often arrives in message text) |
-| Live token usage | Yes (live metrics from CLI step events) | No (absent in RC01, displays zero tokens) |
-| Image prompt input | No (CLI prompt is text-only; images dropped) | Yes (native image blocks forwarded to server) |
-| Image tool results | Yes (bridge tool results carry pixels; probe-verified 2026-09-07) | Yes (probe-verified 2026-09-05) |
-| Audio prompt input | No (dropped) | Protocol advertised (`promptCapabilities.audio: true`) |
-| Review-only plan mode | Yes (`--mode plan` review-only via `/agy mode plan`) | No (RC01 modes are permission levels; plan mode refused) |
-| Leading slash commands in prompt | Disabled via `--disable-slash-commands` (sent as plain text) | Server intercepts recognized commands (e.g. `/plan`) and executes them under the active policy |
-| Dynamic model / effort switch | Recycles process on model or effort change | Dynamic per-turn via `session/set_config_option` (no restart) |
-| Process lifecycle | 1 persistent `agy` process per provider; recycles on drift | 1 persistent server process hosting N sessions concurrently |
-| Session resume & persistence | Client-side map in `sessions.json` via `--conversation <id>` | Server-side session store via `session/load` and `session/new` |
-| Turn cancel / abort | Kills process group; in-flight turn terminates | Teardown, kill, and auto-reload on RC01 (-32601 fallback) |
-| MCP tool bridge routing | Injected filesystem config via `--add-dir` | Direct `mcpServers` param in `session/new` and `session/load` |
-| Tool execution & visibility | Native re-exec (read-only) + wrapper replay (mutating) | Server executes tools natively; events stream with content |
-| Inline file edit diffs | Sourced from git working tree in thinking block | Sourced from `tool_call content[]` or disk vs git HEAD |
-| Permission handling | `--dangerously-skip-permissions` (unattended CLI requirement) | Protocol-native `session/request_permission` (auto-approve when `skipPermissions` is on; auto-deny when off) |
-| Context digest delivery (G1) | Prepend plain text inline in prompt | Native `embeddedContext` resource block |
-| System prompt delivery (G10) | Prepend to first prompt of conversation | Prepend to first prompt of conversation |
-| Authentication methods | Inherits existing `agy` CLI OAuth state | 4 methods: `oauth-personal`, `oauth-business`, `gemini-api-key`, `agent-platform` |
-| Wire protocol | Undocumented CLI NDJSON stream format | Versioned JSON-RPC 2.0 over stdio (`protocolVersion: 1`) |
-| Diagnostics (`/agy doctor`) | Child PID, state, process spawns, recycles, queue stats | Server version, agentInfo, session counts, reconnect count, cancel support |
-| Integration channel | Spawns internal CLI stream-json dialect | Official Google first-party ACP server binary |
-
-Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
+Full capability comparison, switching, and setup/auth details: [docs/ENGINES.md](docs/ENGINES.md).
+
+Switch and setup details live in [docs/ENGINES.md](docs/ENGINES.md): switching to `acp` self-installs Google's official server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) and prepares the login (your Antigravity subscription, same account as the `agy` CLI; the extension never sees your credentials). `/agy auth` signs in explicitly, `/agy doctor` diagnoses, and a session start self-heals silently when everything is ready. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -58,7 +36,7 @@ agy runs its own closed tool loop (`read_file`, `write_file`, `edit_file`, `run_
 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 by default, same as every other tool in pi. The [Approval gate](#approval-gate-agy-native-tools) can put pi-side review in front of agy's mutating native tools (off by default; `auto` enables it only when a pi permission extension is installed). See also [Permissions](#permissions) below.
+- agy commands run without per-action approval by default, same as every other tool in pi. The [Approval gate](docs/APPROVAL-GATE.md) can put pi-side review in front of agy's mutating native tools (off by default; `auto` enables it only when a pi permission extension is installed). See also [Permissions](#permissions) below.
 - 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)
@@ -94,35 +72,9 @@ bridge port, and the last lifecycle events without spending tokens.
 
 ## Approval gate (agy native tools)
 
-agy is not a plain model: it runs its own agent loop with its own native tools (`run_command`, `create_file`, `edit_file`, ...). Those calls execute inside agy with no pi involvement, so pi's permission extensions never saw them. The approval gate closes that gap: agy native tool calls pass through a pi-side approval in a form the existing permission-extension ecosystem gates with zero changes.
-
-Mechanics: the extension stages an `.agents/hooks.json` group in the workspace; the Antigravity server/CLI fires a `PreToolUse` hook before each mutating native tool runs. The hook script (generated, per-pid, mode 0600 because it embeds the bridge token) POSTs the call to the bridge and polls for a decision. The bridge parks it, the provider interrupts the pi-side view of the agy turn with a `toolUse` for a SHADOW tool named `bash`/`write`/`edit` (same schema as the real builtin plus internal `__agy*` marker fields), and pi's whole `tool_call` surface applies: any installed permission extension gates the call unchanged, and only if nothing blocks does the fallback policy run. The decision travels back to the hook and agy enforces it; on deny the reason text is what agy's model sees. Marker calls never execute locally (a ticket check denies forged ones); non-marker calls delegate to a factory twin of the real builtin, so normal pi bash/write/edit behavior is unchanged. Read-only agy tools stay ungated. Every decision lands in the daily log with tool names, source, and latency.
+agy runs its own agent loop with native tools (`run_command`, `create_file`, `edit_file`, ...), which pi's permission extensions never saw. The optional approval gate routes those calls through a pi-side approval: a staged PreToolUse hook parks the call, the provider surfaces it as a shadow `bash`/`write`/`edit` toolUse, and your permission extension (or the built-in ask/allow/deny fallback) decides before agy executes it. Off by default (`approvals.gateMode: auto` enables it only when a pi permission extension is detected); denials fail closed; read-only agy tools stay ungated.
 
-Configuration (`/agy` config keys or environment):
-
-```jsonc
-{
-  "approvals": {
-    "gateMode": "auto",  // auto | shadow | dedicated | off
-    "mode": "ask"        // ask | allow | deny  (fallback when no extension gates)
-  }
-}
-// env: AGY_APPROVALS=shadow AGY_APPROVALS_MODE=ask
-```
-
-`auto` (default) keeps the gate OFF until one of the known pi permission packages is detected (pi settings `packages` name-match or known config markers). `shadow` forces it on; `off` forces it off. `dedicated` currently stages the same shadow tools (the explicit `antigravity_approve` variant is planned; the config value is accepted today so the schema is stable). The fallback `mode` is consulted only when no extension blocked the call: `ask` shows a pi confirm dialog (headless runs deny, fail-closed), `allow` approves, `deny` blocks. Timeouts deny fail-closed: the staged hook timeout always exceeds the park budget, but a hook that outlives its timeout soft-passes upstream (verified against the ACP server), so the park always answers first.
-
-If you write your own gate extension, it sees a normal pi tool call:
-
-```typescript
-export default function (pi) {
-	pi.on("tool_call", async (event) => {
-		if (event.input?.__agyGate && event.input.command?.startsWith("rm ")) {
-			return { block: true, reason: "rm is not allowed through the agy gate" };
-		}
-	});
-}
-```
+Full mechanics, configuration, and a sample gate extension: [docs/APPROVAL-GATE.md](docs/APPROVAL-GATE.md).
 
 ## Install
 
@@ -134,7 +86,7 @@ Install with pi's package manager:
 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.
+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. While the stream-json engine is active and the binary cannot be found, pi warns on every start (toast in the TUI, stderr headless) pointing at the install guide; the warning stops once the binary is detected.
 
 ## Usage
 
@@ -190,7 +142,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy system-prompt on|off send pi's system prompt + AGENTS.md + the Pi Bridge tool-priority note to new agy conversations (default on)
 /agy bridge all|mcp|none  which pi tools the MCP bridge exposes to agy (default all; none = bridge off)
 /agy acp-bin <path|auto>  point the ACP engine at a specific server binary (auto = setup installs, or AGY_ACP_BIN; applies on the next ACP turn)
-/agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp is beta and runs self-service setup: binary install + auth bootstrap)
+/agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp is beta and runs self-service setup: binary install + auth bootstrap). No arguments opens the engine picker modal (TUI)
 /agy auth-manual             manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
 /agy patch-cleanup        restore the original pi files if an older version patched them
 /agy clear                drop all session bindings (force fresh conversations)
@@ -204,7 +156,7 @@ Because agy runs non-interactively under this provider (nothing can answer a `y/
 
 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)).
 
-For per-action review of agy's mutating native tools (`run_command`, `create_file`, `edit_file`, ...), see the [Approval gate](#approval-gate-agy-native-tools): with it on, the call must pass a pi-side approval (your permission extension, or the built-in ask/allow/deny fallback) before agy executes it.
+For per-action review of agy's mutating native tools (`run_command`, `create_file`, `edit_file`, ...), see the [Approval gate](docs/APPROVAL-GATE.md): with it on, the call must pass a pi-side approval (your permission extension, or the built-in ask/allow/deny fallback) before agy executes it.
 
 ### Run pi inside a sandbox
 

package/docs/APPROVAL-GATE.md

@@ -0,0 +1,33 @@
+# Approval gate (agy native tools)
+
+agy is not a plain model: it runs its own agent loop with its own native tools (`run_command`, `create_file`, `edit_file`, ...). Those calls execute inside agy with no pi involvement, so pi's permission extensions never saw them. The approval gate closes that gap: agy native tool calls pass through a pi-side approval in a form the existing permission-extension ecosystem gates with zero changes.
+
+Mechanics: the extension stages an `.agents/hooks.json` group in the workspace; the Antigravity server/CLI fires a `PreToolUse` hook before each mutating native tool runs. The hook script (generated, per-pid, mode 0600 because it embeds the bridge token) POSTs the call to the bridge and polls for a decision. The bridge parks it, the provider interrupts the pi-side view of the agy turn with a `toolUse` for a SHADOW tool named `bash`/`write`/`edit` (same schema as the real builtin plus internal `__agy*` marker fields), and pi's whole `tool_call` surface applies: any installed permission extension gates the call unchanged, and only if nothing blocks does the fallback policy run. The decision travels back to the hook and agy enforces it; on deny the reason text is what agy's model sees. Marker calls never execute locally (a ticket check denies forged ones); non-marker calls delegate to a factory twin of the real builtin, so normal pi bash/write/edit behavior is unchanged. Read-only agy tools stay ungated. Every decision lands in the daily log with tool names, source, and latency.
+
+Configuration (`/agy` config keys or environment):
+
+```jsonc
+{
+  "approvals": {
+    "gateMode": "auto",  // auto | shadow | dedicated | off
+    "mode": "ask"        // ask | allow | deny  (fallback when no extension gates)
+  }
+}
+// env: AGY_APPROVALS=shadow AGY_APPROVALS_MODE=ask
+```
+
+`auto` (default) keeps the gate OFF until one of the known pi permission packages is detected (pi settings `packages` name-match or known config markers). `shadow` forces it on; `off` forces it off. `dedicated` currently stages the same shadow tools (the explicit `antigravity_approve` variant is planned; the config value is accepted today so the schema is stable). The fallback `mode` is consulted only when no extension blocked the call: `ask` shows a pi confirm dialog (headless runs deny, fail-closed), `allow` approves, `deny` blocks. Timeouts deny fail-closed: the staged hook timeout always exceeds the park budget, but a hook that outlives its timeout soft-passes upstream (verified against the ACP server), so the park always answers first.
+
+If you write your own gate extension, it sees a normal pi tool call:
+
+```typescript
+export default function (pi) {
+	pi.on("tool_call", async (event) => {
+		if (event.input?.__agyGate && event.input.command?.startsWith("rm ")) {
+			return { block: true, reason: "rm is not allowed through the agy gate" };
+		}
+	});
+}
+```
+
+Live end-to-end verification (drive a real mutating agy turn through the gate) is still pending; see docs/TODO.md section 1.

package/docs/ARCHITECTURE.md

@@ -32,6 +32,7 @@ src/approval-gate.ts  shadow tool factory (bash/write/edit): marker calls are ti
 src/approval-detect.ts third-party pi permission-extension detection; resolves approvals.gateMode auto (off until a gate extension exists)
 src/approval-hook.ts  merge-safe .agents/hooks.json staging (PreToolUse) + generated 0600 early-ack/poll hook script; staged timeout exceeds the park budget (hook timeouts soft-pass)
 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/engine-picker.ts  first-run onboarding: engine picker overlay (SelectList + DynamicBorder), first-run gate (no config file + no AGY_ENGINE), agy binary detection (PATH / AGY_BIN), missing-CLI toast copy
 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)

package/docs/DEVELOPMENT.md

@@ -99,6 +99,7 @@ Most "stuck" reports trace to one of:
 - `tests/acp-config.test.ts` - engine selection narrowing (`AGY_ENGINE`/`config.engine`), acp block parsing.
 - `tests/daily-log.test.ts` - the support log: day rotation, retention cutoff boundary, secret redaction (incl. header blocks), the 4 KB record cap, never-throw on a broken dir, and the two-tier gate (debug records dropped unless `AGY_DEBUG`).
 - `tests/mcp-registration.test.ts` - the `~/.gemini/config/mcp_config.json` registration for the stream-json CLI: exact agy entry shape, foreign servers preserved, corrupt config refused, atomic writes, stale-entry sweep.
+- `tests/engine-picker.test.ts` - first-run onboarding: picker gate (no config file + no AGY_ENGINE, fail-closed fs), option order (stream-json first), the ACP download/sign-in disclosure pins (intro + saved toast), agy binary detection (PATH scan, explicit path, fail-closed), missing-CLI toast copy.
 - `tests/provider-escalation.test.ts` - the early-ack + poll pipeline (escalation registry, poll views, late-delivery tombstones) and tool-result image forwarding on both engines.
 - `tests/approval-gate.test.ts` - the shadow tool factory: marker calls never execute, ticket verification denies forged/stale markers before the policy, denials throw, native-to-shadow mapping.
 - `tests/approval-park.test.ts` - the approval park end-to-end over a real (port 0) server: POST ticket early-ack, poll pending -> terminal, timeout deny, ungated/unwired deny, close fail-closed, provider round-trip (allow / block-deny / timeout), `__agy*` strip on G9 args.

package/docs/ENGINES.md

@@ -0,0 +1,46 @@
+# Engines
+
+Turns run through one of two engines behind the same provider surface (`config.engine`, default `stream-json`). The choice of engine is left to the user: a first-run picker explains the trade-offs and asks once, and `/agy engine` (no arguments, TUI) reopens the same modal anytime. Direct switches work too: `/agy engine acp|stream-json`.
+
+- **stream-json** (default): the persistent `agy` CLI process. The tested default; live token usage; conversation resume via `--conversation`.
+- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows client-side ESTIMATES until Google ships usage; `acp.usageEstimate` off to keep zeros) and no cancel (abort tears the server down and reloads it next turn).
+
+## First run
+
+On a fresh install (no `config.json` yet), the first interactive pi start opens a picker modal that explains both engines - stream-json needs the `agy` CLI installed and authenticated; ACP needs a second Google sign-in plus a ~1.5 GB server binary downloaded from Google. stream-json is preselected (the default); `esc` decides later (nothing is written, the modal reappears on the next start).
+
+Picking **acp** starts the server download immediately (progress in the status bar, milestones in the chat), then opens the Google sign-in; a restart applies the engine. Picking **stream-json** persists and toasts; while that engine is active and the `agy` binary is missing, pi warns on every start with the install link until the binary shows up.
+
+## Capabilities
+
+| Capability | `stream-json` (default) | `acp` (beta) |
+| --- | --- | --- |
+| Show thinking text | No (token count only, floor 64, no text body) | Yes (streams thought text via `agent_thought_chunk`; sparse on RC01 where reasoning often arrives in message text) |
+| Live token usage | Yes (live metrics from CLI step events) | Estimated client-side (absent in RC01; `acp.usageEstimate`, default on) |
+| Image prompt input | No (CLI prompt is text-only; images dropped) | Yes (native image blocks forwarded to server) |
+| Image tool results | Yes (bridge tool results carry pixels; probe-verified 2026-09-07) | Yes (probe-verified 2026-09-05) |
+| Audio prompt input | No (dropped) | Protocol advertised (`promptCapabilities.audio: true`) |
+| Review-only plan mode | Yes (`--mode plan` review-only via `/agy mode plan`) | No (RC01 modes are permission levels; plan mode refused) |
+| Leading slash commands in prompt | Disabled via `--disable-slash-commands` (sent as plain text) | Server intercepts recognized commands (e.g. `/plan`) and executes them under the active policy |
+| Dynamic model / effort switch | Recycles process on model or effort change | Dynamic per-turn via `session/set_config_option` (no restart) |
+| Process lifecycle | 1 persistent `agy` process per provider; recycles on drift | 1 persistent server process hosting N sessions concurrently |
+| Session resume & persistence | Client-side map in `sessions.json` via `--conversation <id>` | Server-side session store via `session/load` and `session/new` |
+| Turn cancel / abort | Kills process group; in-flight turn terminates | Teardown, kill, and auto-reload on RC01 (-32601 fallback) |
+| MCP tool bridge routing | Injected filesystem config via `--add-dir` | Direct `mcpServers` param in `session/new` and `session/load` |
+| Tool execution & visibility | Native re-exec (read-only) + wrapper replay (mutating) | Server executes tools natively; events stream with content |
+| Inline file edit diffs | Sourced from git working tree in thinking block | Sourced from `tool_call content[]` or disk vs git HEAD |
+| Permission handling | `--dangerously-skip-permissions` (unattended CLI requirement) | Protocol-native `session/request_permission` (auto-approve when `skipPermissions` is on; auto-deny when off) |
+| Context digest delivery (G1) | Prepend plain text inline in prompt | Native `embeddedContext` resource block |
+| System prompt delivery (G10) | Prepend to first prompt of conversation | Prepend to first prompt of conversation |
+| Authentication methods | Inherits existing `agy` CLI OAuth state | 4 methods: `oauth-personal`, `oauth-business`, `gemini-api-key`, `agent-platform` |
+| Wire protocol | Undocumented CLI NDJSON stream format | Versioned JSON-RPC 2.0 over stdio (`protocolVersion: 1`) |
+| Diagnostics (`/agy doctor`) | Child PID, state, process spawns, recycles, queue stats | Server version, agentInfo, session counts, reconnect count, cancel support |
+| Integration channel | Spawns internal CLI stream-json dialect | Official Google first-party ACP server binary |
+
+## Engine-dependent features
+
+pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text. The `AskAntigravity` delegation tool is unaffected by `config.engine` and runs the `stream-json` CLI (`agy -p`) across both configurations.
+
+## Switching and setup
+
+Switch with `/agy engine acp|stream-json` (takes effect on restart), or run `/agy engine` with no arguments for the same picker modal as first run (an `acp` pick there runs the same download + sign-in chain). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.

package/docs/TODO.md

@@ -2,7 +2,7 @@
 
 ## 1. Approval gate: live end-to-end verification
 
-The gate is wired and unit-pinned (304 tests) but has never run against a live
+The gate is wired and unit-pinned (333 tests) but has never run against a live
 agy turn. Enable it, drive an agy turn that mutates a file, and watch the
 round trip: PreToolUse hook -> POST /approval park -> shadow toolUse ->
 decision -> hook stdout -> agy enforces.

package/extensions/index.ts

@@ -66,6 +66,7 @@ import { setupAuthUrlCapture } from "../src/acp/browser-capture.js";
 import { ensureAcpReady, inspectAcpSetup } from "../src/acp/setup.js";
 import type { TurnDriver, TurnOutcome } from "../src/driver-types.js";
 import { CONFIG_PATH, loadConfig, logsDir, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
+import { agyMissingMessage, isAgyInstalled, savedEngineMessage, showEnginePicker, shouldOfferEnginePicker } from "../src/engine-picker.js";
 import { createDailyLogger, type DailyLogger } from "../src/daily-log.js";
 import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
 import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
@@ -181,6 +182,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// ACP self-heal runs once per process (session_start re-fires on /reload;
 	// a ready setup is two file stats, so re-running is harmless anyway).
 	let acpSelfHealRan = false;
+	// Warn-once-per-process flag for the missing-agy-CLI toast (stream-json).
+	let agyMissingWarned = false;
 	// OAuth URL capture: the server hands the login URL only to the
 	// browser-open call (nothing on stdio), so a BROWSER wrapper records it
 	// and the driver logs it as "auth-url". Local users keep the automatic
@@ -276,6 +279,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		// Resolved per connection: the setup flow can install the binary and
 		// update acp.bin mid-session; the next turn picks it up (no restart).
 		bin: () => loadConfig().acp.bin,
+		// Resolved per turn: /agy and AGY_USAGE_ESTIMATE changes apply without
+		// a restart. Without this the driver defaults to "estimate" and the
+		// config knob (incl. "off") is dead.
+		usageEstimate: () => loadConfig().acp.usageEstimate,
 		...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
 		log: acpLog,
 		mcpServers: () => {
@@ -380,6 +387,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		acpLog,
 		fileLog,
 		authCapture: authCapture ?? null,
+		runAcpPickSetup,
 	});
 
 	// AskAntigravity tool: one-shot delegation to agy (ported from
@@ -412,12 +420,115 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		},
 	});
 
+	/** ACP pick follow-through (first-run wizard): the same self-service
+	 *  setup the /agy engine acp command runs, but immediately - the 1.5 GB
+	 *  download starts while the toast is still on screen, progress rides the
+	 *  footer status, and the Google sign-in opens when the install lands.
+	 *  Restart still applies the engine (drivers wire at load); this only
+	 *  removes the wait. Fire-and-forget: the caller already toasted the
+	 *  promise, failures land in the daily log + a warning toast. */
+	// eslint-disable-next-line @typescript-eslint/no-inner-declarations -- hoisted: registerAgyCommand below injects it
+	async function runAcpPickSetup(ctx: { ui: ExtensionUIContext }): Promise<void> {
+		acpSelfHealRan = true;
+		let lastPhase = "";
+		ctx.ui.setStatus("agy-acp", "downloading ACP server…");
+		try {
+			const status = await ensureAcpReady({
+				configBin: loadConfig().acp.bin,
+				onProgress: (m) => {
+					// Dual surface: the status bar carries the live percent (cleared
+					// on completion, zero footprint); the chat window gets phase
+					// milestones only (download start, unpacking, installed) - same
+					// line-in-chat feel as other extensions' notify() notices. The
+					// percent variant updates every chunk and would spam the chat.
+					ctx.ui.setStatus("agy-acp", m);
+					if (m !== lastPhase && !/\d+%/.test(m)) {
+						ctx.ui.notify(m, "info");
+						lastPhase = m;
+					}
+				},
+			});
+			ctx.ui.setStatus("agy-acp", undefined);
+			fileLog.log(
+				"acp-setup",
+				status.ok
+					? { ok: true, binarySource: status.binarySource, needsLogin: status.needsLogin }
+					: { ok: false, error: status.error },
+				status.ok ? "info" : "warn",
+			);
+			if (!status.ok) {
+				ctx.ui.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
+				return;
+			}
+			// Spread, not a bare acp patch: a bare {bin} patch would drop
+			// sibling keys (usageEstimate) from the file.
+			saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
+			if (!status.needsLogin) {
+				ctx.ui.notify(`ACP server ready (auth: ${status.auth}). Restart applies the engine.`, "info");
+				return;
+			}
+			ctx.ui.notify(
+				"ACP server ready. Signing in: the Google sign-in opens in your browser and completes when you finish it.",
+				"info",
+			);
+			const r = await runAcpAuth({
+				bin: status.bin,
+				...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
+				log: acpLog,
+			});
+			fileLog.log("acp-auth", r.ok ? { ok: true } : { ok: false, error: r.error }, r.ok ? "info" : "warn");
+			if (r.ok) ctx.ui.notify("Signed in. The ACP engine is ready; restart applies it.", "info");
+			else ctx.ui.notify(`ACP sign-in failed (${r.error}).\nRun /agy auth to retry; /agy auth-manual has manual steps.`, "warning");
+		} catch (err) {
+			ctx.ui.setStatus("agy-acp", undefined);
+			fileLog.log("acp-setup", { error: String(err) }, "warn");
+			ctx.ui.notify(`ACP setup failed (${String(err)}). /agy auth retries; /agy doctor inspects.`, "warning");
+		}
+	}
+
 	// MCP tool bridge: expose pi's tools to agy over localhost Streamable HTTP.
 	// 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.
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		if (ctx.hasUI) activeUi = ctx.ui;
+		// First-run engine picker: ask once, on the first interactive start,
+		// which turn engine to use. Skipped headless (ctx.mode !== "tui"),
+		// when AGY_ENGINE is set, or once any config file exists (any save -
+		// even of an unrelated knob - means the user has been here before).
+		// esc = decide later: nothing is written, the picker reappears next
+		// start. Like /agy engine, the choice applies on the next start
+		// (drivers wire at load). The await intentionally runs before the
+		// bridge startup below: on a genuine first run the modal blocks input
+		// anyway, so the delay is invisible.
+		if (event.reason === "startup" && ctx.mode === "tui" && shouldOfferEnginePicker(CONFIG_PATH)) {
+			// Best-effort, like the legacy-patch notice below: a picker failure
+			// (mid-prompt TUI teardown, resize races) must never take down the
+			// rest of session_start - the MCP bridge startup included. The
+			// default engine keeps working untouched.
+			try {
+				const picked = await showEnginePicker(ctx.ui);
+				if (picked) {
+					saveConfig({ engine: picked });
+					ctx.ui.notify(savedEngineMessage(picked), "info");
+					if (picked === "acp") void runAcpPickSetup(ctx);
+				}
+			} catch (err) {
+				fileLog.log("engine-picker", { error: String(err) }, "warn");
+				console.error(`[antigravity-bridge] engine picker failed: ${String(err)}`);
+			}
+		}
+		// agy presence check (stream-json engine): the CLI is the whole engine,
+		// so a missing binary means every Antigravity turn would fail. Warn on
+		// every process start until it is installed (per-process flag so /new,
+		// /resume and /reload re-fires do not nag mid-session). Runs after the
+		// picker above, so a first-run stream-json pick warns immediately.
+		if (engine === "stream-json" && !agyMissingWarned && !isAgyInstalled(binary)) {
+			agyMissingWarned = true;
+			const msg = agyMissingMessage();
+			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
+			else console.error(`[antigravity-bridge] ${msg}`);
+		}
 		// Legacy cleanup: users who ran the old consent-gated patcher still
 		// carry pi.invokeTool in their installed pi. Inert, but tell them once
 		// and offer /agy patch-cleanup. Never auto-edits the install.
@@ -451,7 +562,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				);
 				if (status.ok) {
 					if (status.binarySource === "installed" || status.binarySource === "existing") {
-						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+						saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
 					}
 					if (status.needsLogin) {
 						const msg = acpLoginPending();
@@ -755,6 +866,9 @@ interface AgyCommandCtx {
 	acpLog: (msg: string, data?: unknown) => void;
 	/** Daily file logger (src/daily-log.ts); command + doctor surfacing. */
 	fileLog: DailyLogger;
+	/** Wizard-pick follow-through (download now + chained sign-in); reused
+	 *  by /agy engine's no-args modal so both entry points behave alike. */
+	runAcpPickSetup: (cmdCtx: { ui: ExtensionUIContext }) => Promise<void>;
 	/** BROWSER-capture handles; null when unavailable (Windows, unwritable
 	 *  data dir). /agy auth passes them to the sign-in process. */
 	authCapture: { browserEnv: Record<string, string>; file: string } | null;
@@ -866,7 +980,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
 						return;
 					}
-					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+					saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
 					if (status.needsLogin) {
 						ui?.notify(
 							`ACP engine set. ${acpLoginPending()}`,
@@ -875,6 +989,28 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					} else {
 						ui?.notify(`ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`, "info");
 					}
+				} else if (!val && mode === "tui" && ui) {
+					// Same modal as the first-run wizard: switching engines deserves
+					// the explanations, not a bare usage line. Semantics match the
+					// direct path above: plan blocks acp, an acp pick chains setup
+					// + sign-in immediately, restart applies the switch.
+					const current = loadConfig().engine;
+					const picked = await showEnginePicker(ui);
+					if (picked === null) {
+						ui.notify(`engine unchanged: ${current}.`, "info");
+						return;
+					}
+					if (picked === current) {
+						ui.notify(`engine is already ${current}. Restart applies it if set this session.`, "info");
+						return;
+					}
+					if (picked === "acp" && loadConfig().mode === "plan") {
+						ui.notify("mode is plan; the ACP engine has no plan mode. /agy mode accept-edits first.", "warning");
+						return;
+					}
+					saveConfig({ engine: picked });
+					ui.notify(savedEngineMessage(picked), "info");
+					if (picked === "acp") void ctx.runAcpPickSetup({ ui });
 				} else {
 					ui?.notify(`current engine: ${loadConfig().engine}\nusage: /agy engine stream-json|acp`, "info");
 				}
@@ -901,7 +1037,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
 					return;
 				}
-				saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+				saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
 				if (!status.needsLogin) {
 					ui?.notify(`Already signed in (auth: ${status.auth}). Nothing to do.`, "info");
 					return;
@@ -929,7 +1065,9 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				if (rest.length > 0) {
 					// Only the keyword compares case-insensitively; the path keeps its case.
 					const bin = rest.toLowerCase() === "auto" ? "" : rest.replace(/^~(?=\/|$)/, os.homedir());
-					saveConfig({ acp: { bin, permissions: loadConfig().acp.permissions } });
+					// Spread, not a bare acp patch: a bare {bin, permissions} object
+					// would drop sibling keys (usageEstimate) from the file.
+					saveConfig({ acp: { ...loadConfig().acp, bin } });
 					ui?.notify(
 						bin
 							? `acp.bin set to ${bin}. The next ACP turn (re)connects with it.`
@@ -999,6 +1137,8 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					// line the day it starts (then real usage mapping is worth wiring).
 					if (snap.acp.usageSeen) {
 						lines.push("  acp tokens:    AVAILABLE in server payloads (wire real usage mapping next)");
+					} else if (config.acp.usageEstimate !== "off") {
+						lines.push(`  acp tokens:    ESTIMATED client-side (mode: ${config.acp.usageEstimate}; auto-off once the server sends real usage)`);
 					}
 				}
 				if (snap.lifecycle.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.4.10",
+  "version": "1.5.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",

package/src/acp/driver.ts

@@ -19,9 +19,12 @@
 //     in-connection (plan §9.3); no provider involvement
 
 import { randomUUID } from "node:crypto";
+import type { UsageEstimate } from "../config.js";
 import { AcpConnection, resolveAcpBinary, type AcpMcpServer } from "./connection.js";
 import { mapStopReason, mapUpdate, TextAccumulator, type AcpEditDiff } from "./events.js";
+import { estimateTokens, synthesizeUsage } from "./usage-estimate.js";
 import type {
+	AgyUsage,
 	DriverActivity,
 	DriverSnapshot,
 	DriverState,
@@ -46,6 +49,10 @@ export interface AcpDriverOptions {
 	authUrlFile?: string;
 	/** Bridge registration for session/new AND session/load. */
 	mcpServers?: () => AcpMcpServer[];
+	/** Gate B stopgap: how ACP turns synthesize usage while the server sends
+	 *  none. A function is resolved per turn (follows live config, like bin).
+	 *  Default "estimate". */
+	usageEstimate?: UsageEstimate | (() => UsageEstimate);
 	log?: (msg: string, data?: unknown) => void;
 }
 
@@ -59,6 +66,13 @@ interface ActiveTurn {
 	resolve: (o: TurnOutcome) => void;
 	outcome: Promise<TurnOutcome>;
 	response: TextAccumulator;
+	/** Usage-synthesis counters: per-delta token sums (estimate mode) and
+	 *  delta counts (direct mode). Sums are taken per delta, never over the
+	 *  joined text, so a word split across chunks stays two words. */
+	textTokens: number;
+	thoughtTokens: number;
+	textDeltas: number;
+	thoughtDeltas: number;
 	sawResult: boolean;
 	/** True once the prompt RPC was issued. Abort before this point has
 	 *  nothing to cancel: probing would risk a success-as-noop answer from a
@@ -359,10 +373,16 @@ export class AcpDriver implements TurnDriver {
 		switch (mapped.kind) {
 			case "text": {
 				const emit = turn.response.append(mapped.delta);
-				if (emit) this.#emit(turn, { type: "text", delta: emit });
+				if (emit) {
+					turn.textDeltas += 1;
+					turn.textTokens += estimateTokens(emit);
+					this.#emit(turn, { type: "text", delta: emit });
+				}
 				return;
 			}
 			case "thought": {
+				turn.thoughtDeltas += 1;
+				turn.thoughtTokens += estimateTokens(mapped.delta);
 				this.#emit(turn, { type: "thought", delta: mapped.delta });
 				return;
 			}
@@ -543,6 +563,10 @@ export class AcpDriver implements TurnDriver {
 			resolve,
 			outcome,
 			response: new TextAccumulator(),
+			textTokens: 0,
+			thoughtTokens: 0,
+			textDeltas: 0,
+			thoughtDeltas: 0,
 			sawResult: false,
 		promptStarted: false,
 			aborted: false,
@@ -643,6 +667,16 @@ export class AcpDriver implements TurnDriver {
 
 	#settle(turn: ActiveTurn, outcome: TurnOutcome): void {
 		if (turn.closed) return;
+		// Gate B stopgap: synthesize usage on clean turns while the server sends
+		// none. Runs BEFORE close so the usage activity drains through the
+		// normal #nextActivity loop (provider maps it onto partial.usage).
+		if (outcome.status === "OK" && !outcome.aborted && outcome.usage === undefined) {
+			const usage = this.#syntheticUsage(turn);
+			if (usage) {
+				outcome.usage = usage;
+				this.#emit(turn, { type: "usage", usage });
+			}
+		}
 		turn.closed = true;
 		if (turn.overallTimer) clearTimeout(turn.overallTimer);
 		if (turn.idleTimer) clearTimeout(turn.idleTimer);
@@ -671,6 +705,29 @@ export class AcpDriver implements TurnDriver {
 		});
 	}
 
+	/** Usage synthesis mode, resolved per turn (follows live config). */
+	#usageMode(): UsageEstimate {
+		const opt = this.#opts.usageEstimate;
+		return (typeof opt === "function" ? opt() : opt) ?? "estimate";
+	}
+
+	#syntheticUsage(turn: ActiveTurn): AgyUsage | undefined {
+		const mode = this.#usageMode();
+		if (mode === "off") return undefined;
+		// Gate B latch: any server frame with usage/token keys means real
+		// usage exists upstream; estimates must never shadow it.
+		if (this.#conn?.usageSeen) return undefined;
+		return synthesizeUsage({
+			mode,
+			prompt: turn.request.prompt,
+			contextText: turn.request.contextBlock?.text,
+			textTokens: turn.textTokens,
+			thoughtTokens: turn.thoughtTokens,
+			textDeltas: turn.textDeltas,
+			thoughtDeltas: turn.thoughtDeltas,
+		});
+	}
+
 	#log(msg: string, data?: unknown): void {
 		const line = `${new Date().toISOString().slice(11, 19)} ${msg}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}`;
 		this.#lifecycle.push(line);

package/src/acp/usage-estimate.ts

@@ -0,0 +1,59 @@
+// Gate B stopgap: synthesize AgyUsage for ACP turns until Google ships a
+// real token-usage layer in agy_acp_server. Counting mechanism copied from
+// the pi-token-speed extension (npm:pi-token-speed, src/engine.ts): a
+// word/punctuation regex, 1 match = 1 token. The numbers are client-side
+// ESTIMATES, never provider data: the connection's usageSeen latch (Gate B
+// watch) keeps synthesis off the day real usage appears in any frame, so
+// estimates can never shadow real numbers.
+
+import type { UsageEstimate } from "../config.js";
+import type { AgyUsage } from "../driver-types.js";
+
+const TOKEN_REGEX = /\w+|[^\s\w]/g;
+
+/** Word-boundary token estimate (pi-token-speed's estimateTokens). */
+export function estimateTokens(text: string): number {
+	if (!text) return 0;
+	const matches = text.match(TOKEN_REGEX);
+	return matches ? matches.length : 0;
+}
+
+export interface UsageEstimateInput {
+	mode: UsageEstimate;
+	/** Full outgoing prompt text (input side; always regex-estimated). */
+	prompt: string;
+	/** ACP embeddedContext resource text (G1 digest): also reaches the model. */
+	contextText?: string;
+	/** Per-delta token sums (mode "estimate"). Summing per delta, like
+	 *  pi-token-speed's recordDelta, avoids word-merge artifacts when a
+	 *  chunk boundary splits a word. */
+	textTokens: number;
+	thoughtTokens: number;
+	/** Streamed delta counts (mode "direct": 1 token per delta). */
+	textDeltas: number;
+	thoughtDeltas: number;
+}
+
+/** Synthesize usage for a finished turn, or undefined when nothing is worth
+ *  reporting (mode off, or a turn with no prompt and no output). */
+export function synthesizeUsage(input: UsageEstimateInput): AgyUsage | undefined {
+	if (input.mode === "off") return undefined;
+	const inputTokens = estimateTokens(
+		input.contextText ? `${input.prompt}\n${input.contextText}` : input.prompt,
+	);
+	const thoughtTokens =
+		input.mode === "direct" ? input.thoughtDeltas : input.thoughtTokens;
+	const textTokens =
+		input.mode === "direct" ? input.textDeltas : input.textTokens;
+	// Thinking folds INTO output (OpenAI convention: reasoning tokens bill as
+	// output). toPiUsage drops thinking_tokens, and thinking time is inside
+	// elapsed wall time, so folding keeps the tokens/time ratio honest.
+	const outputTokens = textTokens + thoughtTokens;
+	if (inputTokens === 0 && outputTokens === 0) return undefined;
+	return {
+		input_tokens: inputTokens,
+		output_tokens: outputTokens,
+		thinking_tokens: thoughtTokens,
+		total_tokens: inputTokens + outputTokens,
+	};
+}

package/src/config.ts

@@ -44,6 +44,12 @@ export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
 export type BridgeTools = "none" | "mcp" | "all";
 
+/** How ACP turns report token usage while Gate B stands (agy sends none).
+ *  "estimate" (default): word-boundary regex over prompt/response/thought
+ *  text (pi-token-speed's mechanism). "direct": 1 token per streamed delta.
+ *  "off": keep zero-usage. Real server usage (usageSeen latch) always wins. */
+export type UsageEstimate = "estimate" | "direct" | "off";
+
 /** How the approval gate activates (docs/TODO.md section 2.5).
  *
  *  "auto" (default): OFF until a third-party pi permission extension is
@@ -74,6 +80,10 @@ export interface AcpConfig {
 	 *  (parity with skipPermissions). Kept as a key so future policies do not
 	 *  change the config shape. */
 	permissions: "auto";
+	/** Gate B stopgap: client-side token estimates for ACP turns so pi's
+	 *  usage surfaces show nonzero numbers. Estimates are labeled as such in
+	 *  /agy doctor and auto-disable when the server sends real usage. */
+	usageEstimate: UsageEstimate;
 }
 
 export interface AgyConfig {
@@ -149,7 +159,7 @@ const DEFAULTS: AgyConfig = {
 	digest: false,
 	systemPrompt: true,
 	approvals: { gateMode: "auto", mode: "ask" },
-	acp: { bin: "", permissions: "auto" },
+	acp: { bin: "", permissions: "auto", usageEstimate: "estimate" },
 };
 
 /** Load config merged over defaults. Env vars override the file when set. */
@@ -232,11 +242,19 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 			: "ask";
 
 	const fileAcp = (typeof file.acp === "object" && file.acp !== null ? file.acp : {}) as Partial<AcpConfig>;
+	// Unknown values fall back to "estimate" (same narrow-parse pattern as
+	// gateMode: a typo must never silently change behavior).
+	const usageRaw = String(
+		process.env.AGY_USAGE_ESTIMATE ?? fileAcp.usageEstimate ?? DEFAULTS.acp.usageEstimate,
+	).toLowerCase();
+	const usageEstimate: UsageEstimate =
+		usageRaw === "direct" || usageRaw === "off" ? usageRaw : "estimate";
 	const acp: AcpConfig = {
 		bin:
 			process.env.AGY_ACP_BIN ??
 			(typeof fileAcp.bin === "string" ? fileAcp.bin : DEFAULTS.acp.bin),
 		permissions: "auto",
+		usageEstimate,
 	};
 
 	return {

package/src/engine-picker.ts

@@ -0,0 +1,155 @@
+// First-run onboarding: the engine picker plus the agy-presence warning.
+//
+// On the first interactive start (no config file yet, no AGY_ENGINE env) pi
+// asks which turn engine to use: the stream-json `agy` CLI or Google's
+// official ACP server. The choice persists via saveConfig({ engine }) and,
+// like /agy engine, takes effect on the next pi start (drivers wire at load).
+// Every start with the stream-json engine active also re-checks that the
+// `agy` binary exists and warns until it does (re-auth is out of scope).
+//
+// UI: tui.md "Pattern 1" - SelectList framed by DynamicBorder inside pi's
+// native overlay (the window feel pi-rtk builds its modal on).
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	type SelectItem,
+	SelectList,
+	Spacer,
+	Text,
+} from "@earendil-works/pi-tui";
+import fs from "node:fs";
+import path from "node:path";
+import type { Engine } from "./config.js";
+
+/** Picker order is the default answer order: stream-json first. */
+export const ENGINE_PICKER_ITEMS: SelectItem[] = [
+	{
+		value: "stream-json",
+		label: "Stream-JSON CLI",
+		description: "default, recommended",
+	},
+	{
+		value: "acp",
+		label: "ACP server (official Google)",
+		description: "second sign-in, ~1.5 GB binary download",
+	},
+];
+
+/** Intro paragraph above the list. Text wraps, so explanations stay here and
+ *  SelectItem descriptions stay one-liners (SelectList truncates long lines). */
+export const ENGINE_PICKER_INTRO = [
+	"Pick the engine that runs your Antigravity turns. Switch anytime with /agy engine (restart applies it).",
+	"",
+	"stream-json: the `agy` CLI you already installed and authenticated. Persistent process, streamed output. Tested default.",
+	"ACP: Google's official server (agy_acp_server.par). Needs a second Google sign-in and a ~1.5 GB server binary downloaded from Google (automatic, one-time, unavoidable: the server is not part of the agy CLI).",
+].join("\n");
+
+/** True only for a genuine first interactive run: no saved config yet (any
+ *  existing file means the user has been here before) and no AGY_ENGINE env
+ *  (env wins over the file, so the wizard would fight it). Fails closed to
+ *  false - an fs error must never nag the user with a dialog. */
+export function shouldOfferEnginePicker(
+	configPath: string,
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	if (env.AGY_ENGINE !== undefined) return false;
+	try {
+		return !fs.existsSync(configPath);
+	} catch {
+		return false;
+	}
+}
+
+/** Narrow a picker value to an Engine. Items are our own constants, but an
+ *  unknown value must never reach config as a cast string: it falls back to
+ *  the tested default. */
+export function toEngine(value: string): Engine {
+	return value === "acp" ? "acp" : "stream-json";
+}
+
+/** Toast copy shown after the choice is saved. ACP names the promise that
+ *  matters: the binary download starts NOW (not on restart), sign-in follows
+ *  when it lands, restart applies the engine. */
+export function savedEngineMessage(engine: Engine): string {
+	return engine === "acp"
+		? "Engine saved: acp. The ~1.5 GB server binary downloads now; the Google sign-in opens when it lands. Restart applies the engine."
+		: "Engine saved: stream-json. Restart pi to apply.";
+}
+
+/** True when the `agy` CLI binary can be found. A binRef with a path
+ *  separator (AGY_BIN=/opt/agy/agy) must exist as a file; a bare name is
+ *  searched on PATH. statSync cannot throw through the guards, but a race
+ *  (file removed between listing and stat) fails closed to false. */
+export function isAgyInstalled(binRef: string, env: NodeJS.ProcessEnv = process.env): boolean {
+	if (binRef.includes("/")) {
+		try {
+			return fs.statSync(binRef).isFile();
+		} catch {
+			return false;
+		}
+	}
+	return (env.PATH ?? "")
+		.split(path.delimiter)
+		.filter(Boolean)
+		.some((dir) => {
+			try {
+				return fs.statSync(path.join(dir, binRef)).isFile();
+			} catch {
+				return false;
+			}
+		});
+}
+
+/** Toast copy for the missing-CLI warning. Fires every pi start while the
+ *  stream-json engine is active and the binary is absent. */
+export function agyMissingMessage(): string {
+	return "The `agy` CLI is not installed. Install it from https://antigravity.google/product/antigravity-cli and log in on it to use Antigravity models.";
+}
+
+/** Render the picker overlay. Resolves with the chosen engine, or null when
+ *  the user pressed esc (decide later - nothing is persisted). */
+export async function showEnginePicker(ctx: ExtensionUIContext): Promise<Engine | null> {
+	return ctx.custom<Engine | null>(
+		(tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold("Antigravity Bridge: choose your engine")), 1, 0),
+			);
+			container.addChild(new Text(theme.fg("muted", ENGINE_PICKER_INTRO), 1, 0));
+			container.addChild(new Spacer(1));
+
+			const list = new SelectList(ENGINE_PICKER_ITEMS, ENGINE_PICKER_ITEMS.length, {
+				selectedPrefix: (t: string) => theme.fg("accent", t),
+				selectedText: (t: string) => theme.fg("accent", t),
+				description: (t: string) => theme.fg("muted", t),
+				scrollInfo: (t: string) => theme.fg("dim", t),
+				noMatch: (t: string) => theme.fg("warning", t),
+			});
+			list.onSelect = (item) => done(toEngine(item.value));
+			list.onCancel = () => done(null);
+			container.addChild(list);
+
+			container.addChild(new Spacer(1));
+			container.addChild(
+				new Text(theme.fg("dim", "↑↓ navigate · enter select · esc decide later"), 1, 0),
+			);
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => {
+					list.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: { anchor: "center" as const, width: 80, maxHeight: "85%" as const, margin: 1 },
+		},
+	);
+}