@estebanforge/pi-antigravity-bridge 1.7.3 → 1.7.5

package/src/agy-version.ts

@@ -0,0 +1,137 @@
+// agy CLI version gate.
+//
+// An agy older than MIN_AGY_VERSION fails stream-json turns with raw stream
+// errors that look like bridge bugs, so we detect it once per process and
+// say so plainly (session-start warning + /agy doctor) instead of letting
+// users debug parse noise. Pure functions here; the only subprocess is
+// `agy --version`, memoized per binary because discovery already spawns agy
+// once per load and the version will not change mid-process.
+//
+// The ACP server reports its own version at initialize (agentInfo.version,
+// e.g. "agy_acp_server_1.1.1") and /agy doctor already prints it. ACP build
+// numbering is a different lineage from the CLI, so no floor is enforced
+// there: the one known-good build must not be locked out by a CLI number.
+
+import { spawn } from "node:child_process";
+
+/** Floor for the stream-json CLI. Matches the protocol grammar our driver
+ *  and the event mapping rely on; older agy predates verified fields. */
+export const MIN_AGY_VERSION = "1.1.22";
+
+const VERSION_TIMEOUT_MS = 5_000;
+
+export type AgyVersionStatus =
+	| "ok"
+	| "unsupported"
+	| "development"
+	| "invalid"
+	| "unavailable";
+
+export interface AgyVersionCheck {
+	status: AgyVersionStatus;
+	/** Extracted triple when status is ok/unsupported; raw dev token for development. */
+	version?: string;
+	/** Full --version output, for doctor detail. */
+	raw: string;
+}
+
+/** Pull the first strict triple (`1.2.10`) out of arbitrary version output.
+ *  Prefixed forms like "agy_acp_server_1.1.1" and banner text both match;
+ *  anything without a triple is not a version we can gate on. */
+export function parseAgyVersionTriple(text: string): string | undefined {
+	return /\d+\.\d+\.\d+/.exec(text)?.[0];
+}
+
+/** Numeric triple compare; 1.10.0 > 1.9.9, unlike string compare. */
+export function compareVersionTuples(a: string, b: string): number {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+		if (d !== 0) return d;
+	}
+	return 0;
+}
+
+/** Classify raw `--version` output against a floor. Pure: unit-tested for
+ *  every status; checkAgyCliVersion wraps this with the subprocess. */
+export function agyVersionVerdict(
+	raw: string,
+	floor: string = MIN_AGY_VERSION,
+): AgyVersionCheck {
+	// Development builds (agy from source) self-identify as dev, HEAD, or the
+	// spelled-out word; never gate any of them.
+	if (/\b(dev|head|development)\b/i.test(raw))
+		return { status: "development", version: "dev", raw };
+	const triple = parseAgyVersionTriple(raw);
+	if (!triple) return { status: "invalid", raw };
+	if (compareVersionTuples(triple, floor) < 0) return { status: "unsupported", version: triple, raw };
+	return { status: "ok", version: triple, raw };
+}
+
+const checkCache = new Map<string, Promise<AgyVersionCheck>>();
+
+/** Run `binary --version` and classify the result. Memoized per binary for
+ *  the process lifetime (resetAgyVersionCache clears it for tests). Fail
+ *  paths: spawn error (ENOENT etc.) and watchdog timeout are "unavailable",
+ *  a distinct status so doctor can say "could not run" instead of blaming
+ *  the version string. */
+export function checkAgyCliVersion(binary: string = "agy"): Promise<AgyVersionCheck> {
+	const cached = checkCache.get(binary);
+	if (cached) return cached;
+	const run = new Promise<AgyVersionCheck>((resolve) => {
+		let out = "";
+		let done = false;
+		const finish = (check: AgyVersionCheck) => {
+			if (done) return;
+			done = true;
+			clearTimeout(watchdog);
+			resolve(check);
+		};
+		let proc: ReturnType<typeof spawn>;
+		try {
+			proc = spawn(binary, ["--version"], { stdio: ["ignore", "pipe", "ignore"], shell: false });
+		} catch {
+			finish({ status: "unavailable", raw: "" });
+			return;
+		}
+		proc.stdout?.setEncoding("utf8");
+		proc.stdout?.on("data", (d: string) => (out = (out + d).slice(0, 4096)));
+		proc.on("error", () => finish({ status: "unavailable", raw: "" }));
+		// Exit code is ignored on purpose: `agy --version` failures print to
+		// stderr (ignored) and leave junk or empty stdout, which classifies as
+		// invalid — close enough in effect to unavailable for a warn-only gate.
+		proc.on("close", () => finish(agyVersionVerdict(out)));
+		const watchdog = setTimeout(() => {
+			try {
+				proc.kill("SIGKILL");
+			} catch {
+				/* already gone */
+			}
+			finish({ status: "unavailable", raw: out });
+		}, VERSION_TIMEOUT_MS);
+	});
+	checkCache.set(binary, run);
+	return run;
+}
+
+/** Test seam: drop all memoized checks. */
+export function resetAgyVersionCache(): void {
+	checkCache.clear();
+}
+
+/** One-line doctor rendering. */
+export function describeAgyVersionCheck(check: AgyVersionCheck): string {
+	switch (check.status) {
+		case "ok":
+			return check.version ?? "ok";
+		case "unsupported":
+			return `${check.version} TOO OLD`;
+		case "development":
+			return "development build";
+		case "invalid":
+			return "unreadable version output";
+		case "unavailable":
+			return "could not run --version";
+	}
+}

