@estebanforge/pi-antigravity-bridge 1.6.2 → 1.6.4

package/docs/ACP-PROTOCOL-REFERENCE.md

@@ -1,462 +0,0 @@
-# ACP Protocol Reference — `antigravity-acp` (verified live)
-
-Everything below was verified LIVE on 2026-09-03 against the official Google
-ACP server, build `agy_acp_server_20260818_01_RC01` (registry id
-`antigravity-acp`, v1.0.0), linux-x86_64, on a headless Fedora box. Raw
-traffic: `probe-logs/acp-traffic-run5.jsonl` (600 clean JSONL lines,
-gitignored). Gate verdicts: [ACP-ADOPTION-PLAN.md](./ACP-ADOPTION-PLAN.md)
-section 8.1. Raw SQLite conversation store: `probe-logs/acp-server-conversations/`.
-
-Transport: newline-delimited JSON-RPC 2.0 over the server's stdio. The server
-is fully silent until it receives a request. Cold start to `initialize`
-response measured ~5-6 s across three runs (1.5 GB binary). Startup flags:
-only `--debug` and `--notices` exist. No model/effort/conversation flags:
-everything moves through the protocol or `settings.json`.
-
-Data provenance: the captures are SERVER STDOUT only. Requests quoted here
-are author-attested — we composed and sent those exact bytes (source: our
-stdin writes, preserved in `probe-logs/MANIFEST.md` references and the pi
-session) and correlate them with the success/error responses on the capture.
-No request echo exists on the wire. Gate F's accepted `mcpServers` shape is
-verified this way: those exact bytes were sent and `session/new` returned a
-session.
-
-## Method index (verified against this build)
-
-| Method | Status on RC01 |
-| --- | --- |
-| `initialize` | works |
-| `authenticate` | works (param is `methodId`) |
-| `session/new` | works |
-| `session/set_config_option` | works (param is `configId`) |
-| `session/prompt` | works |
-| `session/cancel` | **-32601 Method not found. NOT IMPLEMENTED on RC01** |
-| `session/load` | works (run 6: `{sessionId, cwd, mcpServers}`; full-text history replay) |
-| `session/close` | works (run 6; per-session, connection survives) |
-| `session/set_mode` | works (run 6; `modeId`; redundant with `set_config_option("mode")`) |
-| `session/request_permission` | observed live (run 6, mode `default` tool probe; agent-to-client REQUEST, once-only options) |
-| `session/list`, `session/resume`, `session/fork`, `session/delete` | advertised; not yet probed |
-| `fs/read_text_file`, `fs/write_text_file`, `terminal/*` | not observed (our client capabilities were `fs:false`, `terminal:false`) |
-
-## initialize
-
-Request:
-
-```json
-{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}}}
-```
-
-Result (verbatim, capability names):
-
-```json
-{"protocolVersion":1,
- "agentCapabilities":{
-   "loadSession":true,
-   "promptCapabilities":{"image":true,"audio":true,"embeddedContext":true},
-   "mcpCapabilities":{"http":true,"sse":true},
-   "sessionCapabilities":{"list":{},"resume":{}},
-   "auth":{"logout":{}}},
- "authMethods":[
-   {"description":"Log in with your Google account","id":"oauth-personal","name":"Log in with Google"},
-   {"description":"Log in with your Gemini Enterprise account","id":"oauth-business","name":"Log in with Gemini Enterprise"},
-   {"description":"Use an API key with Gemini Developer API","id":"gemini-api-key","name":"Gemini API key"},
-   {"description":"Use Gemini Enterprise Agent Platform (formerly Vertex AI) with Application Default Credentials or an API key","id":"agent-platform","name":"Gemini Enterprise Agent Platform"}],
- "agentInfo":{"name":"antigravity-acp","title":"Google Antigravity","version":"agy_acp_server_20260818_01_RC01"}}
-```
-
-Types: `promptCapabilities.image|audio|embeddedContext: bool`;
-`mcpCapabilities.http|sse: bool`; `sessionCapabilities.list|resume: object`;
-`auth.logout: object`; `authMethods[].id` is the string passed to
-`authenticate`.
-
-## authenticate
-
-Request (param name is `methodId`, NOT `method` — `method` yields -32602 with
-`errors:[{"loc":["methodId"],"msg":"field required","type":"value_error.missing"}]`):
-
-```json
-{"jsonrpc":"2.0","id":1,"method":"authenticate","params":{"methodId":"oauth-personal"}}
-```
-
-Success result: `{}` (empty object). Failures (verified live):
-
-```json
-{"jsonrpc":"2.0","id":2,"error":{"code":-32000,"message":"Onboarding failed: The authentication flow did not complete successfully.","data":{"reason":"onboarding_failed"}}}
-{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Onboarding failed: Timed out waiting for the authentication flow to complete.","data":{"reason":"onboarding_failed"}}}
-```
-
-Unauthenticated `session/new` (before any auth) returns:
-
-```json
-{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Authentication required","data":{"message":"No authentication method selected. Either call the `authenticate` method (supports oauth-personal, gemini-api-key, agent-platform), or set `auth.type` in settings.json (/home/<u>/.gemini/antigravity-acp/settings.json) to one of: oauth-personal, gemini-api-key (requires GEMINI_API_KEY env var), oauth-business (Gemini Enterprise; requires gcp.project/location), agent-platform (formerly 'vertex-ai', still accepted; requires GOOGLE_API_KEY, or a project and location from GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION or gcp.project/gcp.location with Application Default Credentials)."}}}
-```
-
-### settings.json shapes (official Zed docs + error message)
-
-```jsonc
-// ~/.gemini/antigravity-acp/settings.json
-{"auth": {"type": "oauth-personal"}}
-{"auth": {"type": "gemini-api-key"}}                       // + GEMINI_API_KEY env
-{"auth": {"type": "oauth-business"},  "gcp": {"project": "<ID>", "location": "<REGION>"}}
-{"auth": {"type": "agent-platform"},  "gcp": {"project": "<ID>", "location": "<REGION>"}}
-```
-
-settings.json is read at server STARTUP: writing it while a server process
-runs has no effect on that process (verified: the error persisted until
-restart).
-
-### oauth-personal flow (headless, verified end-to-end)
-
-On `authenticate` the server: starts a loopback HTTP listener on
-`127.0.0.1:<random port>` (observed 44603, 34653, 59563, 35293 — random per
-run), composes a Google OAuth URL, and tries to open a browser. HEADLESS: it
-never prints the URL on stdout or stderr (`--debug` stderr stays empty) and
-execs nothing (strace-verified). The URL exists only in process memory.
-Capture trick (works): set `BROWSER` to a script that appends its argument to
-a file, and/or prepend a fake `xdg-open` to `PATH` (see
-`probe-logs/capurl.sh`). Remote login: `ssh -N -L <port>:127.0.0.1:<port>
-<host>` on the user's machine, then open the URL there; Google's redirect
-lands on the server's loopback through the tunnel. NEVER curl the loopback
-yourself: a `GET /` without the code param is treated as a failed callback
-and aborts the flow ("Authentication failed" page).
-
-Captured URL anatomy (run 5):
-
-```
-https://accounts.google.com/o/oauth2/v2/auth
-  ?response_type=code
-  &client_id=1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com
-  &redirect_uri=http%3A%2F%2F127.0.0.1%3A35293%2F
-  &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform
-        +https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email
-        +https%3A%2F%2Fwww.googleapis.com%2Fauth%2Faicode
-  &state=<random>
-  &access_type=offline
-  &prompt=consent
-  &code_challenge=<S256>
-  &code_challenge_method=S256
-```
-
-Timing: the onboarding window is minutes-scale (one flow timed out at ~8.5
-minutes; a second completed within ~1.5 minutes). Tokens persist at
-`~/.gemini/antigravity-acp/acp_token.json` (0600; 510 bytes; credential —
-never copy). A second server run after successful auth has NOT yet been
-tested (token-reuse across restart is a remaining probe).
-
-## session/new
-
-Request:
-
-```json
-{"jsonrpc":"2.0","id":3,"method":"session/new","params":{"cwd":"/abs/cwd","mcpServers":[]}}
-```
-
-Result (verbatim, this is also the model catalog + config schema):
-
-```json
-{"sessionId":"4d5a6c89-0be5-4d98-ac4d-dede75c780fe",
- "modes":{"currentModeId":"default","availableModes":[
-   {"id":"default","name":"Default","description":"Default permission prompt flow"},
-   {"id":"auto_edit","name":"Auto Edit","description":"Auto-approve file edit tools"},
-   {"id":"yolo","name":"YOLO","description":"Auto-approve all tools"}]},
- "models":{"availableModels":[
-   {"modelId":"gemini-3.8-flash-high","name":"Gemini 3.8 Flash (High)","description":"gemini-3.8-flash-high"},
-   {"modelId":"gemini-3.8-flash-medium","name":"Gemini 3.8 Flash (Medium)","description":"gemini-3.8-flash-medium"},
-   {"modelId":"gemini-3.8-flash-low","name":"Gemini 3.8 Flash (Low)","description":"gemini-3.8-flash-low"},
-   {"modelId":"gemini-3.7-flash-high","name":"Gemini 3.7 Flash (High)","description":"gemini-3.7-flash-high"},
-   {"modelId":"gemini-3.7-flash-medium","name":"Gemini 3.7 Flash (Medium)","description":"gemini-3.7-flash-medium"},
-   {"modelId":"gemini-3.7-flash-low","name":"Gemini 3.7 Flash (Low)","description":"gemini-3.7-flash-low"},
-   {"modelId":"gemini-3.6-flash-high","name":"Gemini 3.6 Flash (High)","description":"gemini-3.6-flash-high"},
-   {"modelId":"gemini-3.6-flash-medium","name":"Gemini 3.6 Flash (Medium)","description":"gemini-3.6-flash-medium"},
-   {"modelId":"gemini-3.6-flash-low","name":"Gemini 3.6 Flash (Low)","description":"gemini-3.6-flash-low"},
-   {"modelId":"gemini-pro-agent","name":"Gemini 3.1 Pro (High)","description":"gemini-pro-agent"},
-   {"modelId":"gemini-3.1-pro-low","name":"Gemini 3.1 Pro (Low)","description":"gemini-3.1-pro-low"}],
-  "currentModelId":"gemini-3.7-flash-high"},
- "configOptions":[
-  {"currentValue":"gemini-3.7-flash-high","id":"model","name":"Model","category":"model","type":"select","options":[{"value":"gemini-3.8-flash-high","name":"Gemini 3.8 Flash (High)","description":"..."}, "...all 11..."]},
-  {"currentValue":"default","id":"mode","name":"Session Mode","category":"mode","type":"select","options":[{"value":"default","name":"Default","description":"Default permission prompt flow"},{"value":"auto_edit","name":"Auto Edit","description":"Auto-approve file edit tools"},{"value":"yolo","name":"YOLO","description":"Auto-approve all tools"}]}]}
-```
-
-Key facts:
-
-- `sessionId` is a UUID, chosen by the server.
-- The FULL model catalog ships in `session/new` (the `agy models` CLI is not
-  needed for the ACP engine). Default model: `gemini-3.7-flash-high`.
-- Model ids are FULL slugs with the effort tier baked in
-  (`gemini-3.8-flash-low` = Flash, low effort). One `--model`-style split is
-  NOT needed here. `gemini-pro-agent` is the 3.1 Pro High slug (differs from
-  the CLI's `gemini-3.1-pro-high` print).
-- Modes map onto our config knobs: `default` = permission prompt flow,
-  `auto_edit` ≈ `--mode accept-edits` for edit tools, `yolo` ≈
-  `--dangerously-skip-permissions`.
-- `mode` and `model` are both `configOptions` (`type: select`), settable via
-  `session/set_config_option`.
-- `availableCommands` arrive right after via `session/update`
-  (`available_commands_update`): observed commands `plan` ("generates an
-  implementation plan artifact and awaits user approval") and `logout`.
-
-## session/set_config_option
-
-Request (param is `configId`, NOT `configOptionId` — wrong name gives -32602
-`errors:[{"loc":["configId"],"msg":"field required"}]`):
-
-```json
-{"jsonrpc":"2.0","id":5,"method":"session/set_config_option","params":{"sessionId":"<uuid>","configId":"model","value":"gemini-3.8-flash-low"}}
-```
-
-Result: the full `configOptions` array with `currentValue` updated
-(`"currentValue":"gemini-3.8-flash-low"` observed). LIVE VERIFIED: model and
-effort switch per session with no process recycle. Mode switch
-(`configId:"mode"`) is expected to work identically (same option shape) but
-was not explicitly exercised.
-
-## session/prompt
-
-Request (`prompt` is an array of typed content blocks):
-
-```json
-{"jsonrpc":"2.0","id":6,"method":"session/prompt","params":{"sessionId":"<uuid>","prompt":[{"type":"text","text":"Reply with exactly: HELLO ACP. Do not use any tools."}]}}
-```
-
-Streaming: `session/update` NOTIFICATIONS (no id), then the `session/prompt`
-response. Discriminator is `update.sessionUpdate`.
-
-`agent_message_chunk` (verbatim):
-
-```json
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"<uuid>","update":{"content":{"text":"HELLO ACP.","type":"text"},"sessionUpdate":"agent_message_chunk"}}}
-```
-
-Terminal response:
-
-```json
-{"jsonrpc":"2.0","id":6,"result":{"stopReason":"end_turn"}}
-```
-
-Observed stop reasons so far: `end_turn` only. Schema enumerates
-`max_tokens`, `max_turn_requests`, `refusal`, `cancelled` (cancelled
-unreachable on RC01 — no cancel method).
-
-`available_commands_update` (verbatim):
-
-```json
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"<uuid>","update":{"availableCommands":[{"name":"plan","description":"Plan carefully before executing a task (generates an implementation plan artifact and awaits user approval)."},{"name":"logout","description":"Log out and clear stored credentials."}],"sessionUpdate":"available_commands_update"}}}
-```
-
-### Streaming behavior (300-line and 3000-line stress writes)
-
-- Chunks are pure DELTAS. Verified by content: numbers split mid-token across
-  chunk boundaries (`"...\n39\n40\n4"` then `"1\n42\n43..."`), and no chunk
-  ever contained a full prefix of the accumulated text. The stream-json
-  cumulative-resend failure mode was NOT observed over ACP (defensive guard
-  stays cheap insurance).
-- Throughput: 300 numbers (~600 tokens) completed within one 25 s poll;
-  3000 numbers streamed continuously at roughly 100 numbers per 1.5 s.
-- Ordering: notifications strictly before the prompt response; no
-  interleaving with other responses observed.
-
-### Usage
-
-NO usage/token fields appeared anywhere in `initialize`, `session/new`,
-`set_config_option`, `agent_message_chunk`, prompt results, or tool flows
-(run 6). Gate B FINAL: ABSENT on RC01. Consequence in the plan (updated
-2026-09-07): Gate B is INFORMATIONAL - zero-usage is documented and accepted
-on ACP, never a blocker. Both engines are permanently maintained peers; no
-deletion is planned.
-
-## session/cancel
-
-**NOT IMPLEMENTED on RC01** (despite appearing in the ACP schema source and
-our plan):
-
-```json
-{"jsonrpc":"2.0","id":12,"method":"session/cancel","params":{"sessionId":"<uuid>"}}
-{"jsonrpc":"2.0","id":12,"error":{"code":-32601,"message":"Method not found","data":{"method":"session/cancel"}}}
-```
-
-An in-flight `session/prompt` CANNOT be stopped over the protocol on this
-build (verified: a 3000-number stream ran to completion after cancel
-returned -32601). Abort fallback candidate: kill the connection and
-`session/load` on the next server (probe pending).
-
-## Error shapes (verified)
-
-```jsonc
-// -32602 Invalid params (wrong/missing param name) — includes field location
-{"code":-32602,"message":"Invalid params","data":{"errors":[{"loc":["methodId"],"msg":"field required","type":"value_error.missing"}]}}
-// -32000 server-state errors — message + data{message|reason}
-{"code":-32000,"message":"Authentication required","data":{"message":"..."}}
-{"code":-32000,"message":"Onboarding failed: ...","data":{"reason":"onboarding_failed"}}
-// -32601 method not implemented
-{"code":-32601,"message":"Method not found","data":{"method":"session/cancel"}}
-```
-
-Note the schema-mismatch pattern: two live params differ from the obvious
-names (`methodId` not `method`; `configId` not `configOptionId`). Expect
-thirds; code against captured examples, and treat -32602 `loc` as the
-correction oracle.
-
-## Server-side persistence (on-disk formats)
-
-`~/.gemini/antigravity-acp/` layout:
-
-| Path | Purpose |
-| --- | --- |
-| `settings.json` | auth config (world-readable 0644); read at startup only |
-| `acp_token.json` | OAuth tokens (0600). CREDENTIAL. Never copy or print. |
-| `conversations/<uuid>.db` | SQLite 3 conversation DB (WAL mode; 163 KB main + 4 MB WAL for our probe session) |
-| `conversations/<uuid>.db-wal`, `.db-shm` | WAL pair |
-| `conversations/<uuid>.meta` | 46-byte JSON: `{"cwd":"<session cwd>"}` |
-
-Session ids match conversation DB file stems (our `sessionId`
-`4d5a6c89-0be5-4d98-ac4d-dede75c780fe` → `conversations/4d5a6c89-....db`).
-
-Snapshot DDL (`probe-logs/acp-server-conversations/schema.sql`; 7 tables):
-
-```sql
-CREATE TABLE `trajectory_meta` (`trajectory_id` text,`cascade_id` text,`trajectory_type` integer,`source` integer,PRIMARY KEY (`trajectory_id`));
-CREATE TABLE `steps` (`idx` integer,`step_type` integer NOT NULL DEFAULT 0,`status` integer NOT NULL DEFAULT 0,`has_subtrajectory` numeric NOT NULL DEFAULT false,`metadata` blob,`error_details` blob,`permissions` blob,`task_details` blob,`render_info` blob,`step_payload` blob,`step_format` integer NOT NULL DEFAULT 0,PRIMARY KEY (`idx`));
-CREATE TABLE `gen_metadata` (`idx` integer,`data` blob,`size` integer NOT NULL DEFAULT 0,PRIMARY KEY (`idx`));
-CREATE TABLE `executor_metadata` (`idx` integer,`data` blob,PRIMARY KEY (`idx`));
-CREATE TABLE `parent_references` (`idx` integer,`data` blob,PRIMARY KEY (`idx`));
-CREATE TABLE `trajectory_metadata_blob` (`id` text DEFAULT "main",`data` blob,PRIMARY KEY (`id`));
-CREATE TABLE `battle_mode_infos` (`idx` integer,`data` blob,PRIMARY KEY (`idx`));
-```
-
-Two facts matter for us:
-
-1. `steps.step_payload` is an OPAQUE BLOB — the same two-phase-write SQLite
-   blob family that silently broke the pre-1.3.2 legacy engine (issue #1).
-   Never poll these DBs; that decision is re-validated by this schema.
-2. WAL quirk: a read-only open of the live `.db` shows an EMPTY
-   `sqlite_master` (schema lives in the WAL until checkpoint); copying
-   `db+wal+shm` yields a copy that also reads empty (stale `-shm` suppresses
-   replay). To snapshot: `VACUUM INTO` from an opened connection (that is how
-   `probe-logs/acp-server-conversations/probe-session-4d5a6c89.db` was made).
-
-## Client capability posture (phase 1 decision, verified harmless)
-
-`initialize` sent `fs:false`, `terminal:false`. Effects observed: `session/new`
-and pure-text prompts work; the agent self-executes its own tools and asks
-via `session/request_permission` (verified in run 6, tool probe). No `fs/*`
-or `terminal/*` delegation occurred with capabilities off.
-
-## Timing summary (Gate E evidence)
-
-| Event | Observation |
-| --- | --- |
-| Spawn → initialize response | ~5-6 s (three runs, consistent; 1.5 GB binary, page cache warm) |
-| session/new response | < 2 s |
-| set_config_option response | < 1 s |
-| Prompt first chunk | ~1-2 s (Flash, low effort) |
-| OAuth onboarding window | minutes-scale; one timeout observed at ~8.5 min |
-| Bridge `tools/call` HTTP request | agy's MCP client abandons the request at ~180s (observed twice at exactly 180.000s on 2026-09-05: AskClaude at 225.7s, then a follow-up exec_command). Mitigations: the bridge early-acks any call still running after ~20s with a poll handle (`bridge_poll_result`, `call-tool-escalated` log event) so the request never reaches the deadline; escalated parks re-arm at 30 min for human-gated latency; a result that outlives polling is re-delivered as a new same-conversation prompt (late delivery, `late-result` log event). `mcp-server` logs `progress-token` when a request carries `_meta.progressToken`: if agy ever sends one, progress notifications become a testable zero-UX fix |
-| Steady RSS | ~327 MB (5 min mixed load; VSZ ~5.3 GB is TCMalloc reservation) |
-
-## Run 6 findings (2026-09-03, post-restart session; raw traffic
-`probe-logs/acp-traffic-run6-restart-load-tools.jsonl`, 28 clean JSONL lines)
-
-All remaining probes executed. Results:
-
-1. **Token persistence: PASS.** New server process, `session/load` with NO
-   `authenticate` call succeeded. `acp_token.json` + `settings.json` carry
-   auth across restarts.
-2. **`session/load`: PASS.** Params `{sessionId, cwd, mcpServers}`. On
-   success the server REPLAYS the whole conversation as `session/update`
-   notifications: `user_message_chunk` / `agent_message_chunk` PAIRS per
-   turn, in order. Replay re-sends prior replies as FULL TEXT (one giant
-   chunk), not the original deltas. Driver rule: on load, incoming chunks
-   are HISTORY replay, never live generation. Then:
-   `available_commands_update`.
-3. **Config does NOT persist across restart.** The loaded session came back
-   `currentModelId: gemini-3.7-flash-high` (default) although it had been
-   switched to `gemini-3.8-flash-low` before the kill. Model/effort/mode
-   must be re-applied by the driver after every restart/load.
-4. **`session/request_permission` verified live.** Agent-to-client REQUEST:
-   `{sessionId, toolCall{...full tool_call object incl. diff content...},
-   options:[{optionId:"allow",name:"Allow",kind:"allow_once"},
-   {optionId:"deny",name:"Deny",kind:"reject_once"}]}`. Client answers:
-   `{"outcome":{"outcome":"selected","optionId":"allow"}}`. Only once-kinds
-   observed (no allow_always in this payload).
-5. **`tool_call` / `tool_call_update` shapes verified.** Fields:
-   `toolCallId`, `title` ("Run create_file?"), `kind` (`edit`/`read`),
-   `status` lifecycle `pending → in_progress → completed|failed`, `content`
-   with `{type:"diff", path, newText, _meta:{kind:"add"}}` (the edit arrives
-   AS A DIFF), `locations:[{path}]`, `rawInput` (full args object), optional
-   `rawOutput` on completion. Gate C PASS: enough content to retire
-   wrapper-replay rendering later.
-6. **toolCallId formats are inconsistent:** `33eb71a0...` (32-hex),
-   `<sessionId>:7` (composite), `call_859008` (OpenAI-style). Treat as
-   opaque strings.
-7. **Approved-id supersede quirk.** After `allow`, the approved
-   `create_file` call reported `status:"failed",
-   rawOutput:"Tool call was approved but never executed."` while the actual
-   edit executed under a different toolCallId (`<sessionId>:7`,
-   `edit_file`) and succeeded (file created, read back, confirmed).
-   Never assume approved toolCallId == executed toolCallId; track effects,
-   not ids.
-8. **Image prompt: PASS end-to-end.** 1x1 red PNG as `{type:"image",
-   data:<base64>, mimeType:"image/png"}` + text question → answer "Red".
-   (Community reports said the agy CLI was broken for images; the ACP path
-   works.)
-9. **Gate F: PASS at shape level.** Accepted entry:
-   `{"name":"pi-bridge","type":"http","url":"http://...","headers":[]}`.
-   `headers` is a LIST. Permitted types: `http`, `sse` (same headers
-   shape), stdio (`command`/`args`/`env`), and an `acp` type (needs `id`).
-   A DEAD url is accepted at `session/new` (connection is lazy). Phase-1
-   TODO: point at the real bridge (MCP SDK Streamable HTTP) and confirm the
-   agent's http client completes `tools/list` + `tools/call` (G9
-   round-trip end-to-end).
-10. **`session/set_mode` (`modeId`) and `session/close` work** (`{}`
-    results). `close` is per-session; the connection survives it.
-    `set_mode` and `set_config_option("mode")` are redundant paths to the
-    same state.
-11. **Usage: ABSENT on RC01 (Gate B final).** No token fields in any
-    payload across both runs, including tool flows. Accept zero-usage
-    (existing documented fallback); re-check on future builds.
-12. **Steady RSS ~327 MB** under 5 minutes of mixed load.
-
-Probe session closed cleanly (`session/close` then kill). Final gate status:
-plan section 8.1.
-
-## Phase-2 probe findings (2026-09-03; raw traffic
-`probe-logs/acp-phase2-traffic.jsonl`, one session, four labeled prompts,
-all `end_turn`)
-
-1. **`agent_thought_chunk` is SPARSE on RC01.** A step-by-step math prompt
-   produced ZERO thought chunks - the reasoning shipped as plain
-   `agent_message_chunk` text. The only thought chunk in the capture came
-   from the `/plan` flow. Shape is identical to the message chunk
-   (`content:{type:"text",text}`), already mapped. Consequence: the
-   thinking-block pipeline rarely renders on flash-low; do not build UI
-   assumptions on frequent thought deltas.
-2. **Image prompts: PASS at real resolution.** 64x64 two-tone PNG (top
-   red / bottom blue) sent as `{type:"image",data,mimeType}` blocks ahead
-   of the text block answered "Top: Red, Bottom: Blue". Mixed
-   image+text prompt arrays work; no 1x1-only limitation.
-3. **Tool frames: three mappings the phase-1 driver got wrong.**
-   - MCP tools wrap args in an envelope: `rawInput:{arguments:{text}}`.
-     Native `edit_file` carries args directly (`rawInput:{file_path}`).
-   - MCP tool titles are "<server>_<tool>" ("pi-bridge_bridge_echo"); the
-     clean name hides in `_meta.mcp.tool`.
-   - A completed `tool_call_update`'s `rawOutput` is the server's DISPLAY
-     string, often just the tool title ("Call bridge_echo"), NOT the
-     result. `content[]` entries wrap their payload
-     (`{type:"content",content:{type:"text",text}}`); for edits the same
-     array carries the real diff (`newText`...). The MCP result itself
-     reaches the model out-of-band: the client answered ECHO:PROBE-9
-     correctly without the result ever appearing in an update.
-4. **`/plan` command flow (F.7 answered: the server INTERCEPTS leading
-   slash commands).** "/plan Organize a birthday party" produced: one
-   `agent_thought_chunk`, a `create_file` tool_call with the full plan
-   diff in `content[]`, an `edit_file` into the server's brain dir
-   (`~/.gemini/antigravity-acp/brain/<sessionId>/...`), and a closing
-   message asking for decisions. It WRITES under the auto permission
-   policy. **Verdict: ACP has NO review-only mode.** The three modes
-   (default/auto_edit/yolo) are permission modes only; the CLI's
-   `--mode plan` has no ACP equivalent. The committed exception stands:
-   plan delegations keep `agy -p --mode plan`.
-5. **No `plan` sessionUpdate type exists** on RC01. Plan artifacts arrive
-   as ordinary edit `tool_call`s (rendered as tool cards), not as a
-   distinct update stream. The phase-2 idea "plan updates as thinking
-   labels" is observed-absent, not deferred.

