@estebanforge/pi-antigravity-bridge 1.4.8 → 1.4.9

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.9] - 2026-09-05
+
+### Added
+
+- Warn toasts in the pi UI: bridge tool failures, stalls, timeouts, process exits, and other warnings surface as native warning notifications the moment they happen, so users see them and can report them. Over SSH or without a UI the same text falls back to stderr. Deliberate aborts, connection exits (the turn's own error block carries real crashes), and `call-tool-fail` (same-instant duplicate of `round-trip-fail`) stay silent.
+- Gate B watch in `/agy doctor`: the ACP connection latches the first `session/update` payload that carries usage/token fields, and doctor prints one "acp tokens: AVAILABLE" line when that happens. Silent until then; the day the line appears, wiring real token counts becomes a small mapping job. Auth-style string `"token"` keys inside tool frames cannot trip the latch.
+
+### Fixed
+
+- Esc-abort on the ACP engine no longer dumps the dying server's raw stderr tail (a google3 stack trace) into the transcript. Teardown exits (abort kill, shutdown, idle recycle) are marked expected and never render; a genuine mid-turn crash surfaces as the turn's own clean error block instead. Raw tails still land in the file log for post-mortems.
+
+### Changed
+
+- The ACP engine is now beta. Parity is verified live against RC01 (text streaming, multi-turn resume, bridge tools, effort switching, serialization, abort recovery - see `scripts/parity-live.mjs`), so it graduates from opt-in-experimental to a supported alternative engine. It stays behind `config.engine` for now; the two known RC01 gaps (no usage fields, kill+reload abort) are documented in the README.
+- Daily log volume: the default tier now writes ONLY errors, so a regular session costs the disk nothing. Warns live in the UI (see above); `AGY_DEBUG=1` restores the full debug/info/warn/error trail for reproducing a problem. Docs: README debug-logs section, `/agy doctor` hint.
+- The tool-priority note now steers agy's native `view_file` (artifact-sandboxed on RC01) to the Pi Bridge file tools (`read`, `ls`, `grep`, `find`, `edit`, `execute`) for any real filesystem path. Observed live: repeated `invalid_args` rejections on `operator/pkg/tmux/client.go` before the model fell back to `edit`.
+
 ## [1.4.8] - 2026-09-05
 
 ### Added

package/README.md

@@ -21,11 +21,11 @@ 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**: Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Opt-in while it matures: the current build (RC01) ships no usage fields (token display shows zero) and no cancel (abort tears the server down and reloads it next turn). Everything else is parity-verified live - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery - see `scripts/parity-live.mjs`.
+- **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).
 
 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.
 
-| Capability | `stream-json` (default) | `acp` |
+| 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) |
@@ -157,7 +157,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 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)
 /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)
@@ -188,7 +188,7 @@ For isolation when running any agent that executes commands without a confirmati
 | `AGY_SKIP_PERMISSIONS` | `1`/`true` (default) to pass `--dangerously-skip-permissions` so commands don't hang on an unanswerable prompt in `-p` mode. `0`/`false` to prompt (hangs any `run_command` non-interactively). Wins over the config file. |
 | `AGY_DEFAULT_MODEL` | Default model alias for the `AskAntigravity` tool (`flash`/`pro`/`gemini`, or a tier/version qualifier). Wins over the config file. |
 | `AGY_DEFAULT_THINKING` | Default thinking tier for the `AskAntigravity` tool: `low`/`medium`/`high`. Anything else falls back to `medium`. Wins over the config file. |
-| `AGY_DEBUG` | `1`/`true`/`on` writes verbose debug records to the daily log (driver lifecycle, raw bridge traffic). Default off: only the light info/warn/error stream. |
+| `AGY_DEBUG` | `1`/`true`/`on` writes the full trail to the daily log (driver lifecycle, raw bridge traffic). Default off: **only `error` records land on disk** - routine disk writes are zero for regular users, and warnings surface as UI toasts instead. |
 
 ## Debug logs
 