package/src/artifacts-ui.ts

@@ -0,0 +1,86 @@
+// /agy artifacts overlay: SelectList over one conversation's artifacts.
+//
+// UI mirrors the engine picker (tui.md "Pattern 1"): SelectList framed by
+// DynamicBorder inside pi's native overlay. Read-only on purpose: enter
+// opens the selected file with the OS default handler, r rescans (the list
+// is always a fresh scan), esc closes. No delete keys — agy's files are
+// agy's to manage.
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+import type { AgyArtifact } from "./artifacts.js";
+
+export type ArtifactsBrowserAction =
+	| { type: "open"; artifact: AgyArtifact }
+	| { type: "rescan" }
+	| { type: "close" };
+
+function humanBytes(n: number): string {
+	if (n < 1024) return `${n}B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+	return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function artifactItems(artifacts: AgyArtifact[]): SelectItem[] {
+	return artifacts.map((a, i) => {
+		const when = new Date(a.modifiedMs);
+		const stamp = `${when.getFullYear()}-${String(when.getMonth() + 1).padStart(2, "0")}-${String(when.getDate()).padStart(2, "0")} ${String(when.getHours()).padStart(2, "0")}:${String(when.getMinutes()).padStart(2, "0")}`;
+		return {
+			value: String(i),
+			label: a.name,
+			description: `${a.kind} · ${a.mediaType} · ${humanBytes(a.bytes)} · ${stamp}`,
+		};
+	});
+}
+
+/** Render the overlay. Resolves with what the user asked for: open (with the
+ *  selected artifact), rescan, or close. */
+export async function showArtifactsBrowser(
+	ctx: ExtensionUIContext,
+	artifacts: AgyArtifact[],
+): Promise<ArtifactsBrowserAction> {
+	const items = artifactItems(artifacts);
+	return ctx.custom<ArtifactsBrowserAction>((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+		container.addChild(
+			new Text(theme.fg("accent", theme.bold(`Antigravity artifacts (${artifacts.length})`)), 1, 0),
+		);
+		container.addChild(new Spacer(1));
+
+		const list = new SelectList(items, Math.min(items.length, 12), {
+			selectedPrefix: (t: string) => theme.fg("accent", t),
+			selectedText: (t: string) => theme.fg("accent", t),
+			description: (t: string) => theme.fg("muted", t),
+			scrollInfo: (t: string) => theme.fg("dim", t),
+			noMatch: (t: string) => theme.fg("warning", t),
+		});
+		list.onSelect = (item) => done({ type: "open", artifact: artifacts[Number(item.value)] });
+		list.onCancel = () => done({ type: "close" });
+		container.addChild(list);
+
+		container.addChild(new Spacer(1));
+		container.addChild(
+			new Text(theme.fg("dim", "↑↓ navigate · enter open · r rescan · esc close"), 1, 0),
+		);
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				// r rescan; enter opens (via onSelect), esc cancels (via onCancel).
+				if (data.trim().toLowerCase() === "r") {
+					done({ type: "rescan" });
+					return;
+				}
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	}, {
+		overlay: true,
+		overlayOptions: { anchor: "center" as const, width: 84, maxHeight: "85%" as const, margin: 1 },
+	});
+}

package/src/artifacts.ts

@@ -0,0 +1,144 @@
+// Read-only artifact scan over one agy conversation's brain dir.
+//
+// agy drops files in three places under brain/<conversationId>/: the
+// conversation root itself, .tempmediaStorage/ (media agy generated), and
+// .user_uploaded/ (files the user handed it). Nothing else surfaces them,
+// so this module lists them for pi (live-probed 2026-09-24: both trees
+// exist per engine; media dirs are created on demand and may be absent).
+//
+// Read-only by design: list and open, never delete. Each entry is
+// realpath'd and containment-checked canonical-to-canonical, which defeats
+// symlinks pointing outside the conversation root and stays correct when
+// the conversation dir itself is reached through a symlinked ancestor
+// (macOS /var -> /private/var, symlinked homes). A file could still be
+// swapped for a symlink between listing and a later `open` — the OS opener
+// would follow it; that is outside this module's guarantee and acceptable
+// for a single-user, own-home tool.
+
+import { readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+export type AgyArtifactKind = "conversation" | "generated" | "uploaded";
+export type AgyArtifactMediaType =
+	| "image"
+	| "audio"
+	| "video"
+	| "pdf"
+	| "markdown"
+	| "text"
+	| "other";
+
+export interface AgyArtifact {
+	name: string;
+	absolutePath: string;
+	kind: AgyArtifactKind;
+	mediaType: AgyArtifactMediaType;
+	bytes: number;
+	modifiedMs: number;
+}
+
+const EXT_TO_MEDIA: Record<string, AgyArtifactMediaType> = {
+	png: "image",
+	jpg: "image",
+	jpeg: "image",
+	gif: "image",
+	webp: "image",
+	svg: "image",
+	bmp: "image",
+	mp3: "audio",
+	wav: "audio",
+	ogg: "audio",
+	m4a: "audio",
+	flac: "audio",
+	mp4: "video",
+	mov: "video",
+	webm: "video",
+	mkv: "video",
+	pdf: "pdf",
+	md: "markdown",
+	markdown: "markdown",
+	txt: "text",
+	csv: "text",
+	json: "text",
+};
+
+function mediaTypeFor(name: string): AgyArtifactMediaType {
+	return EXT_TO_MEDIA[path.extname(name).slice(1).toLowerCase()] ?? "other";
+}
+
+/** Files that are agy bookkeeping, not user-facing artifacts. */
+function isSkippedName(name: string): boolean {
+	return name.startsWith(".") || name.endsWith(".metadata.json");
+}
+
+const SCAN_ROOTS: Array<{ sub: string | null; kind: AgyArtifactKind }> = [
+	{ sub: null, kind: "conversation" },
+	{ sub: ".tempmediaStorage", kind: "generated" },
+	{ sub: ".user_uploaded", kind: "uploaded" },
+];
+
+/** List artifacts under one conversation dir. Missing subdirs are normal
+ *  (created on demand) and skip silently; a missing conversation dir
+ *  returns []. Newest first. */
+export async function listAgyArtifacts(conversationDir: string): Promise<AgyArtifact[]> {
+	// Canonicalize ONCE and derive everything from the canonical root: a
+	// raw-vs-canonical containment check silently rejects every entry when
+	// any ancestor is a symlink (the relative prefix comparison crosses
+	// resolved/unresolved segments and yields a bogus "..").
+	let root: string;
+	try {
+		root = await realpath(conversationDir);
+	} catch {
+		return [];
+	}
+	const byPath = new Map<string, AgyArtifact>();
+	for (const { sub, kind } of SCAN_ROOTS) {
+		const dir = sub === null ? root : path.join(root, sub);
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isFile()) continue; // Dirent type: symlinks excluded here
+			if (isSkippedName(entry.name)) continue;
+			// Re-resolve per entry and re-check containment on the canonical
+			// path: catches anything swapped in between readdir and use.
+			let canonical: string;
+			let stats;
+			try {
+				canonical = await realpath(path.join(dir, entry.name));
+				if (!containedIn(root, canonical)) continue;
+				stats = await stat(canonical);
+			} catch {
+				continue;
+			}
+			if (!stats.isFile()) continue;
+			const key = canonical;
+			if (byPath.has(key)) continue;
+			byPath.set(key, {
+				name: entry.name,
+				absolutePath: canonical,
+				kind,
+				mediaType: mediaTypeFor(entry.name),
+				bytes: stats.size,
+				modifiedMs: stats.mtimeMs,
+			});
+		}
+	}
+	return [...byPath.values()].sort((a, b) => b.modifiedMs - a.modifiedMs);
+}
+
+function containedIn(root: string, candidate: string): boolean {
+	const rel = path.relative(root, candidate);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/** OS open command for the user's default handler. Undefined on unknown
+ *  platforms (caller renders a message instead of spawning blind). */
+export function artifactOpenCommand(): { cmd: string } | undefined {
+	if (process.platform === "darwin") return { cmd: "open" };
+	if (process.platform === "linux") return { cmd: "xdg-open" };
+	return undefined;
+}

package/src/ask-tool.ts

@@ -78,7 +78,7 @@ TWO MODES (you choose):
 - **Continued conversation**: pass the conversationId returned in the PREVIOUS call's details (details.conversationId). agy resumes that conversation with full context intact.
 
 EXECUTION MODES (param: mode):
-- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks.
+- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks. Enforced: plan runs never receive the skip-permissions flag, so a write or command attempt ends the run quickly with a "confirm plan" message instead of executing.
 - **accept-edits** (default): agy applies edits directly inside the workspace.
 
 COMPACT OUTPUT (param: digest): when true, the prompt is prefixed to request compact digests instead of full file contents. Defaults on for plan, off for accept-edits.
@@ -390,7 +390,8 @@ export async function registerAskAntigravityTool(
 			}
 
 			const body = result.content[0]?.type === "text" ? result.content[0].text : "";
-			const errored = d?.exitCode !== 0 || !!d?.aborted || !!d?.timedOut;
+			const errored =
+		d?.exitCode !== 0 || !!d?.aborted || !!d?.timedOut || !!d?.empty;
 
 			let text = errored
 				? theme.fg("error", "✗ AskAntigravity error")
@@ -536,7 +537,16 @@ export async function registerAskAntigravityTool(
 			// Honor the shared permissions setting (same knob as the provider). Non-
 			// interactive -p can't answer a permission prompt, so when this is off
 			// any run_command will hang - but the setting must mean what it says.
-			if (config.skipPermissions !== false) args.push("--dangerously-skip-permissions");
+			// Plan mode never gets the flag even when the knob is on: the flag
+			// auto-approves ALL permission requests including plan mode's own
+			// approval gate, which would silently turn "review-only" into full
+			// write access inside --add-dir (probed 2026-09-25: with the flag a
+			// plan run wrote files; without it, file and command attempts end
+			// exit 0 in ~20-30s with a "confirm plan" message - fail-visible,
+			// never a hang). Omitting it is what makes "plan = review-only" true.
+			if (mode !== "plan" && config.skipPermissions !== false) {
+				args.push("--dangerously-skip-permissions");
+			}
 			if (isContinuation) args.push("--conversation", rawConvId as string);
 			args.push("--print-timeout", `${timeoutMin}m`);
 			if (contextFile) args.push("--add-dir", askContextDir());
@@ -701,10 +711,11 @@ export async function registerAskAntigravityTool(
 				details.aborted = outcome.aborted;
 				details.timedOut = outcome.timedOut;
 				details.durationMs = Date.now() - start;
+				const text = out.trim();
 				log?.(
 					"ask-end",
-					{ exitCode: outcome.exitCode, aborted: outcome.aborted, timedOut: outcome.timedOut, durationMs: details.durationMs, conversationId: details.conversationId },
-					outcome.exitCode !== 0 || outcome.aborted || outcome.timedOut ? "warn" : "info",
+					{ exitCode: outcome.exitCode, aborted: outcome.aborted, timedOut: outcome.timedOut, empty: !text, durationMs: details.durationMs, conversationId: details.conversationId },
+					outcome.exitCode !== 0 || outcome.aborted || outcome.timedOut || !text ? "warn" : "info",
 				);
 
 				if (!isContinuation && !details.conversationId && snapshot) {
@@ -718,8 +729,6 @@ export async function registerAskAntigravityTool(
 					}
 				}
 
-				const text = out.trim();
-
 				if (outcome.aborted) {
 					return {
 						content: [
@@ -754,6 +763,25 @@ export async function registerAskAntigravityTool(
 					};
 				}
 
+				// Exit 0 with nothing on stdout is still a failure for the
+				// delegator: headless agy auto-denies a permission-gated tool call
+				// (e.g. the command gate in plan mode), prints the reason only to
+				// stderr, and ends cleanly. Falling through to the success path here
+				// returned just the conversation footer, which read as an empty
+				// success (silent-failure bug found 2026-09-25).
+				if (!text) {
+					details.empty = true;
+					const stderr = redactText(details.stderr.trim());
+					const note = [
+						"agy exited cleanly but produced no output.",
+						stderr ? `stderr: ${stderr}` : null,
+						"Common cause: a tool call needed a permission that headless mode cannot prompt for (typically the command gate in plan mode), so it was auto-denied. Allow-list it under permissions.allow in ~/.gemini/antigravity-cli/settings.json, or rerun outside plan mode with skipPermissions.",
+					]
+						.filter(Boolean)
+						.join(" ");
+					return { content: [{ type: "text", text: note }], details };
+				}
+
 				onUpdate?.({ content: [{ type: "text", text: "" }], details: { ...details } });
 				const footer = details.conversationId
 					? `\n\n[agy conversationId: ${details.conversationId} - pass as conversationId to continue this conversation]`
@@ -857,6 +885,9 @@ interface AgyDetails {
 	exitCode: number;
 	aborted: boolean;
 	timedOut: boolean;
+	// Exit 0 with no answer on stdout (the empty-output failure branch).
+	// renderResult flips to the error glyph on it.
+	empty?: boolean;
 	durationMs: number;
 	stderr: string;
 }

package/src/config.ts

@@ -13,6 +13,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { normalizeAgyAgentName } from "./agents.js";
 
 const CONFIG_PATH = path.join(
 	os.homedir(),
@@ -112,6 +113,9 @@ export interface AgyConfig {
 	 *  on the installed pi. The notice never repeats; /agy patch-cleanup is
 	 *  always available. */
 	patchCleanupNotified?: boolean;
+	/** Custom agy agent for stream-json turns (`--agent`, /agy agent).
+	 *  Absent = agy's default agent. ACP turns ignore it (no protocol slot). */
+	agent?: string;
 	/** Which pi tools the MCP bridge exposes to agy: "none" (bridge off),
 	 *  "all" (every registered non-builtin tool incl. other Ask* delegations;
 	 *  default - users expect the bridge working out of the box, and the
@@ -316,6 +320,11 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		usageEstimate,
 	};
 
+	// Custom agent for stream-json turns (--agent). Env wins over the file
+	// (same pattern as mode). Normalized (trim/cap/control-strip); an empty
+	// result means agy's default agent.
+	const agent = normalizeAgyAgentName(process.env.AGY_AGENT ?? file.agent);
+
 	return {
 		engine,
 		acp,
@@ -330,6 +339,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		systemPrompt,
 		turnTimeoutMin,
 		inactivityTimeoutMin,
+		agent,
 		approvals: { gateMode, mode: gateAskMode },
 		patchCleanupNotified: file.patchCleanupNotified === true,
 	};

package/src/driver-types.ts

@@ -18,6 +18,10 @@ export interface DriverProfile {
 	effort?: string;
 	mode: string;
 	skipPermissions: boolean;
+	/** Custom agy agent (stream-json `--agent`). ACP has no agent slot in the
+	 *  protocol (RC01) and ignores it; the /agy agent command refuses to set
+	 *  one while the ACP engine is active. */
+	agent?: string;
 }
 
 export interface DriverTurnRequest extends DriverProfile {
@@ -55,13 +59,15 @@ export type DriverActivity =
 	/** Stream-json emits a token count only; ACP carries the actual thought text in
 	 *  `delta`. The provider renders whichever is present. */
 	| { type: "thought"; tokens?: number; delta?: string }
-	| { type: "tool_start"; stepId?: number; name: string; args: Record<string, unknown>; mcpServer?: string }
+	| { type: "tool_start"; stepId?: number; name: string; args: Record<string, unknown>; mcpServer?: string; /** ACP only: the protocol toolCallId (stream-json carries numeric stepId instead). */ toolCallId?: string }
 	| {
 			type: "tool_done";
 			stepId?: number;
 			name: string;
 			args: Record<string, unknown>;
 			mcpServer?: string;
+			/** ACP only: the protocol toolCallId; pairs done/error with their start. */
+			toolCallId?: string;
 			output?: string;
 			durationSeconds?: number;
 			/** ACP only: the server's native edit diff from `tool_call`
@@ -69,7 +75,7 @@ export type DriverActivity =
 			 *  sets it; the provider renders it without any git subprocess. */
 			diff?: { path: string; oldText?: string; newText: string };
 	  }
-	| { type: "tool_error"; stepId?: number; name: string; message: string; mcpServer?: string }
+	| { type: "tool_error"; stepId?: number; name: string; message: string; mcpServer?: string; toolCallId?: string }
 	| { type: "usage"; usage: AgyUsage }
 	/** Synthetic: injected by the provider when the MCP bridge receives a call
 	 *  (G9). Parks the turn: output is expected to stall while pi executes the