@estebanforge/pi-antigravity-bridge 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.1] - 2026-09-15
+
+### Fixed
+
+- Delegated agy no longer sees the pi tool bridge. `AskAntigravity` spawns `agy -p`, and any agy on the machine discovers MCP servers from the global `~/.gemini/config/mcp_config.json`, which carries a live `pi-bridge-*` entry for every running pi session. A delegation could therefore connect to a host bridge and call tools (observed live: `memory_search`), which the round-trip store denies fail-closed with "no active antigravity turn" the moment no provider turn is streaming - a dead end for the delegation and an error toast in the host session. The bridge entries are now suppressed while a delegated agy starts: disabled before the spawn, re-enabled on process close or after a 5s grace, whichever lands first. Suppression is reference-counted, so overlapping delegations cannot re-enable early; session start re-enables any entries a crashed delegation left disabled. Foreign MCP servers in the file are never touched. Residual race, documented in code: another session's provider agy respawning inside the window reads the entries disabled and that process lacks bridge tools until its next recycle.
+- Real bridge tool-call failures now land on disk in default mode. The daily log records only errors, and `call-tool-fail` was logged at warn tier (toast only), so a failure like the one above left no durable trace. Genuine rejections now log at error tier; routine turn-end and shutdown aborts stay silent, with the reasons shared as constants between the emit sites and the log classifier so the two cannot drift.
+
+### Changed
+
+- README corrected: the bridge mechanism section described only the dir-scoped discovery and claimed the user's global agy config is never touched. Global per-pid registration shipped earlier and is now documented, along with the delegation suppression and its window.
+
 ## [1.5.0] - 2026-09-08
 
 ### Added

package/README.md

