@estebanforge/pi-antigravity-bridge 1.2.5 → 1.3.0

package/CHANGELOG.md

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

package/README.md

@@ -26,9 +26,9 @@ 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.
 
-When the capability is present the bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and `tools/call` executes them via `pi.invokeTool()`. agy discovers the server through a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the provider passes that dir as an extra `--add-dir` when it spawns agy. The user's global agy config (`~/.gemini/config/mcp_config.json`) is never touched, so standalone agy outside pi is unaffected.
+The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and `tools/call` executes them via `pi.invokeTool()`. agy discovers the server through a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the provider passes that dir as an extra `--add-dir` when it spawns agy. The user's global agy config (`~/.gemini/config/mcp_config.json`) is never touched, so standalone agy outside pi is unaffected.
 
-**Capability requirement.** `pi.invokeTool()` is not (yet) part of upstream pi. On first load with the patch missing, the extension **asks you once** whether to apply it (see [Install](#install)); once applied it activates after a full `pi` restart. Without it the bridge detects the missing capability at load time, skips the MCP server, and everything else works unchanged. See [docs/PI-INVOKETOOL-PATCH.md](docs/PI-INVOKETOOL-PATCH.md) for what the patch is, and `/agy patch status|apply|restore` to inspect, force, or undo it.
+**No patch required.** Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a `toolUse` stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.
 
 **Recursion safety.** Only the provider's agy receives the extra `--add-dir`. The `AskAntigravity` tool spawns its own agy with just the workspace, so that inner agy starts plain (no pi tools) and cannot re-enter. `AskAntigravity` is also filtered from the exposed tool list. Standalone agy is unaffected because nothing is written to its global config.
 
@@ -36,6 +36,22 @@ When the capability is present the bridge starts a localhost MCP server inside p
 
 **Security.** The MCP server binds to `127.0.0.1` only and requires a per-session shared-secret header (`x-bridge-token`) that agy sends from the bridge config; browsers cannot set custom headers on a simple cross-origin POST, so this blocks web CSRF against the loopback server. Request bodies are size-capped. This is intended for single-user developer machines: any local process running as the same user can read the token from the per-pid config and call the exposed tools, so do not run it on a shared host where you do not trust other same-user processes.
 
+### Native cards, wrapper replay, and skills (stream-json engine)
+
+Read-only agy steps (view_file, list_dir, grep_search, find_by_name) re-run as
+real pi builtins (`read`, `ls`, `grep`, `find`) when those builtins are active,
+so their cards render with pi's own renderers. Mutating and agy-specialty steps
+render through a display-only `antigravity` wrapper tool: its `execute()`
+replays the output agy already recorded, so the transcript gets proper
+toolCall/toolResult pairs without any double execution. Neither path re-runs
+anything with side effects.
+
+When the bridge is on, agy also gets one `activate_skill` tool whose enum is
+your pi Agent Skills catalog; calling it returns the SKILL.md body. The bridge
+answers it directly, no pi round-trip. `/agy doctor` prints engine state,
+driver counters, bridge port, and the last lifecycle events without spending
+tokens.
+
 ## Install
 
 > ⚠️ **Heads-up: this extension patches your `pi` install.** When it loads and
@@ -92,6 +108,18 @@ Model ids are slugified from the `agy models` output (`Gemini 3.6 Flash (Medium)
 
 If `agy models` fails at load (binary missing, auth not done, network stall), a fallback catalog still populates the picker so you get a clear runtime error instead of an empty list.
 
+### Engine and bridge surface
+
+`config.json` selects the turn engine and the bridge surface:
+
+| Key | Values | Default |
+| --- | --- | --- |
+| `engine` | `stream-json` (persistent agy process, toolUse round-trips, live usage) or `legacy-sqlite` (spawn `agy -p`, poll its SQLite) | `stream-json` |
+| `bridgeTools` | `none` (bridge off), `mcp` (pi-mcp-adapter tools), `all` (every non-builtin tool, incl. other `Ask*` delegations) | `mcp` |
+| `digest` | `off` (stable prompts; agy's prompt cache hits) or `on` (inject a delta of pi-side context - compaction summaries, other-provider turns - into each agy prompt; the delta changes every turn, so agy re-bills the full context). Enable for mixed-provider sessions where agy must see pi-side context | `off` |
+
+Env overrides: `AGY_ENGINE`, `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`. The `legacy-sqlite` engine is kept as a fallback and is scheduled for removal once the stream-json engine has burned in.
+
 ### The /agy command
 
 `/agy` configures the provider at runtime. Settings persist to `~/.pi/agent/antigravity-bridge/config.json` and take effect on the next turn.

package/docs/ARCHITECTURE.md

@@ -16,7 +16,6 @@ src/sessions.ts       atomic JSON store: pi session -> agy conversation + last s
 src/config.ts         persisted runtime config (mode, permissions, model/thinking defaults)
 src/ask-tool.ts       the AskAntigravity one-shot delegation tool (model/thinking defaults)
 src/mcp-server.ts     MCP tool bridge: exposes pi's tools to agy over Streamable HTTP
-src/patcher.ts        Auto-applies the pi.invokeTool local patch to enable the MCP tool bridge
 src/diff-render.ts    render agy's file edits as git diffs in pi's thinking stream
 ```
 

package/extensions/index.ts

@@ -36,11 +36,23 @@ import {
 	type AgyModelEntry,
 } from "../src/models.js";
 import { SessionStore } from "../src/sessions.js";
-import { createStreamSimple } from "../src/provider.js";
-import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type ThinkingTier } from "../src/config.js";
+import { ToolRoundTrips, WrapperReplay, createStreamSimple } from "../src/provider.js";
+import { AgyDriver } from "../src/driver.js";
+import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type BridgeTools, type ThinkingTier } from "../src/config.js";
 import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
-import { hasInvokeTool, startMcpServer, type McpServerHandle } from "../src/mcp-server.js";
-import { applyInvokeToolPatch, decidePatchAction, patchStatus, restorePatch } from "../src/patcher.js";
+import { startMcpServer, type McpServerHandle } from "../src/mcp-server.js";
+import {
+	ACTIVATE_SKILL_TOOL_NAME,
+	activateSkillSchema,
+	catalogSummary,
+	findSkillByName,
+	readSkillBody,
+	scanSkills,
+	type SkillLite,
+} from "../src/skills.js";
+import { mapAgyToolToNative } from "../src/native-tools.js";
+import { Type } from "typebox";
+import { patchStatus, restorePatch } from "../src/patch-cleanup.js";
 
 function resolveAgyBinary(): string {
 	return process.env.AGY_BIN || "agy";
@@ -71,7 +83,26 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	const models = entries.map(toPiModel);
 
 	const store = new SessionStore();
-	const streamSimple = createStreamSimple({ entries, store });
+	// Persistent stream-json engine + the no-patch pi-tool round-trip store.
+	// The MCP bridge parks calls here; the provider emits them as real pi
+	// toolUse turns and completes them from the next call's toolResult.
+	const driver = new AgyDriver();
+	const roundTrips = new ToolRoundTrips(driver);
+	const replay = new WrapperReplay();
+	// Native re-exec only emits for builtins actually active in the session;
+	// anything else (or an unknown name) falls back to the wrapper card.
+	const nativeActive = (name: string): boolean => {
+		try {
+			const getAll = (pi as unknown as { getAllTools: () => Array<{ name: string }> }).getAllTools.bind(pi);
+			return getAll().some((t) => t.name === name);
+		} catch {
+			return false;
+		}
+	};
+	// A settled turn cannot answer its parked calls; the driver never sees
+	// ToolRoundTrips, so the provider bridges the two here.
+	driver.onTurnEnd = () => roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+	const streamSimple = createStreamSimple({ entries, store, driver, roundTrips, replay, nativeActive });
 
 	pi.registerProvider("antigravity", {
 		name: "Antigravity (agy)",
@@ -92,7 +123,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		streamSimple,
 	});
 
-	registerAgyCommand(pi, { entries, store, usingFallback });
+	registerAgyCommand(pi, { entries, store, usingFallback, driver, getMcpPort: () => mcpHandle?.port ?? null });
 
 	// AskAntigravity tool: one-shot delegation to agy (ported from
 	// pi-ask-antigravity). When both extensions are installed, the bridge wins
@@ -100,13 +131,48 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// detects this package via import.meta.resolve).
 	await registerAskAntigravityTool(pi, toolModels);
 
-	// MCP tool bridge: expose pi's tools to agy over localhost Streamable HTTP,
-	// backed by pi.invokeTool (local patch). Capability-gated: if the running pi
-	// lacks invokeTool, startMcpServer returns { ok: false } and the bridge runs
-	// unchanged (other instances do not break). Started on session_start so it is
-	// live before the provider's first turn; torn down on session_shutdown.
+	// Display-only wrapper tool: the provider emits mutating agy steps as
+	// toolCalls against it (never re-executed - execute() replays the output
+	// agy already recorded). Empty description on purpose: no model should
+	// call it, it exists so pi renders proper toolCall/toolResult cards.
+	pi.registerTool({
+		name: "antigravity",
+		label: "Antigravity",
+		description: "",
+		parameters: Type.Object({
+			tool: Type.String({ description: "agy tool name that produced this step." }),
+			key: Type.String({ description: "Internal replay key. Do not fabricate." }),
+		}),
+		execute: async (_toolCallId, params) => {
+			const key = (params as { key?: string }).key ?? "";
+			const output = replay.take(key) ?? `(no recorded output for ${key})`;
+			return { content: [{ type: "text", text: output }], details: { replay: true } };
+		},
+	});
+
+	// 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.
 	let mcpHandle: McpServerHandle | null = null;
 	pi.on("session_start", async (_event, ctx) => {
+		// Legacy cleanup: users who ran the old consent-gated patcher still
+		// carry pi.invokeTool in their installed pi. Inert, but tell them once
+		// and offer /agy patch-cleanup. Never auto-edits the install.
+		try {
+			if (!loadConfig().patchCleanupNotified && patchStatus().present) {
+				// Flag after surfacing, not before: headless sessions log to
+				// stderr (ctx.ui.notify is a no-op without a UI), so the notice
+				// is never silently dropped.
+				const msg =
+					"Your pi install still carries the old pi.invokeTool patch. It is unused and harmless; a pi update also removes it. To restore the original files from the backup now: /agy patch-cleanup";
+				if (ctx.hasUI) ctx.ui.notify(msg, "info");
+				else console.error(`[antigravity-bridge] ${msg}`);
+				saveConfig({ patchCleanupNotified: true });
+			}
+		} catch {
+			/* detection is best-effort */
+		}
 		// Bridge lifecycle/error logger. Routes through ctx.ui.notify (an
 		// ephemeral toast that fades) instead of stderr: pi's TUI captures stderr
 		// and pins it above the input for the whole session, which left the
@@ -131,79 +197,65 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				console.error(msg);
 			}
 		};
-		// Decide the pi.invokeTool patch + MCP tool bridge path. The patch is only
-		// needed for the bridge; the provider and AskAntigravity tool always work.
-		// The bridge can only start when the patch is LIVE in this process; a
-		// just-applied patch needs a full pi restart (not /reload) to go live.
-		const live = hasInvokeTool(pi);
-		const action = live
-			? ({ kind: "proceed" } as const)
-			: decidePatchAction(live, patchStatus().present, !!loadConfig().invokeToolPatchDeclined, !!ctx.hasUI);
-
-		try {
-			switch (action.kind) {
-				case "proceed": {
-					if (loadConfig().invokeToolPatchDeclined) {
-						saveConfig({ invokeToolPatchDeclined: false });
-					}
-					break;
-				}
-				case "notify-restart": {
-					ctx.ui.notify(
-						"The pi.invokeTool patch is present on disk but not loaded in this pi session. Fully RESTART pi (quit + relaunch) to start the MCP tool bridge.",
-						"warning",
-					);
-					break;
-				}
-				case "silent": {
-					// Previously declined. Stay quiet; bridge stays off until the user
-					// runs /agy patch apply or the patch becomes live.
-					mcpLog("patch-declined");
-					break;
-				}
-				case "ask": {
-					const apply = await ctx.ui.confirm(
-						"Apply the pi.invokeTool patch?",
-						"Enables the MCP tool bridge. Edits one method into your installed @earendil-works/pi-coding-agent/dist/ (reversible via /agy patch restore), and takes effect after a full pi restart.",
-						// Bound the wait so a non-confirm-capable RPC client (hasUI is always
-						// true in RPC) can't hang session_start. Timeout resolves like "no"
-						// (declined persists); reversible via /agy patch apply.
-						{ timeout: 60_000 },
-					);
-					if (apply) {
-						const res = applyInvokeToolPatch({ log: mcpLog });
-						if (res.patched) {
-							saveConfig({ invokeToolPatchDeclined: false });
-							ctx.ui.notify(
-								`Applied the pi.invokeTool patch to ${res.root} (pi ${res.version}). Fully RESTART pi (quit + relaunch) to start the MCP tool bridge.`,
-								"warning",
-							);
-						} else if (res.errors.length > 0) {
-							ctx.ui.notify(`pi.invokeTool patch failed: ${res.errors[0]}`, "error");
-						}
-					} else {
-						saveConfig({ invokeToolPatchDeclined: true });
-						ctx.ui.notify(
-							"Skipped. The MCP tool bridge stays off. To enable it later, run /agy patch apply. Then restart pi.",
-							"info",
-						);
+		// Start the bridge unless the user turned it off. No patch gate, no
+		// consent flow: calls route through pi's normal toolUse loop.
+		const bridgeMode: BridgeTools = loadConfig().bridgeTools;
+		if (bridgeMode === "none") return; // user opted out
+		if (mcpHandle) return; // already running (reload re-fires session_start)
+		const SKIP = new Set(["AskAntigravity"]);
+		const skills: SkillLite[] = scanSkills(process.cwd());
+		const getAll = (pi as unknown as {
+			getAllTools: () => Array<{ name: string; description?: string; parameters?: object; sourceInfo?: { source?: string } }>;
+		}).getAllTools.bind(pi);
+		const listTools = () => {
+			const all = getAll();
+			const filtered =
+				bridgeMode === "mcp"
+					? all.filter((t) => /pi-mcp-adapter/.test(t.sourceInfo?.source ?? ""))
+					: all.filter((t) => t.sourceInfo?.source !== "builtin");
+			const tools = filtered
+				.filter((t) => !SKIP.has(t.name))
+				.map((t) => {
+					let inputSchema: object = { type: "object", properties: {}, additionalProperties: true };
+					try {
+						if (t.parameters) inputSchema = JSON.parse(JSON.stringify(t.parameters)) as object;
+					} catch {
+						/* keep default schema */
 					}
-					break;
-				}
-				case "headless-skip": {
-					console.error(
-						"[antigravity-bridge] pi.invokeTool patch missing; MCP tool bridge off. Apply interactively (/agy patch apply) or re-run pi in a TUI.",
-					);
-					break;
-				}
+					return { name: t.name, description: t.description ?? t.name, inputSchema };
+				});
+			if (skills.length > 0) {
+				tools.push({
+					name: ACTIVATE_SKILL_TOOL_NAME,
+					description: `Activate a pi Agent Skill by name. Catalog:\n${catalogSummary(skills)}`,
+					inputSchema: activateSkillSchema(skills) as object,
+				});
 			}
-		} catch (e) {
-			mcpLog("self-patch-error", e instanceof Error ? e.message : String(e));
-		}
-
-		if (action.kind !== "proceed") return; // bridge can't start without a live patch
-		if (mcpHandle) return; // already running (reload re-fires session_start)
-		const r = await startMcpServer(pi, { log: mcpLog });
+			return tools;
+		};
+		// activate_skill never round-trips through pi: the bridge answers it
+		// directly by reading the SKILL.md (pi has no skill tool to execute).
+		const bridgeOnToolCall = (
+			callId: string,
+			name: string,
+			args: Record<string, unknown>,
+			signal: AbortSignal,
+		) => {
+			if (name !== ACTIVATE_SKILL_TOOL_NAME) return roundTrips.onToolCall(callId, name, args, signal);
+			const wanted = typeof args.name === "string" ? args.name : "";
+			const skill = findSkillByName(skills, wanted);
+			const body = skill ? readSkillBody(skill) : `unknown skill: ${wanted || "(none given)"}`;
+			return Promise.resolve({
+				content: [
+					{
+						type: "text",
+						text: skill ? `${body}\n\n[skill resources dir: ${skill.dir}]` : `Error: ${body}`,
+					},
+				],
+				isError: !skill,
+			});
+		};
+		const r = await startMcpServer({ listTools, onToolCall: bridgeOnToolCall }, { log: mcpLog });
 		if (r.ok && r.handle) {
 			mcpHandle = r.handle;
 		} else {
@@ -214,6 +266,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
+		roundTrips.failAll("antigravity session shut down");
+		await driver.close("shutdown");
 	});
 }
 
@@ -223,6 +277,8 @@ interface AgyCommandCtx {
 	entries: AgyModelEntry[];
 	store: SessionStore;
 	usingFallback: boolean;
+	driver: AgyDriver;
+	getMcpPort: () => number | null;
 }
 
 interface PendingConfig {
@@ -245,24 +301,19 @@ function statusText(ctx: AgyCommandCtx): string {
 		`  tool thinking: ${config.defaultThinking}`,
 		`  sessions:      ${ctx.store.size} bound`,
 		`  config:        ${CONFIG_PATH}`,
-		`  invokeTool:    ${patchStateLabel()}`,
+		`  engine:        ${config.engine}`,
+		`  bridge tools:  ${config.bridgeTools}`,
+		`  digest:        ${config.digest ? "on" : "off"}`,
 		"",
-		"Subcommands: /agy mode plan|accept-edits, /agy permissions on|off, /agy model flash|pro|gemini, /agy thinking low|medium|high, /agy patch status|apply|restore, /agy clear",
+		"Subcommands: /agy mode plan|accept-edits, /agy permissions on|off, /agy model flash|pro|gemini, /agy thinking low|medium|high, /agy clear",
 	].join("\n");
 }
 
-function patchStateLabel(): string {
-	const s = patchStatus();
-	if (s.present) return "patched";
-	if (!s.root) return "MISSING (pi root not found)";
-	if (loadConfig().invokeToolPatchDeclined) return `declined (pi ${s.version}). Resume: /agy patch apply`;
-	return `MISSING (pi ${s.version}). Apply it: /agy patch apply`;
-}
 
 function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	pi.registerCommand("agy", {
 		description:
-			"Antigravity provider: status, mode picker, patch, clear sessions. Usage: /agy [status|mode [plan|accept-edits]|patch [status|apply|restore]|clear]",
+			"Antigravity provider: status, doctor, mode picker, clear sessions. Usage: /agy [status|doctor|mode [plan|accept-edits]|digest on|off|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
 			const mode = cmdCtx.mode;
@@ -275,6 +326,47 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				ui?.notify("Cleared all antigravity session bindings.", "info");
 				return;
 			}
+			if (sub === "patch-cleanup") {
+				const st = patchStatus();
+				if (!st.present) {
+					ui?.notify(
+						st.root
+							? `No invokeTool patch detected on pi ${st.version}. Nothing to clean.`
+							: "Could not locate the installed pi package. Nothing cleaned.",
+						"info",
+					);
+					return;
+				}
+				const r = restorePatch();
+				ui?.notify(
+					r.ok
+						? `Restored ${r.restoredFiles.length} file(s) from ${r.backupDir}. The running session is unaffected; the files on disk are clean again.`
+						: `patch-cleanup failed: ${r.reason}`,
+					r.ok ? "info" : "error",
+				);
+				return;
+			}
+			if (sub === "doctor") {
+				const config = loadConfig();
+				const snap = ctx.driver.snapshot();
+				const port = ctx.getMcpPort();
+				const lines = [
+					"Antigravity doctor (no tokens spent)",
+					`  engine:        ${config.engine}`,
+					`  bridge:        ${config.bridgeTools}${port ? ` (port ${port})` : " (not running)"}`,
+					`  driver:        ${snap.state}${snap.pid ? ` pid=${snap.pid}` : ""}${snap.conversationId ? ` conv=${snap.conversationId.slice(0, 8)}` : ""}`,
+					`  driver stats:  spawns=${snap.stats.spawns} turns=${snap.stats.turns} reused=${snap.stats.reused} recycles=${snap.stats.recycles}${snap.stats.lastRecycleReason ? ` (last: ${snap.stats.lastRecycleReason})` : ""}`,
+					`  sessions:      ${ctx.store.size} bound`,
+					`  models:        ${ctx.entries.length} ${ctx.usingFallback ? "FALLBACK (agy models failed)" : "discovered"}`,
+					`  config:        ${CONFIG_PATH}`,
+				];
+				if (snap.lifecycle.length > 0) {
+					lines.push("  lifecycle (last 5):");
+					for (const entry of snap.lifecycle.slice(-5)) lines.push(`    ${entry}`);
+				}
+				ui?.notify(lines.join("\n"), "info");
+				return;
+			}
 			if (sub === "mode") {
 				if (val === "plan" || val === "accept-edits") {
 					const next = saveConfig({ mode: val as AgyMode });
@@ -303,6 +395,21 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				}
 				return;
 			}
+			if (sub === "digest") {
+				if (val === "on" || val === "off") {
+					const next = saveConfig({ digest: val === "on" });
+					ui?.notify(
+						next.digest
+							? "digest on. pi-side context (compaction summaries, other-provider turns) is injected into each agy prompt. Note: this defeats agy's prompt cache (~25-30k tokens re-billed per turn)."
+							: "digest off. agy prompts contain only your message; agy's prompt cache stays stable. Enable when mixing providers in one session and agy must see pi-side context.",
+						"info",
+					);
+				} else {
+					ui?.notify(`digest: ${loadConfig().digest ? "on" : "off"}\nusage: /agy digest on|off`, "info");
+				}
+				return;
+			}
+
 			if (sub === "thinking") {
 				if (val === "low" || val === "medium" || val === "high") {
 					const next = saveConfig({ defaultThinking: val as ThinkingTier });
@@ -313,53 +420,6 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				return;
 			}
 
-			if (sub === "patch") {
-				if (val === "restore") {
-					const r = restorePatch();
-					ui?.notify(
-						r.ok
-							? `Restored ${r.restoredFiles.length} file(s) from ${r.backupDir}. Restart pi to take effect.`
-							: `restore failed: ${r.reason}`,
-						r.ok ? "info" : "error",
-					);
-					return;
-				}
-				if (val === "apply") {
-					const r = applyInvokeToolPatch();
-					if (r.patched || r.alreadyPresent) {
-						saveConfig({ invokeToolPatchDeclined: false });
-					}
-					const msg = r.patched
-						? `Applied patch to ${r.changedFiles.length} file(s) in ${r.root} (pi ${r.version}). Restart pi to activate.`
-						: r.alreadyPresent
-							? `Patch already present in ${r.root} (pi ${r.version}).`
-							: `apply failed: ${r.errors[0] ?? "unknown error"}`;
-					ui?.notify(msg, r.patched || r.alreadyPresent ? "info" : "error");
-					return;
-				}
-				// status (default)
-				const s = patchStatus();
-				if (!s.root) {
-					ui?.notify("patch status: could not locate the pi package root.", "warning");
-				} else {
-					ui?.notify(
-						[
-							`pi.invokeTool patch: ${s.present ? "PRESENT" : "MISSING"}`,
-							`  root:    ${s.root}`,
-							`  version: ${s.version}`,
-							s.missing.length ? `  missing: ${s.missing.length} site(s)` : null,
-							loadConfig().invokeToolPatchDeclined ? "  consent: declined. Resume: /agy patch apply" : null,
-						s.backupDir ? `  backup:  ${s.backupDir} (v${s.backupVersion})` : "  backup:  none",
-							"",
-							"Usage: /agy patch [status|apply|restore]",
-						]
-							.filter(Boolean)
-							.join("\n"),
-						"info",
-					);
-				}
-				return;
-			}
 
 			// No subcommand (or "status"): print status, or open the picker in TUI.
 			if (sub && sub !== "status") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "Streaming Gemini provider for pi, built on the agy CLI. Registers antigravity/* models in pi's /model picker via SQLite polling + protobuf decode of agy's conversation DBs.",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -24,6 +24,8 @@ const CONFIG_PATH = path.join(
 
 export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
+export type AgyEngine = "stream-json" | "legacy-sqlite";
+export type BridgeTools = "none" | "mcp" | "all";
 
 export interface AgyConfig {
 	mode: AgyMode;
@@ -37,10 +39,33 @@ export interface AgyConfig {
 	defaultModel: string;
 	/** AskAntigravity tool: default thinking tier when the alias names none. */
 	defaultThinking: ThinkingTier;
-	/** User declined the pi.invokeTool auto-patch consent prompt. When true,
-	 *  session_start silently skips the patch + MCP tool bridge until cleared
-	 *  (by /agy patch apply succeeding, or the patch otherwise becoming live). */
-	invokeToolPatchDeclined?: boolean;
+	/** Turn engine. "stream-json" (default): one persistent agy process fed
+	 *  NDJSON user events; enables live toolUse round-trips, native usage, and
+	 *  conversation binding from the init event. "legacy-sqlite": the old
+	 *  spawn-`agy -p`-and-poll-SQLite path, kept as a fallback for one release. */
+	engine: AgyEngine;
+	/** Set after the one-time notice about a leftover legacy invokeTool patch
+	 *  on the installed pi. The notice never repeats; /agy patch-cleanup is
+	 *  always available. */
+	patchCleanupNotified?: boolean;
+	/** Which pi tools the MCP bridge exposes to agy: "none" (bridge off),
+	 *  "mcp" (pi-mcp-adapter tools + skills bridge; default), "all" (every
+	 *  registered non-builtin tool incl. other Ask* delegations). */
+	bridgeTools: BridgeTools;
+	/** Inject a delta digest of pi-side context (compaction summaries, turns
+	 *  handled by other providers or pi's own tools) into each agy prompt.
+	 *
+	 *  Default OFF. The digest changes every turn, which defeats agy's
+	 *  server-side prompt cache: every turn re-bills the full context
+	 *  (~25-30k tokens observed). With it off, prompts stay stable and the
+	 *  cache hits.
+	 *
+	 *  Enable when you mix providers in one pi session (Claude turns, pi-side
+	 *  tool runs, or a compaction that agy should know about) and you value
+	 *  agy seeing that context over the cache re-billing. Pure antigravity
+	 *  sessions gain nothing: agy already keeps its own history, and bridge
+	 *  round-trips deliver tool results through the bridge, not the digest. */
+	digest: boolean;
 }
 
 const DEFAULTS: AgyConfig = {
@@ -48,6 +73,9 @@ const DEFAULTS: AgyConfig = {
 	skipPermissions: true,
 	defaultModel: "flash",
 	defaultThinking: "medium",
+	engine: "stream-json",
+	bridgeTools: "mcp",
+	digest: false,
 };
 
 /** Load config merged over defaults. Env vars override the file when set. */
@@ -92,7 +120,29 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	const defaultThinking: ThinkingTier =
 		thinkRaw === "low" || thinkRaw === "high" ? thinkRaw : "medium";
 
-	return { mode, skipPermissions, defaultModel, defaultThinking, invokeToolPatchDeclined: file.invokeToolPatchDeclined };
+	const engine: AgyEngine =
+		process.env.AGY_ENGINE === "legacy-sqlite" || file.engine === "legacy-sqlite"
+			? "legacy-sqlite"
+			: "stream-json";
+
+	const bridgeRaw = (process.env.AGY_BRIDGE_TOOLS ?? file.bridgeTools ?? DEFAULTS.bridgeTools).toLowerCase();
+	const bridgeTools: BridgeTools =
+		bridgeRaw === "none" || bridgeRaw === "all" ? bridgeRaw : "mcp";
+
+	const digest = process.env.AGY_DIGEST !== undefined
+		? ["1", "true", "on"].includes(process.env.AGY_DIGEST.toLowerCase())
+		: file.digest ?? false;
+
+	return {
+		mode,
+		skipPermissions,
+		defaultModel,
+		defaultThinking,
+		engine,
+		bridgeTools,
+		digest,
+		patchCleanupNotified: file.patchCleanupNotified === true,
+	};
 }
 
 /** Atomically persist a config patch (temp + rename). */