package/docs/ANTIGRAVITY-INTEGRATIONS.md

@@ -1,50 +0,0 @@
-# Antigravity Editor Integrations: Reverse Engineered Internals (historical)
-
-Date of original research: 2026-08-21 (full 551-line analysis preserved in git
-history; this stub summarizes what still matters). Sources: the official VSIX
-`Google.google-antigravity_1.0.0`, Zed's external-agents registry cache, the
-ACP release zip from `dl.google.com`, and the binaries on this machine — all
-verified by direct inspection or live execution.
-
-> **2026-09-04 status:** the ACP adoption this doc originally planned is
-> SHIPPED (phases 0-3 of docs/ACP-ADOPTION-PLAN.md). Everything about the ACP
-> server's protocol now lives in docs/ACP-PROTOCOL-REFERENCE.md (far more
-> complete than section 3 below); the adoption decision and trade-offs live
-> in ACP-ADOPTION-PLAN.md sections 1, 4, and 8.1 (superseding sections 9-10
-> here). The VSIX internals below are retained as ecosystem reference only —
-> this bridge uses Mechanism B and has no plans to touch Mechanism A.
-
-## The three mechanisms (executive summary)
-
-1. **Mechanism A, VS Code and JetBrains extension**: the extension spawns
-   `agy --hub` (hidden flag; `AGY_ENABLE_HUB=1`), a local HTTP server serving
-   the complete Antigravity web UI, embedded in an iframe. The webapp drives
-   the agent over an internal WebSocket protocol; IDE capabilities flow
-   through a protobuf RPC bridge over postMessage. Never documented by
-   Google.
-2. **Mechanism B, Zed and any ACP client**: Google publishes
-   `agy_acp_server`, a dedicated binary speaking Agent Client Protocol v1,
-   JSON-RPC over stdio. The sanctioned programmatic surface — this is what
-   the bridge's ACP engine drives.
-3. **Hidden, `agy agentapi`**: an undocumented subcommand that proxies
-   conversation control into a running Antigravity IDE language server over
-   HTTP via the `ANTIGRAVITY_LS_ADDRESS` environment variable. Documented
-   nowhere else; potential future integration surface, unexamined.
-
-## Facts worth keeping
-
-- Two distinct `agy` install locations exist: `~/.local/bin/agy` (the
-  self-updating CLI, what `agy install` configures) and `~/.gemini/bin/agy`
-  (where the VS Code extension's auto-installer pins its own copy). They are
-  independent and can be different versions.
-- The VSIX auto-installer resolves binaries from
-  `https://antigravity-cli-auto-updater-974169037036.us-central1.run.app/manifests/{goos}_{goarch}.json`
-  (production) or a GCS dogfood bucket, verifies sha256/sha512 when present,
-  and installs to `~/.gemini/bin/agy`.
-- The hub process signals OAuth via the stdout prefix
-  `ANTIGRAVITY_OPEN_URL:`; the extension opens the URI with
-  `vscode.env.openExternal`. (The bridge's ACP auth uses the same
-  loopback-redirect OAuth flow via the BROWSER-capture trick — see
-  docs/ACP-PROTOCOL-REFERENCE.md.)
-- The ACP conversation store is per-session SQLite with opaque
-  `steps.step_payload` blobs. Never poll these DBs.

package/docs/APPROVAL-GATE.md

@@ -1,33 +0,0 @@
-# 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.