@@ -198,14 +198,14 @@ The extension keeps a daily log on your machine, sorted by day:
 ~/.pi/extensions-data/estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson
 ```
 
-One JSON record per line. Two verbosity tiers keep the disk cost negligible for regular users: by default only `info`/`warn`/`error` records land on disk, which is the useful skeleton: turn starts and outcomes with error text (both engines), bridge tool calls, escalations and poll traffic, late deliveries, and round-trip failures, `AskAntigravity` runs, `/agy` commands, ACP setup/self-heal, auth URLs, and every driver failure (stall, abort, timeout, nonzero exit). Set `AGY_DEBUG=1` before reproducing a problem for the full trail: per-event driver lifecycle (spawn, exit, session load/new, unparks), list-tools traffic, recycle causes, and the raw bridge chatter. `/agy doctor` prints the log directory.
+One JSON record per line. Two verbosity tiers keep the disk cost at zero for regular users: by default only `error` records land on disk - everything routine (turn starts, tool calls, escalations, commands, driver failures) is withheld. Warnings are not lost: the extension toasts each one in the pi UI (bridge tool failures, stalls, timeouts, process exits), so users see them and can report them; deliberate aborts and failures pi already renders as the turn's own error block stay silent. Set `AGY_DEBUG=1` before reproducing a problem for the full trail: per-event driver lifecycle (spawn, exit, session load/new, unparks), turn starts and outcomes, bridge tool calls, escalations and poll traffic, late deliveries, list-tools traffic, recycle causes, and the raw bridge chatter. `/agy doctor` prints the log directory.
 
 Notes:
 
 - Retention: 14 days. Older files are pruned automatically.
 - Privacy: prompt text, tool arguments, and tool output never land in the log. Secret-shaped values (tokens, API keys, credentials, header blocks) are redacted, and long strings are truncated. The `auth-url` record strips the login URL's query string.
 - Logging never throws: an unwritable directory is skipped silently and retried on the next record.
-- SSD wear: default volume is a handful of records per turn. Verbose mode (`AGY_DEBUG=1`) writes more; turn it off after reproducing.
+- SSD wear: default volume is effectively zero until something actually errors. Verbose mode (`AGY_DEBUG=1`) writes more; turn it off after reproducing.
 
 When you report an issue, attach the last day or two of files from that directory. For anything that needs reproduction, run with `AGY_DEBUG=1` once and attach that day's file. They usually contain the exact failure sequence (engine, session, bridge call, error) with no need to guess.
 

package/extensions/index.ts

@@ -116,6 +116,36 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// src/daily-log.ts). Fire-and-forget, secrets redacted, old days pruned.
 	// Support flow: "attach the last days' files from that dir".
 	const fileLog = createDailyLogger({ dir: logsDir() });
+	// Warn tier = user-facing: the default file log keeps ONLY errors (zero
+	// 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.
+	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;
+		const d = (data ?? {}) as Record<string, unknown>;
+		let text: string;
+		if (event === "round-trip-fail") {
+			text = `Bridge tool call failed: ${String(d.name ?? "tool")} (${String(d.reason ?? "unknown")})`;
+		} else if (event.startsWith("stall:")) {
+			text = "Antigravity stalled with no output; the turn was stopped";
+		} else if (event.startsWith("timeout:")) {
+			text = "Antigravity turn timed out";
+		} else if (event.startsWith("exit:") && event !== "exit:0") {
+			text = "Antigravity process exited unexpectedly";
+		} else if (event === "turn-error") {
+			text = `Antigravity turn issue: ${String(d.reason ?? "unknown")}`;
+		} else {
+			text = `Antigravity warning: ${event}`;
+		}
+		if (activeUi) activeUi.notify(text, "warning");
+		else console.error(`[antigravity-bridge] ${text}`);
+	};
 	fileLog.log(
 		"extension-load",
 		{ engine, models: models.length, fallback: usingFallback, bridge: loadConfig().bridgeTools, askTool: loadConfig().askTool },
@@ -183,12 +213,19 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				: data;
 		// Failures warn; turn-start + auth-url are the always-on skeleton;
 		// routine per-event lifecycle (spawn, session-load, unparked, ...) is
-		// verbose-only.
-		const level = acpFailures.has(msg)
-			? "warn"
-			: msg === "turn-start" || msg === "auth-url"
-				? "info"
-				: "debug";
+		// verbose-only. Deliberate teardown exits (Esc abort kill, shutdown,
+		// idle recycle) demote to debug: routine, and the warn tier stays the
+		// "what broke" grep.
+		const expectedExit =
+			msg === "connection-exited" &&
+			(data as { expected?: boolean } | undefined)?.expected === true;
+		const level = expectedExit
+			? "debug"
+			: acpFailures.has(msg)
+				? "warn"
+				: msg === "turn-start" || msg === "auth-url"
+					? "info"
+					: "debug";
 		fileLog.log(msg, fileData, level);
 		if (msg === "auth-url") {
 			const { url, port } = (data ?? {}) as { url?: string; port?: number | null };
@@ -209,7 +246,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			return;
 		}
 		if (!acpFailures.has(msg)) return;
-		console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`);
+		// Console noise is gone: warns toast through the fileLog wrapper (with
+		// a stderr fallback when no UI exists), and raw tails stay in the file
+		// log behind AGY_DEBUG.
 	};
 	const acpDriver = new AcpDriver({
 		// Resolved per connection: the setup flow can install the binary and
@@ -793,7 +832,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					`  sessions:      ${ctx.store.size} bound`,
 					`  models:        ${ctx.entries.length} ${ctx.usingFallback ? "FALLBACK (agy models failed)" : "discovered"}`,
 					`  config:        ${CONFIG_PATH}`,
-					`  logs:          ${logsDir()} (attach recent days' files when reporting issues)`,
+					`  logs:          ${logsDir()} (attach recent days' files when reporting issues; set AGY_DEBUG=1 to capture details)`,
 				];
 				if (snap.engine === "acp" && snap.acp) {
 					lines.push(
@@ -801,6 +840,11 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						`  acp server:    ${snap.acp.serverVersion ?? "unknown"}${snap.acp.agentTitle ? ` (${snap.acp.agentTitle})` : ""}`,
 						`  acp stats:     prompts=${snap.acp.prompts} created=${snap.acp.sessionsCreated} loaded=${snap.acp.sessionsLoaded} kills=${snap.acp.kills} reconnects=${snap.acp.reconnects} cancel=${snap.acp.cancelSupported === null ? "unprobed" : snap.acp.cancelSupported ? "supported" : "unsupported (kill+reload)"}`,
 					);
+					// Gate B watch: silent while the server offers no token counts; one
+					// 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)");
+					}
 				}
 				if (snap.lifecycle.length > 0) {
 					lines.push("  lifecycle (last 5):");

package/package.json

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

@@ -24,6 +24,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parseAuthPort, readLastUrl } from "./browser-capture.js";
+import { frameCarriesUsage } from "./events.js";
 import { JsonRpcResponseError, JsonRpcSession } from "./jsonrpc.js";
 
 export interface AcpMcpServer {
@@ -80,6 +81,7 @@ export class AcpConnection {
 	#child: ChildProcess | undefined;
 	#rpc: JsonRpcSession | undefined;
 	#stderrTail = "";
+	#usageSeen = false;
 	#exited = false;
 	#killed = false;
 	#suppressUpdates = false;
@@ -106,6 +108,13 @@ export class AcpConnection {
 		return this.#stderrTail;
 	}
 
+	/** Gate B watch: latched true once any session/update frame carried
+	 *  usage/token fields. /agy doctor surfaces it the day upstream starts
+	 *  sending token counts; silent until then. */
+	get usageSeen(): boolean {
+		return this.#usageSeen;
+	}
+
 	/** While true, session/update notifications are dropped: they are the
 	 *  full-text history replay that precedes a session/load response, never
 	 *  live generation (run 6). */
@@ -299,6 +308,9 @@ export class AcpConnection {
 
 	#onNotification(method: string, params: unknown): void {
 		if (method === "session/update") {
+			// Latched before the suppression gate: history-replay frames are the
+			// server's payloads too, and they are the cheapest signal source.
+			if (!this.#usageSeen && frameCarriesUsage(params)) this.#usageSeen = true;
 			if (this.#suppressUpdates) return; // load replay: history, not live text
 			const p = typeof params === "object" && params !== null ? (params as Record<string, unknown>) : {};
 			const sessionId = typeof p.sessionId === "string" ? p.sessionId : this.#updateSessionId;

package/src/acp/driver.ts

@@ -409,7 +409,12 @@ export class AcpDriver implements TurnDriver {
 		const turn = this.#active;
 		this.#conn = undefined;
 		this.#state = "dead";
-		this.#log("connection-exited", { tail: info.stderrTail.slice(-200) });
+		// Teardown exits (abort kill, shutdown, idle recycle) are deliberate:
+		// their stderr tail must never reach the UI. Only a live turn dying
+		// mid-flight is user-reportable, and it surfaces as a normal turn
+		// error, not as raw console noise.
+		const turnActive = Boolean(turn && !turn.closed && !turn.aborted && !turn.sawResult);
+		this.#log("connection-exited", { expected: !turnActive, tail: info.stderrTail.slice(-200) });
 		if (!turn || turn.closed) return;
 		if (turn.aborted || turn.sawResult) {
 			this.#settle(turn, {
@@ -421,7 +426,7 @@ export class AcpDriver implements TurnDriver {
 			});
 			return;
 		}
-		this.#failTurn(turn, info.stderrTail.trim() || "ACP server exited mid-turn");
+		this.#failTurn(turn, "Antigravity session exited unexpectedly; it restarts on the next turn");
 	}
 
 	#ensureConnection(request: DriverTurnRequest): Promise<AcpConnection> {
@@ -721,6 +726,7 @@ export class AcpDriver implements TurnDriver {
 				reconnects: Math.max(0, this.#stats.spawns - 1),
 				agentName: this.#agentInfo?.name,
 				agentTitle: this.#agentInfo?.title,
+				usageSeen: this.#conn?.usageSeen ?? false,
 			},
 		};
 	}

package/src/acp/events.ts

@@ -248,3 +248,20 @@ export class TextAccumulator {
 		return this.#acc;
 	}
 }
+
+const USAGE_KEY = /usage|tokens?/i;
+
+/** Gate B watch: true when a server payload carries usage/token fields.
+ *  Key-name based so future shapes (usage blocks, _meta.tokenCount, top-level
+ *  token totals) all trip it. String values are exempt so auth-style "token"
+ *  args inside tool-call frames cannot false-positive the latch; depth-capped
+ *  so the walk stays cheap on every frame until it latches. */
+export function frameCarriesUsage(value: unknown, depth = 0): boolean {
+	if (depth > 8 || typeof value !== "object" || value === null) return false;
+	if (Array.isArray(value)) return value.some((v) => frameCarriesUsage(v, depth + 1));
+	for (const [key, v] of Object.entries(value)) {
+		if (USAGE_KEY.test(key) && (typeof v === "number" || typeof v === "object")) return true;
+		if (frameCarriesUsage(v, depth + 1)) return true;
+	}
+	return false;
+}

package/src/daily-log.ts

@@ -15,10 +15,10 @@
 //     redacted and long strings are truncated before they reach disk.
 //   - Retention: files older than `retentionDays` are pruned once per
 //     process, so the dir cannot grow unbounded.
-//   - Two tiers, to keep SSD wear negligible for regular users: only
-//     info/warn/error records (failures, turn/tool boundaries, commands,
-//     setup) are written by default. Full verbose trails (per-event driver
-//     lifecycle, raw bridge traffic) require AGY_DEBUG=1.
+//   - Volume tiers: default installs write ONLY errors — routine logging
+//     costs the disk nothing. Warns surface as UI toasts instead (the
+//     extension wraps this logger); AGY_DEBUG=1 restores the full trail
+//     (debug/info/warn/error).
 
 import { appendFile, mkdir, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
@@ -30,9 +30,9 @@ export interface DailyLoggerOptions {
 	dir: string;
 	/** Files older than this many days are pruned once per process. Default 14. */
 	retentionDays?: number;
-	/** Verbose gate. When false (default), debug-level records are dropped:
-	 *  only info/warn/error land on disk, the light stream regular users
-	 *  keep. AGY_DEBUG=1 (or this option) restores the full trail. */
+	/** Verbose gate. When false (default), only error-level records land on
+	 *  disk; debug/info/warn are dropped so regular users write nothing
+	 *  routine. AGY_DEBUG=1 (or this option) restores the full trail. */
 	debug?: boolean;
 	/** Injectable clock for tests. */
 	now?: () => Date;
@@ -166,9 +166,10 @@ export function createDailyLogger(opts: DailyLoggerOptions): DailyLogger {
 
 	return {
 		log(event, data, level = "debug") {
-			// Volume gate: debug is the verbose tier. Default installs write
-			// only info/warn/error so the disk cost stays negligible.
-			if (level === "debug" && !verbose) return;
+			// Volume gate: default installs write only errors so routine disk
+			// traffic is zero for regular users; the extension toasts warns
+			// instead. AGY_DEBUG=1 restores the full trail.
+			if (!verbose && level !== "error") return;
 			write(level, event, data);
 		},
 		flush() {

package/src/driver-types.ts

@@ -125,6 +125,10 @@ export interface DriverSnapshot {
 		/** From the initialize handshake agentInfo block. */
 		agentName?: string;
 		agentTitle?: string;
+		/** Gate B watch: true once this server process sent usage/token fields
+		 *  in any session/update frame. /agy doctor surfaces it when true and
+		 *  stays silent otherwise. */
+		usageSeen: boolean;
 	};
 }
 

package/src/provider.ts

@@ -114,12 +114,14 @@ export const SYSTEM_PROMPT_END = "[END SYSTEM PROMPT]";
 
 /** Brief tool-priority note appended inside every system prompt block: agy
  *  runs embedded in pi, so its native interactive tools never reach the
- *  user. Equivalent Pi Bridge tools must win. Concrete clash observed live:
- *  agy picked its native ask_question over the bridge's ask_user_question
- *  and the question never displayed. Rides the systemPrompt gate: the note
- *  ships only when the system prompt ships. */
+ *  user. Equivalent Pi Bridge tools must win. Concrete clashes observed
+ *  live: agy picked its native ask_question over the bridge's
+ *  ask_user_question and the question never displayed; on ACP its native
+ *  view_file rejects real filesystem paths (artifact sandbox), so reads of
+ *  the user's machine must go through the bridge. Rides the systemPrompt
+ *  gate: the note ships only when the system prompt ships. */
 export const TOOL_PRIORITY_NOTE =
-	"[Tool priority: this conversation runs inside pi, not as a standalone agy session; the user only sees what surfaces in pi. Native interactive tools, for example ask_question, never reach the user. When a Pi Bridge tool covers the same purpose, always use the Pi Bridge tool; for user questions use ask_user_question. Long-running bridge calls do not fail: after ~20 seconds the bridge answers STILL RUNNING with a callId; fetch the result with bridge_poll_result and poll until it lands. For work you already know is long, prefer exec_command's session-output pattern or background agents so you keep working while it runs.]";
+	"[Tool priority: this conversation runs inside pi, not as a standalone agy session; the user only sees what surfaces in pi. Native interactive tools, for example ask_question, never reach the user. When a Pi Bridge tool covers the same purpose, always use the Pi Bridge tool; for user questions use ask_user_question. Your native file tools such as view_file only read brain artifacts and reject real filesystem paths; for any path on the user's machine use the Pi Bridge tools (read, ls, grep, find, edit, execute). Long-running bridge calls do not fail: after ~20 seconds the bridge answers STILL RUNNING with a callId; fetch the result with bridge_poll_result and poll until it lands. For work you already know is long, prefer exec_command's session-output pattern or background agents so you keep working while it runs.]";
 
 /** Assemble the full agy prompt: system prompt block, pi-side digest, user
  *  prompt. Empty parts are dropped. Pure; exported for unit testing.