@firespoon/pi-antigravity-bridge 0.0.0-stage → 1.10.7

package/src/acp/jsonrpc.ts

@@ -0,0 +1,232 @@
+// Newline-delimited JSON-RPC 2.0 session over a stdio transport.
+//
+// Transport-agnostic by design: the caller supplies a `send` sink (writes one
+// serialized frame + newline to the child's stdin) and feeds incoming bytes to
+// `feed()`. Everything ACP-specific lives in connection.ts.
+//
+// Semantics verified live against agy 1.5.3 ACP:
+//   - requests are correlated by numeric id; responses reject the pending
+//     promise on JSON-RPC `error` results;
+//   - server-to-client REQUESTS (session/request_permission, fs/*, terminal/*)
+//     arrive as messages with both `method` and `id` and are answered through
+//     the handler registered via setRequestHandler;
+//   - notifications (session/update, auth_required) carry no id;
+//   - malformed lines are counted and dropped, never fatal (the parseAgyLine
+//     lesson: a chatty banner must not kill the reader loop);
+//   - `abortAll()` rejects every pending request (Gate D teardown: no promise
+//     survives a killed connection).
+
+import { isKnownNoiseLine, MAX_FRAME_BYTES, stripGluedNoise } from "../frame-guard.js";
+
+export interface JsonRpcErrorShape {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+export interface JsonRpcIncoming {
+	id?: number | string | null;
+	method?: string;
+	params?: unknown;
+	result?: unknown;
+	error?: JsonRpcErrorShape;
+}
+
+export type SendFn = (frame: string) => void;
+
+export interface JsonRpcSessionOptions {
+	send: SendFn;
+	/** Server-to-client request (has method + id). Return the result value, or
+	 *  throw to answer with a JSON-RPC error. */
+	onRequest?: (method: string, params: unknown) => Promise<unknown>;
+	/** Server-to-client notification (method, no id). */
+	onNotification?: (method: string, params: unknown) => void;
+	/** Unparseable line (logged, never fatal). */
+	onParseError?: (line: string) => void;
+	/** Frame-cap breach: the peer flooded stdout with no newline. The session
+	 *  aborts itself; the transport must kill the process. */
+	onOverflow?: (detail: string) => void;
+	/** Default timeout for requests without an explicit one (ms). 0 = none. */
+	defaultTimeoutMs?: number;
+}
+
+interface Pending {
+	resolve: (value: unknown) => void;
+	reject: (err: Error) => void;
+	timer?: ReturnType<typeof setTimeout>;
+	method: string;
+}
+
+export class JsonRpcSession {
+	#send: SendFn;
+	#opts: JsonRpcSessionOptions;
+	#pending = new Map<number, Pending>();
+	#nextId = 1;
+	#aborted = false;
+	#overflowed = false;
+	#lineBuf = "";
+	parseErrors = 0;
+
+	constructor(opts: JsonRpcSessionOptions) {
+		this.#opts = opts;
+		this.#send = opts.send;
+	}
+
+	/** Feed raw transport bytes. Stdio chunks are NOT newline-aligned: bytes
+	 *  are buffered and only complete lines are parsed (a frame split across a
+	 *  64KB pipe boundary must never be dropped). The buffer is capped: a peer
+	 *  flooding stdout with no newline breaches the cap and the session dies
+	 *  (onOverflow + abortAll), it never grows without bound. */
+	feed(chunk: string): void {
+		if (this.#overflowed) return;
+		this.#lineBuf += chunk;
+		if (this.#lineBuf.length > MAX_FRAME_BYTES) {
+			const detail = `${this.#lineBuf.length} bytes buffered with no newline (cap ${MAX_FRAME_BYTES})`;
+			this.#overflow(detail);
+			return;
+		}
+		const lines = this.#lineBuf.split("\n");
+		this.#lineBuf = lines.pop() ?? "";
+		for (const raw of lines) {
+			const line = raw.trim();
+			if (!line) continue;
+			// Known foreign noise (e.g. the Chromium launcher behind a browser
+			// login) is dropped before parsing, not counted as a parse error.
+			if (isKnownNoiseLine(line)) continue;
+			let msg: JsonRpcIncoming;
+			try {
+				msg = JSON.parse(line) as JsonRpcIncoming;
+			} catch {
+				// A noise FRAGMENT without its newline glued itself onto the next
+				// real frame; strip everything up to the marker and re-parse.
+				const repaired = stripGluedNoise(line);
+				if (repaired) {
+					try {
+						msg = JSON.parse(repaired) as JsonRpcIncoming;
+					} catch {
+						this.parseErrors += 1;
+						this.#opts.onParseError?.(line.slice(0, 200));
+						continue;
+					}
+				} else {
+					// Malformed lines are counted and dropped, never fatal (the
+					// parseAgyLine lesson: a chatty banner must not kill the reader
+					// loop).
+					this.parseErrors += 1;
+					this.#opts.onParseError?.(line.slice(0, 200));
+					continue;
+				}
+			}
+			this.#handleMessage(msg);
+		}
+	}
+
+	#overflow(detail: string): void {
+		this.#overflowed = true;
+		this.#lineBuf = "";
+		// Aborting first gives pending requests the typed overflow reason; the
+		// transport's own teardown afterwards is a no-op on the empty map.
+		this.abortAll(`stdout frame overflow: ${detail}`);
+		this.#opts.onOverflow?.(detail);
+	}
+
+	#handleMessage(msg: JsonRpcIncoming): void {
+		// Response to one of our requests.
+		if (msg.method === undefined && msg.id !== undefined && msg.id !== null) {
+			const id = Number(msg.id);
+			const pending = this.#pending.get(id);
+			if (!pending) return; // late response to an aborted request: drop
+			this.#pending.delete(id);
+			if (pending.timer) clearTimeout(pending.timer);
+			if (msg.error) {
+				pending.reject(new JsonRpcResponseError(msg.error));
+			} else {
+				pending.resolve(msg.result);
+			}
+			return;
+		}
+		if (msg.method === undefined) return;
+		// Server-to-client request: must be answered with the same id. The
+		// handler is always invoked through Promise.resolve() so a synchronous
+		// throw can never escape into the reader loop.
+		if (msg.id !== undefined && msg.id !== null) {
+			const id = msg.id;
+			const handler = this.#opts.onRequest;
+			if (!handler) {
+				this.#sendError(id, -32601, `client does not support method: ${msg.method}`);
+				return;
+			}
+			void Promise.resolve()
+				.then(() => handler(msg.method as string, msg.params))
+				.then((result) => {
+					if (this.#aborted) return;
+					this.#send(JSON.stringify({ jsonrpc: "2.0", id, result: result ?? {} }));
+				})
+				.catch((err: unknown) => {
+					if (this.#aborted) return;
+					const message = err instanceof Error ? err.message : String(err);
+					this.#sendError(id, -32000, message);
+				});
+			return;
+		}
+		// Notification.
+		this.#opts.onNotification?.(msg.method, msg.params);
+	}
+
+	#sendError(id: number | string, code: number, message: string): void {
+		if (this.#aborted) return;
+		this.#send(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }));
+	}
+
+	/** Send a request. Resolves with the result value; rejects on error
+	 *  responses (JsonRpcResponseError), timeouts, or abortAll(). */
+	request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown> {
+		if (this.#aborted) return Promise.reject(new Error("connection aborted"));
+		const id = this.#nextId++;
+		const effective = timeoutMs ?? this.#opts.defaultTimeoutMs ?? 0;
+		return new Promise<unknown>((resolve, reject) => {
+			const pending: Pending = { resolve, reject, method };
+			if (effective > 0) {
+				pending.timer = setTimeout(() => {
+					this.#pending.delete(id);
+					reject(new Error(`ACP request timed out after ${effective}ms: ${method}`));
+				}, effective);
+			}
+			this.#pending.set(id, pending);
+			this.#send(JSON.stringify({ jsonrpc: "2.0", id, method, params: params ?? {} }));
+		});
+	}
+
+	notify(method: string, params?: unknown): void {
+		if (this.#aborted) return;
+		this.#send(JSON.stringify({ jsonrpc: "2.0", method, params: params ?? {} }));
+	}
+
+	/** Reject every pending request (Gate D teardown). The transport is going
+	 *  away; nothing will ever be written again. */
+	abortAll(reason: string): void {
+		this.#aborted = true;
+		for (const [id, pending] of this.#pending) {
+			if (pending.timer) clearTimeout(pending.timer);
+			pending.reject(new Error(`${reason} (request: ${pending.method})`));
+			this.#pending.delete(id);
+		}
+	}
+
+	get pendingCount(): number {
+		return this.#pending.size;
+	}
+}
+
+/** A JSON-RPC `error` result, preserving code + data (the -32602 `loc` paths
+ *  and the -32601 method name are correction oracles; see the reference doc). */
+export class JsonRpcResponseError extends Error {
+	readonly code: number;
+	readonly data: unknown;
+	constructor(error: JsonRpcErrorShape) {
+		super(error.message);
+		this.name = "JsonRpcResponseError";
+		this.code = error.code;
+		this.data = error.data;
+	}
+}

package/src/acp/setup.ts

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface AcpCleanupResult {
+	removedBuilds: string[];
+	rootRemoved: boolean;
+}
+
+export function defaultManagedAcpRoot(): string {
+	return path.join(os.homedir(), ".local", "opt", "agy-acp");
+}
+
+function regularFile(file: string): boolean {
+	try {
+		return fs.lstatSync(file).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function realDirectory(file: string): boolean {
+	try {
+		const stat = fs.lstatSync(file);
+		return stat.isDirectory() && !stat.isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+function enoent(err: unknown): boolean {
+	return (err as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+/** Remove only artifacts carrying the old installer's layout markers. */
+export function cleanupManagedAcpInstall(root: string = defaultManagedAcpRoot()): AcpCleanupResult {
+	let rootStat: fs.Stats;
+	try {
+		rootStat = fs.lstatSync(root);
+	} catch (err) {
+		if (enoent(err)) return { removedBuilds: [], rootRemoved: false };
+		throw err;
+	}
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return { removedBuilds: [], rootRemoved: false };
+
+	const entries = fs.readdirSync(root, { withFileTypes: true });
+	const interrupted = new Set<string>();
+	for (const entry of entries) {
+		const match = /^\.download-(.+)\.zip$/.exec(entry.name);
+		if (!match || !regularFile(path.join(root, entry.name))) continue;
+		interrupted.add(match[1]!);
+		try {
+			fs.unlinkSync(path.join(root, entry.name));
+		} catch (err) {
+			if (!enoent(err)) throw err;
+		}
+	}
+
+	const removedBuilds: string[] = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+		const dir = path.join(root, entry.name);
+		if (!regularFile(path.join(dir, "agy_acp_server.par"))) {
+			if (interrupted.has(entry.name)) {
+				try {
+					if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+				} catch (err) {
+					if (!enoent(err)) throw err;
+				}
+			}
+			continue;
+		}
+		const marked =
+			regularFile(path.join(dir, "zip.sha256")) ||
+			realDirectory(path.join(dir, "localharness_external")) ||
+			interrupted.has(entry.name);
+		if (!marked) continue;
+		try {
+			fs.rmSync(dir, { recursive: true, force: true });
+			removedBuilds.push(entry.name);
+		} catch (err) {
+			if (!enoent(err)) throw err;
+		}
+	}
+
+	const current = path.join(root, "current");
+	try {
+		if (fs.lstatSync(current).isSymbolicLink()) {
+			const target = path.resolve(root, fs.readlinkSync(current));
+			if (path.dirname(target) === root && removedBuilds.includes(path.basename(target))) fs.unlinkSync(current);
+		}
+	} catch (err) {
+		if (!enoent(err)) throw err;
+	}
+
+	let rootRemoved = false;
+	try {
+		if (fs.readdirSync(root).length === 0) {
+			fs.rmdirSync(root);
+			rootRemoved = true;
+		}
+	} catch (err) {
+		if (enoent(err)) rootRemoved = true;
+		else throw err;
+	}
+	return { removedBuilds, rootRemoved };
+}

package/src/acp/usage-estimate.ts

@@ -0,0 +1,61 @@
+// Gate B stopgap: synthesize AgyUsage for ACP turns until Google ships a
+// real token-usage layer in agy_acp_server. Counting mechanism copied from
+// the pi-token-speed extension (npm:pi-token-speed, src/engine.ts): a
+// word/punctuation regex, 1 match = 1 token. The numbers are client-side
+// ESTIMATES, never provider data: the connection's usageSeen latch (Gate B
+// watch) keeps synthesis off the day real usage appears in any frame, so
+// estimates can never shadow real numbers.
+
+import type { UsageEstimate } from "../config.js";
+import type { AgyUsage } from "../driver-types.js";
+
+const TOKEN_REGEX = /\w+|[^\s\w]/g;
+
+/** Word-boundary token estimate (pi-token-speed's estimateTokens). */
+export function estimateTokens(text: string): number {
+	if (!text) return 0;
+	const matches = text.match(TOKEN_REGEX);
+	return matches ? matches.length : 0;
+}
+
+export interface UsageEstimateInput {
+	mode: UsageEstimate;
+	/** Full outgoing prompt text (input side; always regex-estimated). */
+	prompt: string;
+	/** Cached estimate for repeated live updates during the same turn. */
+	inputTokens?: number;
+	/** ACP embeddedContext resource text (G1 digest): also reaches the model. */
+	contextText?: string;
+	/** Per-delta token sums (mode "estimate"). Summing per delta, like
+	 *  pi-token-speed's recordDelta, avoids word-merge artifacts when a
+	 *  chunk boundary splits a word. */
+	textTokens: number;
+	thoughtTokens: number;
+	/** Streamed delta counts (mode "direct": 1 token per delta). */
+	textDeltas: number;
+	thoughtDeltas: number;
+}
+
+/** Synthesize usage for a finished turn, or undefined when nothing is worth
+ *  reporting (mode off, or a turn with no prompt and no output). */
+export function synthesizeUsage(input: UsageEstimateInput): AgyUsage | undefined {
+	if (input.mode === "off") return undefined;
+	const inputTokens = input.inputTokens ?? estimateTokens(
+		input.contextText ? `${input.prompt}\n${input.contextText}` : input.prompt,
+	);
+	const thoughtTokens =
+		input.mode === "direct" ? input.thoughtDeltas : input.thoughtTokens;
+	const textTokens =
+		input.mode === "direct" ? input.textDeltas : input.textTokens;
+	// Thinking folds INTO output (OpenAI convention: reasoning tokens bill as
+	// output). toPiUsage drops thinking_tokens, and thinking time is inside
+	// elapsed wall time, so folding keeps the tokens/time ratio honest.
+	const outputTokens = textTokens + thoughtTokens;
+	if (inputTokens === 0 && outputTokens === 0) return undefined;
+	return {
+		input_tokens: inputTokens,
+		output_tokens: outputTokens,
+		thinking_tokens: thoughtTokens,
+		total_tokens: inputTokens + outputTokens,
+	};
+}

package/src/agents.ts

@@ -0,0 +1,64 @@
+// agy custom-agent roster (stream-json engine only).
+//
+// `agy agent` (alias `agents`) lists the user's custom agents one per line.
+// Live-verified against agy 1.2.10: bare names, no banner and no columns
+// when agents exist; help text on bad flags; empty output when none. The
+// parser still tolerates a name-plus-description column layout and banner
+// lines so a future agy that annotates the listing keeps parsing.
+//
+// A picked name rides the turn request as `--agent` (same flag our web
+// tools already pass for their throwaway agents). ACP has no agent slot in
+// per-turn agent selection, so the bridge refuses it at the command level.
+
+import { spawnAgyRaw } from "./models.js";
+
+/** Agent names are agy agent-dir names: filesystem-safe tokens. */
+export const AGENT_NAME_MAX = 128;
+const AGENT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** Parse raw `agy agent` output into agent names. Tolerant: skips empty and
+ *  banner/help lines, takes the first whitespace-separated token per line
+ *  (a future description column survives), rejects names that are not
+ *  filesystem-safe tokens, dedupes preserving order. */
+export function parseAgyAgentsRaw(text: string): string[] {
+	const seen = new Set<string>();
+	const agents: string[] = [];
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		// Help output and older banner formats are noise, not agent names
+		// (checked on the whole line: "List available agents" has no single
+		// banner token).
+		if (/^(usage:|flags:|-h\b|list available|available agents)/i.test(trimmed)) continue;
+		const token = trimmed.split(/\s+/)[0] ?? "";
+		if (!AGENT_NAME_RE.test(token) || seen.has(token)) continue;
+		seen.add(token);
+		agents.push(token);
+	}
+	return agents;
+}
+
+/** True when `name` is a valid agent-dir token (what `--agent` accepts). */
+export function isValidAgyAgentName(name: string): boolean {
+	return AGENT_NAME_RE.test(name);
+}
+
+/** Normalize a configured agent value: trim, cap, strip control characters;
+ *  empty result means "no agent configured". Kept permissive beyond the
+ *  token regex so a user typo reaches agy's own validation (a visible
+ *  turn error) instead of silently reverting to the default agent. */
+export function normalizeAgyAgentName(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const cleaned = value
+		.trim()
+		.replace(/[\x00-\x1f\x7f]/g, "")
+		.slice(0, AGENT_NAME_MAX);
+	return cleaned === "" ? undefined : cleaned;
+}
+
+/** List the custom agents `agy agent` reports. "" stdout (missing binary,
+ *  failure, cap) parses to [], so callers can treat "no agents" and "could
+ *  not ask" the same way the command layer renders it. */
+export async function listAgyAgents(binary: string = "agy"): Promise<string[]> {
+	return parseAgyAgentsRaw(await spawnAgyRaw(binary, ["agent"]));
+}

package/src/agy-install.ts

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { isAgyInstalled } from "./engine-picker.js";
+
+export interface AgyInstallCommand {
+	command: string;
+	args: string[];
+}
+
+export function agyInstallCommand(platform: NodeJS.Platform = process.platform): AgyInstallCommand {
+	if (platform === "win32") {
+		return {
+			command: "powershell.exe",
+			args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", "irm https://antigravity.google/cli/install.ps1 | iex"],
+		};
+	}
+	return {
+		command: "bash",
+		args: ["-c", "set -o pipefail; curl -fsSL https://antigravity.google/cli/install.sh | bash"],
+	};
+}
+
+export function agyAuthenticationMessage(): string {
+	return "Run `agy` in your terminal and complete the Google sign-in. Restart pi afterwards.";
+}
+
+type InstallRunner = (command: AgyInstallCommand, timeoutMs: number) => Promise<{ code: number | null; output: string }>;
+
+const defaultRunner: InstallRunner = ({ command, args }, timeoutMs) =>
+	new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			detached: process.platform !== "win32",
+			windowsHide: true,
+		});
+		let output = "";
+		let settled = false;
+		const append = (chunk: Buffer) => {
+			output = (output + chunk.toString("utf8")).slice(-64_000);
+		};
+		const fail = (err: Error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(watchdog);
+			reject(err);
+		};
+		child.stdout?.on("data", append);
+		child.stderr?.on("data", append);
+		child.on("error", fail);
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(watchdog);
+			resolve({ code, output: output.trim() });
+		});
+		const watchdog = setTimeout(() => {
+			try {
+				if (child.pid && process.platform === "win32") {
+					const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+					killer.on("error", () => {});
+					killer.unref();
+				} else if (child.pid) process.kill(-child.pid, "SIGKILL");
+				else child.kill("SIGKILL");
+			} catch {
+				// The process may have exited between the deadline and kill.
+			}
+			fail(new Error("Antigravity CLI installer exceeded 10 minutes"));
+		}, timeoutMs);
+	});
+
+export async function installAgyCli(opts: {
+	platform?: NodeJS.Platform;
+	run?: InstallRunner;
+	verify?: () => boolean | Promise<boolean>;
+	timeoutMs?: number;
+} = {}): Promise<{ ok: true; output: string } | { ok: false; error: string }> {
+	try {
+		const result = await (opts.run ?? defaultRunner)(agyInstallCommand(opts.platform), opts.timeoutMs ?? 10 * 60_000);
+		if (result.code !== 0) return { ok: false, error: result.output || `installer exited with code ${result.code ?? "unknown"}` };
+		const verify = opts.verify ?? (() => isAgyInstalled(process.env.AGY_BIN || "agy"));
+		if (!(await verify())) return { ok: false, error: "installer finished, but agy is not available in this pi process; open a new terminal, run `agy --version`, then restart pi" };
+		return { ok: true, output: result.output };
+	} catch (err) {
+		return { ok: false, error: err instanceof Error ? err.message : String(err) };
+	}
+}

package/src/agy-paths.ts

@@ -0,0 +1,30 @@
+// agy per-engine state dirs ("brain" trees).
+//
+// Both engines keep per-conversation state in the native CLI tree:
+//   ~/.gemini/antigravity-cli/brain/<conversationId>/
+// The ACP tree mirrors the CLI layout (.system_generated/tasks/,
+// .system_generated/steps/), so downstream scans (tasks, artifacts) work
+// unchanged once the right root is picked. A third tree exists —
+// ~/.gemini/antigravity-cli/conversations/<uuid>.db — but it serves
+// one-shot print-mode calls (AskAntigravity), NOT these features; do not
+// conflate the two. Conversation ids are the raw ids agy reports, no
+// hashing; the ids our session store persists match these dir names.
+
+import os from "node:os";
+import path from "node:path";
+import type { Engine } from "./config.js";
+
+/** Brain root for one engine. `home` injectable for tests. */
+export function agyBrainRoot(engine: Engine, home: string = os.homedir()): string {
+	return path.join(home, ".gemini", "antigravity-cli", "brain");
+}
+
+/** Per-conversation state dir. `conversationId` is the raw id agy reports
+ *  (and what the session store persists). */
+export function agyConversationDir(
+	engine: Engine,
+	conversationId: string,
+	home: string = os.homedir(),
+): string {
+	return path.join(agyBrainRoot(engine, home), conversationId);
+}

package/src/agy-setup.ts

@@ -0,0 +1,72 @@
+import { agyAuthenticationMessage, agyInstallCommand, installAgyCli } from "./agy-install.js";
+
+export interface AgySetupUi {
+	confirm: (title: string, body: string) => Promise<boolean>;
+	notify: (message: string, level: "info" | "warning") => void;
+	setStatus: (id: string, text?: string) => void;
+}
+
+export function createAgySetupOffer(opts: {
+	ui: AgySetupUi;
+	binaryOverride?: string;
+	install?: typeof installAgyCli;
+	missingMessage: () => string;
+	log: (event: string, data: unknown, level: "warn" | "info") => void;
+}): () => Promise<void> {
+	let offered = false;
+	let inFlight: Promise<void> | null = null;
+	const install = opts.install ?? installAgyCli;
+	const notify = (message: string, level: "info" | "warning") => {
+		try {
+			opts.ui.notify(message, level);
+		} catch (err) {
+			opts.log("agy-install", { error: String(err) }, "warn");
+		}
+	};
+
+	return () => {
+		if (inFlight) return inFlight;
+		if (offered) return Promise.resolve();
+		offered = true;
+		inFlight = (async () => {
+			try {
+				if (opts.binaryOverride) {
+					notify(
+						`AGY_BIN points to ${opts.binaryOverride}, which is missing or unsupported. Fix or unset AGY_BIN. The official installer cannot change this override.`,
+						"warning",
+					);
+					return;
+				}
+				const spec = agyInstallCommand();
+				const command = [spec.command, ...spec.args].join(" ");
+				const approved = await opts.ui.confirm(
+					"Antigravity CLI required",
+					`Both engines require the agy CLI. Run Google's official installer now?\n\n${command}`,
+				);
+				if (!approved) {
+					notify(opts.missingMessage(), "warning");
+					return;
+				}
+				opts.ui.setStatus("agy-install", "Installing Antigravity CLI…");
+				const result = await install();
+				if (!result.ok) {
+					opts.log("agy-install", { error: result.error }, "warn");
+					notify(`Antigravity CLI installation failed: ${result.error}\n${opts.missingMessage()}`, "warning");
+					return;
+				}
+				notify(`Antigravity CLI installed. ${agyAuthenticationMessage()}`, "info");
+			} catch (err) {
+				opts.log("agy-install", { error: String(err) }, "warn");
+				notify(`Antigravity CLI setup failed: ${String(err)}\n${opts.missingMessage()}`, "warning");
+			} finally {
+				try {
+					opts.ui.setStatus("agy-install", undefined);
+				} catch {
+					// UI teardown must not reject a shared setup promise.
+				}
+				inFlight = null;
+			}
+		})();
+		return inFlight;
+	};
+}