@@ -2,11 +2,16 @@
 
 A Gemini model provider **and** the `AskAntigravity` delegation tool for [pi](https://github.com/earendil-works/pi-coding-agent), built on Google's official Antigravity binaries: the `agy` CLI by default, or **Google's official ACP server** (opt-in). It registers `antigravity/gemini-*` models in pi's `/model` picker (streaming), and provides the `AskAntigravity` tool for one-shot delegation - the same combined shape as `pi-claude-bridge`.
 
-<img width="2566" height="1723" alt="SCR-20260903-sefo" src="https://github.com/user-attachments/assets/20f0c04c-d622-4b11-962a-3478f64570c2" align="center"/>
+<p>
+  <img width="1374" height="869" alt="image" src="https://github.com/user-attachments/assets/fdd6c1f0-5144-40ef-9371-77a94de50b76" align="center" />
+</p>
+<p>
+  <img width="1376" height="451" alt="SCR-20260908-mbox" src="https://github.com/user-attachments/assets/d105c8a7-1ace-42f7-8285-642150453761" align="center" />
+</p>
+<p>
+  <img width="1375" height="1342" alt="SCR-20260908-mbvc" src="https://github.com/user-attachments/assets/bb614c55-e0f8-4677-bb0e-6541071e91ef" align="center" />
+</p>
 
-<br/><br/>
-
-<img width="1272" height="842" alt="SCR-20260903-sfcu" src="https://github.com/user-attachments/assets/c483613b-10ff-4d2f-9893-027d84130ac6" align="center" />
 
 If you also have [`@estebanforge/pi-ask-antigravity`](https://github.com/EstebanForge/pi-ask-antigravity) installed, this bridge takes over: pi-ask-antigravity detects the bridge and registers nothing, so the `AskAntigravity` tool is never duplicated.
 
@@ -43,13 +48,13 @@ Residual limits (with or without the bridge):
 
 While agy is the active model it normally cannot see pi's universe of extensions: agentmemory, codegraph, web search, slack/asana, the `Ask*` delegations, and any other installed pi tool. This extension optionally bridges that gap.
 
-The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. agy discovers the server through a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the provider passes that dir as an extra `--add-dir` when it spawns agy. The user's global agy config (`~/.gemini/config/mcp_config.json`) is never touched, so standalone agy outside pi is unaffected.
+The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. Discovery has two layers. The provider's agy gets a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the driver passes that dir as an extra `--add-dir` when it spawns agy. A per-pid entry (`pi-bridge-<pid>`) is also registered in the user's global agy config (`~/.gemini/config/mcp_config.json`; foreign servers preserved, stale entries swept at start), so agy builds that read only the global config still find the bridge.
 
 **No patch required.** Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a `toolUse` stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.
 
 **Long calls don't die.** agy's MCP client abandons a `tools/call` request at a flat ~180s, which used to kill any pi tool that ran longer (a long peer review, a build, a commit preview waiting for you). A call still running after ~20 seconds now settles its HTTP request with a `STILL RUNNING` answer carrying a `callId` while pi keeps executing; agy fetches the result through the bridge-local `bridge_poll_result` tool and polls until it lands. Escalated calls get their own 30-minute budget, so human-gated tools can take as long as the human takes. Fast calls stay fully synchronous and never see any of this. If a park does fail (abort, timeout, recycle), the late result is re-routed to agy as a follow-up prompt in the same conversation instead of being lost.
 
-**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. The `AskAntigravity` tool spawns its own agy with just the workspace, so that inner agy starts plain (no pi tools) and cannot re-enter. `AskAntigravity` is also filtered from the exposed tool list. Standalone agy is unaffected because nothing is written to its global config.
+**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. `AskAntigravity` is also filtered from the exposed tool list. Its delegated `agy -p` spawns with just the workspace, and while it starts the bridge suppresses its global per-pid entries: disabled before the spawn, re-enabled on process close or after a 5s grace (whichever lands first), refcounted across overlapping delegations, and re-enabled at every session start. The inner agy therefore sees no bridge and cannot re-enter pi. A hand-run agy outside pi that starts inside the seconds-wide window briefly misses the bridge; foreign servers in the global config are never touched.
 
 **Cost / fan-out.** Every registered pi tool except builtins (and `AskAntigravity`) is exposed, including other delegation tools like `AskClaude`/`AskCodex`. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.
 

package/docs/ARCHITECTURE.md

@@ -27,7 +27,7 @@ src/config.ts         persisted runtime config (engine + acp block, bridgeTools,
 src/daily-log.ts      daily NDJSON support log (one file per day, 14-day retention, secret redaction, AGY_DEBUG verbose gate); fed by both drivers, the bridge, round-trips, /agy, and ask-tool
 src/ask-tool.ts       the AskAntigravity one-shot delegation tool (model/thinking defaults)
 src/mcp-server.ts     MCP tool bridge server: ferries tools/list + tools/call; calls park in the provider round-trip. Also the approval park: POST /approval (ticket early-ack) + GET /approval/<id>, fail-closed on timeout/unwired/close
-src/mcp-registration.ts registers/unregisters the bridge in ~/.gemini/config/mcp_config.json for the stream-json CLI (per-pid, atomic, stale sweep)
+src/mcp-registration.ts registers/unregisters the bridge in ~/.gemini/config/mcp_config.json for the stream-json CLI (per-pid, atomic, stale sweep) and flips our entries off around AskAntigravity spawns (refcounted; session start re-enables)
 src/approval-gate.ts  shadow tool factory (bash/write/edit): marker calls are ticket-verified approval round-trips, non-marker calls delegate; maps agy native tools onto the shadow surface
 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)

package/docs/DEVELOPMENT.md

@@ -98,7 +98,7 @@ Most "stuck" reports trace to one of:
 - `tests/acp-driver.test.ts` - the ACP driver over the fake server (`tests/helpers/fake-acp-server.mjs`, scenario-selected): happy flow, load-replay, permission auto-answer, Gate D abort (cancel probe, teardown, `cancelSupported` memory), the stale-exit race (a killed connection's late exit must not fail its replacement - `ACP_FAKE_SLOW_DEATH_MS`), auth errors, park/kickIdle timer pause with remaining budget.
 - `tests/acp-config.test.ts` - engine selection narrowing (`AGY_ENGINE`/`config.engine`), acp block parsing.
 - `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/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, delegation suppression (`setBridgeEntriesDisabled` flip/restore/idempotence, refcounted `acquireBridgeSuppression`).
 - `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.

package/extensions/index.ts

@@ -72,6 +72,7 @@ import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.j
 import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
 	registerBridgeServer,
+	setBridgeEntriesDisabled,
 	sweepStaleBridgeServers,
 	unregisterBridgeServer,
 } from "../src/mcp-registration.js";
@@ -131,6 +132,12 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	const modelInput: Array<"text" | "image"> = engine === "acp" ? ["text", "image"] : ["text"];
 	const models = entries.map((e) => toPiModel(e, modelInput));
 
+	// failAll reasons the bridge treats as routine (turn end / shutdown
+	// sweep), not faults. Shared by the emitters below and the mcpLog
+	// classifier so the substring match cannot drift from the text.
+	const FAIL_REASON_TURN_END = "antigravity turn ended with an unresolved pi tool call";
+	const FAIL_REASON_SHUTDOWN = "antigravity session shut down";
+
 	// Daily file log: every sink below feeds ~/.pi/extensions-data/
 	// estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson (see
 	// src/daily-log.ts). Fire-and-forget, secrets redacted, old days pruned.
@@ -140,14 +147,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// routine disk traffic), so a warn that never reaches the UI is lost.
 	// Every warn toasts here instead; AGY_DEBUG=1 restores the full file
 	// trail. Silent exceptions: deliberate aborts (pi already shows
-	// "Operation aborted"), connection exits (the turn's own error block
-	// carries real crashes), and call-tool-fail (same-instant duplicate of
-	// round-trip-fail). No UI (headless): warn text falls back to stderr.
+	// "Operation aborted") and connection exits (the turn's own error block
+	// carries real crashes). call-tool-fail needs no exclusion here: its tier
+	// is debug or error, never warn. No UI (headless): warn text falls back
+	// to stderr.
 	const rawFileLog = fileLog.log.bind(fileLog);
 	fileLog.log = (event, data, level) => {
 		rawFileLog(event, data, level);
 		if (level !== "warn") return;
-		if (event.startsWith("abort:") || event === "connection-exited" || event === "call-tool-fail") return;
+		if (event.startsWith("abort:") || event === "connection-exited") return;
 		const d = (data ?? {}) as Record<string, unknown>;
 		let text: string;
 		if (event === "round-trip-fail") {
@@ -341,7 +349,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			{ status: outcome.status, error: outcome.error?.slice(0, 500), aborted: outcome.aborted },
 			outcome.status === "OK" ? "info" : "warn",
 		);
-		roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+		roundTrips.failAll(FAIL_REASON_TURN_END);
 	};
 	streamDriver.onTurnEnd = onTurnEnd;
 	acpDriver.onTurnEnd = onTurnEnd;
@@ -593,18 +601,27 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			// filters below only decide what reaches the user. Bridge calls
 			// start/end at info (one record per tool call, the fragile-path
 			// skeleton); list-tools and startup chatter stay verbose.
-			const level = failures.has(s)
-				? "warn"
-				: s === "call-tool" || s === "call-tool-ok"
+			// Routine abort traffic (failAll on turn end / session shutdown
+			// answers every parked call with an error) is not a fault: debug
+			// only. Any other call-tool-fail is a real rejection (e.g. "no
+			// active antigravity turn" from a client that should not see the
+			// bridge) and lands at error tier - default mode records errors
+			// only, so this is the sole durable trace of the incident.
+			const detail = (d as { msg?: string } | undefined)?.msg ?? "";
+			const routineAbort =
+				s === "call-tool-fail" &&
+				(detail.includes(FAIL_REASON_TURN_END) || detail.includes(FAIL_REASON_SHUTDOWN));
+			const level = !failures.has(s)
+				? s === "call-tool" || s === "call-tool-ok"
 					? "info"
-					: "debug";
+					: "debug"
+				: routineAbort
+					? "debug"
+					: s === "call-tool-fail"
+						? "error"
+						: "warn";
 			fileLog.log(s, d, level);
-			// Routine abort traffic: failAll fires on turn end / session shutdown
-			// and the bridge answers every parked call with an error. Not a fault.
-			if (s === "call-tool-fail") {
-				const detail = (d as { msg?: string } | undefined)?.msg ?? "";
-				if (detail.includes("unresolved pi tool call") || detail.includes("session shut down")) return;
-			}
+			if (routineAbort) return;
 			if (!failures.has(s)) return;
 			const msg = `[antigravity-bridge mcp] ${s}${d !== undefined ? " " + JSON.stringify(d) : ""}`;
 			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
@@ -708,11 +725,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		);
 		if (r.ok && r.handle) {
 			mcpHandle = r.handle;
-			// Stream-json engine registration: the agy CLI discovers MCP servers
-			// from ~/.gemini/config/mcp_config.json (ACP uses session/new
-			// mcpServers instead; verified live 2026-09-07). Per-pid entry,
-			// removed at session_shutdown; stale entries swept at start.
+			// Stale entries swept at start; entries a crashed delegation left
+			// suppressed are healed here (live bridges start every session
+			// enabled).
 			sweepStaleBridgeServers();
+			setBridgeEntriesDisabled(false);
 			registerBridgeServer({
 				pid: process.pid,
 				port: r.handle.port,
@@ -816,7 +833,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
-		roundTrips.failAll("antigravity session shut down");
+		roundTrips.failAll(FAIL_REASON_SHUTDOWN);
 		// "recycle", NOT "shutdown": pi fires session_shutdown on /new, /resume
 		// and /fork (docs/extensions.md session lifecycle), not only on process
 		// exit. The drivers are process-lifetime singletons; closing them with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "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/ask-tool.ts

@@ -25,6 +25,7 @@ import {
 	snapshotConversations,
 } from "./discovery.js";
 import { loadConfig, type AgyMode, type ThinkingTier } from "./config.js";
+import { acquireBridgeSuppression } from "./mcp-registration.js";
 import { spawnAgyModelsRaw } from "./models.js";
 
 // --- Constants -------------------------------------------------------------
@@ -46,6 +47,15 @@ const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
 	pro: "high",
 	other: "medium",
 };
+
+/** Bridge-suppression grace for a delegated `agy -p`. The shared config stays
+ *  disabled for min(process close, this): agy reads it once at startup, so
+ *  this bound covers that read without staying disabled for the whole run.
+ *  Residual race: a provider agy respawn in ANOTHER session landing inside
+ *  the window reads the entries disabled and that process lacks bridge tools
+ *  until its next recycle (session start heals the file). Fail-open past the
+ *  window = status-quo behavior. */
+const BRIDGE_SUPPRESS_MS = 5000;
 const TIER_RANK: Record<ThinkingTier, number> = { low: 0, medium: 1, high: 2 };
 
 // Static alias overlay for non-Gemini models agy may or may not surface.
@@ -510,6 +520,31 @@ export async function registerAskAntigravityTool(
 			const binary = process.env.AGY_BIN || "agy";
 			let out = "";
 
+			// Delegation isolation: any agy on this machine reads the global
+			// mcp_config.json, so this spawned `agy -p` would discover live
+			// pi-bridge-* entries and call tools the host bridge cannot serve
+			// outside a live provider turn ("no active antigravity turn").
+			// Delegation isolation: any agy on this machine reads the global
+			// mcp_config.json, so this spawned `agy -p` would discover live
+			// pi-bridge-* entries and call tools the host bridge cannot serve
+			// outside a live provider turn ("no active antigravity turn").
+			// Window = min(close, grace): the release fires on process close or
+			// after BRIDGE_SUPPRESS_MS, whichever lands first. Refcounted, so an
+			// overlapping delegation cannot re-enable early. A refused config
+			// fail-opens to the status quo.
+			const releaseBridge = acquireBridgeSuppression();
+			let suppressTimer: ReturnType<typeof setTimeout> | undefined = setTimeout(
+				releaseBridge,
+				BRIDGE_SUPPRESS_MS,
+			);
+			const restoreBridge = (): void => {
+				if (suppressTimer) {
+					clearTimeout(suppressTimer);
+					suppressTimer = undefined;
+				}
+				releaseBridge();
+			};
+
 			const statusInterval = onUpdate
 				? setInterval(() => {
 						const elapsed = Math.floor((Date.now() - start) / 1000);
@@ -592,6 +627,7 @@ export async function registerAskAntigravityTool(
 						if (watchdog) clearTimeout(watchdog);
 						if (sigkillTimer) clearTimeout(sigkillTimer);
 						if (signal) signal.removeEventListener("abort", onAbort);
+						restoreBridge();
 					};
 					const onAbort = () => killTree();
 
@@ -698,6 +734,9 @@ export async function registerAskAntigravityTool(
 				return { content: [{ type: "text", text: `failed to run agy: ${msg}` }], details };
 			}
 			finally {
+				// Belt and braces: cleanup() already restores on close/error; this
+				// covers paths that never reached the process (sync spawn throw).
+				restoreBridge();
 				if (contextFile) {
 					try {
 						fs.unlinkSync(contextFile);

package/src/mcp-registration.ts

@@ -93,6 +93,61 @@ export function unregisterBridgeServer(pid: number, configPath: string = mcpConf
 	return { wrote: true };
 }
 
+/** Flip `disabled` on every pi-bridge-* entry (foreign servers untouched).
+ *
+ *  (1) Delegation isolation: the global config is read by ANY agy on the
+ *  machine, so an `agy -p` we spawn ourselves (AskAntigravity) would discover
+ *  live bridge entries and call tools the round-trip store cannot serve
+ *  outside a live provider turn (fail-closed "no active antigravity turn",
+ *  observed live 2026-09-15). agy reads the config once at startup, so a
+ *  short suppression window around the spawn hides the bridge from it.
+ *
+ *  (2) Startup healing (disabled=false): clears entries a crashed delegation
+ *  left suppressed. */
+export function setBridgeEntriesDisabled(
+	disabled: boolean,
+	configPath: string = mcpConfigPath(),
+): { wrote: boolean; changed: number; reason?: string } {
+	const read = readConfig(configPath);
+	if (!read.ok) return { wrote: false, changed: 0, reason: read.reason };
+	let changed = 0;
+	for (const [name, entry] of Object.entries(read.config.mcpServers)) {
+		if (!/^pi-bridge-\d+$/.test(name)) continue;
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const e = entry as { disabled?: unknown };
+		if ((e.disabled === true) === disabled) continue;
+		e.disabled = disabled;
+		changed++;
+	}
+	if (changed === 0) return { wrote: false, changed: 0 };
+	writeConfig(configPath, read.config);
+	return { wrote: true, changed };
+}
+
+const suppressionRefs = new Map<string, number>();
+
+/** Reference-counted suppression for a self-spawned agy process (AskAntigravity
+ *  delegation). First acquire disables every pi-bridge-* entry, last release
+ *  re-enables; nested acquires are free, so overlapping delegations in one
+ *  process cannot clobber each other's window. Same-process only: delegations
+ *  from two pi sessions still race on the shared file - accepted, fail-open
+ *  to the status-quo error. */
+export function acquireBridgeSuppression(configPath: string = mcpConfigPath()): () => void {
+	const key = path.resolve(configPath);
+	const refs = (suppressionRefs.get(key) ?? 0) + 1;
+	suppressionRefs.set(key, refs);
+	if (refs === 1) setBridgeEntriesDisabled(true, configPath);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		const left = Math.max(0, (suppressionRefs.get(key) ?? 1) - 1);
+		if (left === 0) suppressionRefs.delete(key);
+		else suppressionRefs.set(key, left);
+		if (left === 0) setBridgeEntriesDisabled(false, configPath);
+	};
+}
+
 /** Default liveness probe: can the signal be delivered? */
 function pidAlive(pid: number): boolean {
 	try {