@estebanforge/pi-antigravity-bridge 1.4.3 → 1.4.5

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.5] - 2026-09-04
+
+### Added
+
+- `/agy auth` subcommand: runs the antigravity-acp sign-in on demand (spawns the server, sends `authenticate`, waits for the browser round-trip to complete; minutes-scale). Signing in no longer rides the first Antigravity message, and both login-pending moments now point at `/agy auth`. The sign-in URL toast (and its ssh port-forward hint) fires during `/agy auth` exactly as it does during turns. After the authenticate reply the run waits up to 5 s for `acp_token.json` before killing the sign-in server, and a second concurrent `/agy auth` fails fast instead of racing the token write.
+
+### Changed
+
+- `/agy acp-auth` renamed to `/agy auth-manual` (no alias): it prints the manual credential setup for those who want it. Auth-error remediation, MANUAL_SETUP, README, and docs now point at `/agy auth` / `/agy auth-manual`, and the stale first-message login wording is gone from the manual steps.
+
+## [1.4.4] - 2026-09-04
+
+### Added
+
+- The Google sign-in URL now surfaces in pi. The ACP server hands the OAuth URL only to the browser-open call (nothing on stdout/stderr, headless or not), so a `BROWSER` wrapper script records the URL and forwards to the real opener; the connection watches the record file and logs it as an `auth-url` event. The extension toasts it at warning level with the ssh port-forward command for the redirect port, so logins work from SSH sessions on remote machines; local users keep the automatic browser open and get the URL as a fallback. An existing `BROWSER` setting is chained, not replaced.
+
+### Fixed
+
+- ACP login pending was reported only at the moment setup wrote `settings.json`, so after the restart, with `settings.json` in place but the browser login never completed, every check went silent: no toast, no hint, while the first ACP message had no token to use. `needsLogin` now tracks the token file (stat only, never read): `oauth-personal` without `acp_token.json` is login-pending, so the switch-time toast, the picker, and the `session_start` self-heal keep saying so on every start until the login is done.
+
+### Changed
+
+- Engine switching is command-only now: `/agy engine stream-json|acp`. The bare-`/agy` settings picker no longer carries an Engine row (nor the post-save setup run), so the switch surface cannot be hit accidentally; `/agy engine acp` keeps the self-service setup (binary + auth) and the login warning. The picker's plan+acp (RC01) guard stays in a narrower form: the mode row alone can still produce `plan` while the engine is `acp`.
+- ACP login-pending messages rewritten for end users: what happens (the server opens the Google sign-in page in your browser on the first Antigravity message), when (after the restart or immediately, per moment), and which account (your Antigravity subscription, the same Google account as the `agy` CLI). No URL to open manually. All remaining moments (engine switch, session start) now toast at warning level so the pending action stands out.
+- The "Turn engine" wording became "Engine" in the README env table, the config comment, and the architecture doc heading; the picker row itself is gone (engine switching is command-only, see above).
+
 ## [1.4.3] - 2026-09-04
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ Turns run through one of two engines behind the same provider surface (`config.e
 
 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.
 
-Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: on your first ACP message the server opens the Google login in your browser, and you sign in with the same account and plan you use for the Antigravity CLI (`agy`). It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy acp-auth`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
+Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -121,6 +121,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy                      status, or open the full settings picker (TUI)
 /agy status               print current settings + session counts
 /agy doctor               bridge state, driver counters, bridge port, last lifecycle events
+/agy auth                 run the antigravity-acp sign-in now (engine acp): opens the Google login in your browser, shows the URL when no browser opens
 /agy mode plan            review-only: agy plans but writes nothing
 /agy mode accept-edits    agy applies edits directly (default)
 /agy permissions on|off   auto-approve / prompt for tool calls (see warning)
@@ -132,7 +133,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /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 acp-auth                 manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
+/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)
 ```
@@ -154,7 +155,7 @@ For isolation when running any agent that executes commands without a confirmati
 | Variable | Purpose |
 | --- | --- |
 | `AGY_BIN` | Path to the agy binary. Defaults to `agy` on PATH. |
-| `AGY_ENGINE` | Turn engine: `stream-json` (default) or `acp`. Wins over the config file. |
+| `AGY_ENGINE` | Engine: `stream-json` (default) or `acp`. Wins over the config file. |
 | `AGY_ACP_BIN` | Path to the ACP server binary (`agy_acp_server.par`). Defaults to `agy_acp_server.par` on PATH. Wins over `config.acp.bin`. When neither points at a binary, auto-setup installs one. |
 | `AGY_EXTRA_ARGS` | Extra args appended to every invocation. Whitespace-split. |
 | `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |

package/docs/ACP-ADOPTION-PLAN.md

@@ -325,7 +325,7 @@ Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
 | Human decision latency on parked G9 tool round-trips exceeds the 10m overall-turn cap | Turn killed mid-wait | `AcpDriver` pauses the overall timer while parked, re-armed with REMAINING budget; every park carries its own timeout (9.3) |
 | Binary size (1.5 GB + 117 MB) | Disk + update churn | Pinned install layout (section 12), registry pin by build id |
 | aarch64 TCMalloc startup failure (forum report, Chromebook) | arch-specific | x86_64 unaffected; gate install per-arch, link the forum issue in README |
-| Separate auth state from `agy` CLI | First-run auth friction | `/agy acp-auth` prints exact instructions; `gemini-api-key` path works headless via `GEMINI_API_KEY`. The agent never writes credentials |
+| Separate auth state from `agy` CLI | First-run auth friction | `/agy auth-manual` prints exact instructions; `gemini-api-key` path works headless via `GEMINI_API_KEY`. The agent never writes credentials |
 | Thought text changes rendering volume | Noisy transcript | Route through the existing thinking block pipeline, close-on-switch unchanged; no new block types |
 | Two engines drift on behavior | Confusing support surface | Shared provider layer + shared parity suite run against both engines in CI |
 
@@ -827,7 +827,7 @@ Install layout:
   request (issue) once we depend on this.
 - `--uid=` from the linux registry entry: the server ran without it here.
   Treat as a launcher artifact; revisit if a future build refuses to start.
-- Auth onboarding: `/agy acp-auth` prints the four methods with exact
+- Auth onboarding: `/agy auth-manual` prints the four methods with exact
   `settings.json` shapes (source: official Zed docs, section 2.3). Headless
   path: `GEMINI_API_KEY` + `auth.type: "gemini-api-key"`. The agent NEVER
   writes or reads credentials; it prints instructions and verifies by

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 How the provider works internally. For build/test/debug workflow see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
-## Turn engine
+## Engine
 
 The provider ships two turn engines behind one contract (`TurnDriver`,
 `src/driver-types.ts`): the default **stream-json engine** (below) and the

package/docs/DEVELOPMENT.md

@@ -37,7 +37,7 @@ AGY_LIVE=1 node --experimental-strip-types scripts/smoke-stream-json.mjs
 
 # Live smoke for the ACP engine through OUR driver stack. OPT-IN: spends a
 # little quota. Needs AGY_ACP_BIN (or acp on PATH) and a one-time
-# /agy acp-auth credential setup.
+# /agy auth-manual credential setup.
 AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
   npx tsx scripts/smoke-acp.mjs
 

package/extensions/index.ts

@@ -40,6 +40,8 @@ import { SessionStore } from "../src/sessions.js";
 import { ToolRoundTrips, WrapperReplay, createStreamSimple } from "../src/provider.js";
 import { AgyDriver } from "../src/driver.js";
 import { AcpDriver } from "../src/acp/driver.js";
+import { runAcpAuth } from "../src/acp/auth.js";
+import { setupAuthUrlCapture } from "../src/acp/browser-capture.js";
 import { ensureAcpReady, inspectAcpSetup } from "../src/acp/setup.js";
 import type { TurnDriver } from "../src/driver-types.js";
 import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
@@ -58,6 +60,12 @@ import { mapAgyToolToNative } from "../src/native-tools.js";
 import { Type } from "typebox";
 import { patchStatus, restorePatch } from "../src/patch-cleanup.js";
 
+// Last UI seen (session_start / /agy commands). The ACP login URL arrives
+// via the driver log sink, which has no command context; the stash lets that
+// sink toast instead of only logging to stderr. Module scope: both the
+// default export (session_start, log sink) and registerAgyCommand assign it.
+let activeUi: ExtensionUIContext | null = null;
+
 function resolveAgyBinary(): string {
 	return process.env.AGY_BIN || "agy";
 }
@@ -102,6 +110,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// ACP self-heal runs once per process (session_start re-fires on /reload;
 	// a ready setup is two file stats, so re-running is harmless anyway).
 	let acpSelfHealRan = false;
+	// OAuth URL capture: the server hands the login URL only to the
+	// browser-open call (nothing on stdio), so a BROWSER wrapper records it
+	// and the driver logs it as "auth-url". Local users keep the automatic
+	// browser open; over SSH the URL surfaces for copy-paste with the
+	// port-forward command.
+	const authCapture = setupAuthUrlCapture();
+	if (!authCapture && process.platform !== "win32") {
+		// Rare (unwritable data dir). Surfacing the diagnostic: without it,
+		// login URLs would silently stop appearing on headless boxes.
+		console.error("[antigravity-bridge] OAuth URL capture unavailable; login URL surfacing is off (setup failed).");
+	}
 	// Two turn engines behind one contract (plan §9): stream-json (tested
 	// default) and the official ACP server (opt-in via config.engine, off by
 	// default). Neither spawns anything until its first turn.
@@ -117,14 +136,27 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		"unsupported-server-request",
 	]);
 	const legacyDriver = new AgyDriver();
+	// Shared ACP log sink (driver turns AND /agy auth): the login URL event
+	// toasts so SSH users can copy it; genuine failures reach stderr.
+	const acpLog = (msg: string, data?: unknown): void => {
+		if (msg === "auth-url") {
+			const { url, port } = (data ?? {}) as { url?: string; port?: number | null };
+			if (!url) return;
+			const ssh = port ? `\nSSH session? Forward the port on your machine first:\n  ssh -N -L ${port}:127.0.0.1:${port} <user@host>` : "";
+			const text = `Google sign-in URL for the ACP engine:\n${url}${ssh}`;
+			if (activeUi) activeUi.notify(text, "warning");
+			else console.error(`[antigravity-bridge acp] ${text}`);
+			return;
+		}
+		if (!acpFailures.has(msg)) return;
+		console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`);
+	};
 	const acpDriver = new AcpDriver({
 		// Resolved per connection: the setup flow can install the binary and
 		// update acp.bin mid-session; the next turn picks it up (no restart).
 		bin: () => loadConfig().acp.bin,
-		log: (msg, data) => {
-			if (!acpFailures.has(msg)) return;
-			console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`);
-		},
+		...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
+		log: acpLog,
 		mcpServers: () => {
 			const handle = mcpHandle;
 			if (!handle) return [];
@@ -204,6 +236,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		acpDriver,
 		engine,
 		getMcpPort: () => mcpHandle?.port ?? null,
+		acpLog,
+		authCapture: authCapture ?? null,
 	});
 
 	// AskAntigravity tool: one-shot delegation to agy (ported from
@@ -241,6 +275,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// normal toolUse loop (native cards, permissions, hooks) - no patch, no
 	// privileged API. Started on session_start, torn down on session_shutdown.
 	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.hasUI) activeUi = ctx.ui;
 		// 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.
@@ -270,8 +305,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
 					}
 					if (status.needsLogin) {
-						const msg = acpLoginPending("Your next antigravity message opens the browser;");
-						if (ctx.hasUI) ctx.ui.notify(msg, "info");
+						const msg = acpLoginPending();
+						if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 						else console.error(`[antigravity-bridge] ${msg}`);
 					}
 					return;
@@ -372,6 +407,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		}
 	});
 	pi.on("session_shutdown", async () => {
+		// The UI is going away; a later auth-url must fall back to stderr
+		// instead of toasting into a dead UI (where it would be lost).
+		activeUi = null;
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
@@ -384,11 +422,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 // --- /agy command -----------------------------------------------------------
 
 /** Shared body for every ACP-login-pending moment (session_start self-heal,
- *  /agy engine acp, picker): names the component so users know WHAT they are
- *  logging into, and that it is the same Google account as the agy CLI with
- *  its own token file. `browserTrigger` says when the browser opens. */
-function acpLoginPending(browserTrigger: string): string {
-	return `One-time Google login pending for the antigravity-acp server, Google's own ACP binary and a separate component of the Antigravity suite (agy desktop, agy editor, agy cli, agy acp). ${browserTrigger} Sign in with your Antigravity subscription account: the same Google account as your agy CLI login, but its own login and token file. One-time; tokens stay on your machine and this extension never sees them.`;
+ *  /agy engine acp). End-user simple: what to run, what happens, which
+ *  account. Sign-in is explicit (/agy auth); it never rides the first
+ *  message. */
+function acpLoginPending(): string {
+	return `One-time sign-in needed to finish ACP setup. Run /agy auth: the Google sign-in opens in your browser. Use the Google account of your Antigravity subscription (the same account as your agy CLI login). If no browser opens, pi shows the sign-in URL to copy. The token stays on your machine; this extension never sees it.`;
 }
 
 interface AgyCommandCtx {
@@ -400,10 +438,14 @@ interface AgyCommandCtx {
 	/** Engine latched at extension load (see the provider wiring note). */
 	engine: Engine;
 	getMcpPort: () => number | null;
+	/** Shared ACP log sink (login URL surfacing + failure events). */
+	acpLog: (msg: string, data?: unknown) => void;
+	/** BROWSER-capture handles; null when unavailable (Windows, unwritable
+	 *  data dir). /agy auth passes them to the sign-in process. */
+	authCapture: { browserEnv: Record<string, string>; file: string } | null;
 }
 
 interface PendingConfig {
-	engine?: Engine;
 	mode?: AgyMode;
 	skipPermissions?: boolean;
 	defaultModel?: string;
@@ -436,7 +478,7 @@ function statusText(ctx: AgyCommandCtx): string {
 		row("digest:", config.digest ? "on" : "off"),
 		row("system prompt:", config.systemPrompt ? "on" : "off"),
 		"",
-		"Subcommands: /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy ask on|off, /agy model <alias>, /agy thinking low|medium|high, /agy bridge all|mcp|none, /agy digest on|off, /agy system-prompt on|off, /agy acp-bin <path|auto>, /agy acp-auth, /agy patch-cleanup, /agy clear",
+		"Subcommands: /agy auth, /agy auth-manual, /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy ask on|off, /agy model <alias>, /agy thinking low|medium|high, /agy bridge all|mcp|none, /agy digest on|off, /agy system-prompt on|off, /agy acp-bin <path|auto>, /agy patch-cleanup, /agy clear",
 	].join("\n");
 }
 
@@ -444,9 +486,10 @@ function statusText(ctx: AgyCommandCtx): string {
 function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	pi.registerCommand("agy", {
 		description:
-			"Antigravity provider: status, doctor, settings picker, clear sessions. Usage: /agy [status|doctor|engine stream-json|acp|mode plan|accept-edits|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|bridge all|mcp|none|digest on|off|system-prompt on|off|acp-bin <path|auto>|acp-auth|patch-cleanup|clear]",
+			"Antigravity provider: status, doctor, settings picker, clear sessions. Usage: /agy [status|doctor|auth|auth-manual|engine stream-json|acp|mode plan|accept-edits|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|bridge all|mcp|none|digest on|off|system-prompt on|off|acp-bin <path|auto>|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
+			if (ui) activeUi = ui;
 			const mode = cmdCtx.mode;
 			const sub = (args ?? "").trim().split(/\s+/)[0]?.toLowerCase();
 			const val = (args ?? "").trim().split(/\s+/)[1]?.toLowerCase();
@@ -501,17 +544,55 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						return;
 					}
 					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
-					ui?.notify(
-						status.needsLogin
-							? `ACP engine ready. ${acpLoginPending("Your first ACP message (after the next pi start or /reload) opens the browser;")}`
-							: `ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`,
-						"info",
-					);
+					if (status.needsLogin) {
+						ui?.notify(
+							`ACP engine set. ${acpLoginPending()}`,
+							"warning",
+						);
+					} else {
+						ui?.notify(`ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`, "info");
+					}
 				} else {
 					ui?.notify(`current engine: ${loadConfig().engine}\nusage: /agy engine stream-json|acp`, "info");
 				}
 				return;
 			}
+			if (sub === "auth") {
+				// Gate on the CONFIGURED engine (disk + env), not the latched one:
+				// /agy engine acp followed by /agy auth in the same session works,
+				// no restart needed before signing in.
+				if (loadConfig().engine !== "acp") {
+					ui?.notify(`the selected engine is ${loadConfig().engine}. /agy engine acp first, then /agy auth.`, "warning");
+					return;
+				}
+				ui?.notify("Preparing the ACP server (binary + auth settings)…", "info");
+				const status = await ensureAcpReady({ configBin: loadConfig().acp.bin, onProgress: (m) => ui?.notify(m, "info") });
+				if (!status.ok) {
+					ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
+					return;
+				}
+				saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+				if (!status.needsLogin) {
+					ui?.notify(`Already signed in (auth: ${status.auth}). Nothing to do.`, "info");
+					return;
+				}
+				ui?.notify(
+					"Signing in: the Google sign-in opens in your browser and completes when you finish it (minutes-scale). If no browser opens, pi shows the sign-in URL to copy.",
+					"info",
+				);
+				const r = await runAcpAuth({
+					bin: status.bin,
+					extraEnv: ctx.authCapture?.browserEnv,
+					authUrlFile: ctx.authCapture?.file,
+					log: ctx.acpLog,
+				});
+				if (r.ok) {
+					ui?.notify("Signed in. The ACP engine is ready; takes effect on the next pi start (or /reload).", "info");
+				} else {
+					ui?.notify(`ACP sign-in failed (${r.error}).\nRun /agy auth to retry; /agy auth-manual has manual steps.`, "warning");
+				}
+				return;
+			}
 			if (sub === "acp-bin") {
 				const rest = (args ?? "").trim().split(/\s+/).slice(1).join(" ");
 				if (rest.length > 0) {
@@ -530,7 +611,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				}
 				return;
 			}
-			if (sub === "acp-auth") {
+			if (sub === "auth-manual") {
 				ui?.notify(
 					[
 						"ACP engine authentication (one-time; usually automatic -",
@@ -546,14 +627,16 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						"1. Server binary: auto-setup installs it. Manual: agy_acp_server.par from",
 						"   the antigravity-acp registry; point acp.bin or AGY_ACP_BIN at it.",
 						'2. Default: put {"auth":{"type":"oauth-personal"}} in',
-						"   ~/.gemini/antigravity-acp/settings.json, run one turn, and complete the",
-						"   Google login that opens in your browser (headless: tunnel 127.0.0.1:<port>",
-						"   over ssh, then open the URL on your machine).",
+						"   ~/.gemini/antigravity-acp/settings.json, run /agy auth, and complete",
+						"   the Google login that opens in your browser. No browser (SSH",
+						"   session)? pi shows the sign-in URL to copy; forward the redirect",
+						"   port over ssh (ssh -N -L <port>:127.0.0.1:<port> <user@host>), then",
+						"   open the URL on your machine.",
 						'   Headless alternative: GEMINI_API_KEY + {"auth":{"type":"gemini-api-key"}}',
 						"   (metered paid API - not your Antigravity plan). The key is used only",
 						"   when that type is selected; with the default oauth-personal in place,",
 						"   an exported key is ignored.",
-						"3. Run one turn; /agy doctor shows the server version when auth is OK.",
+						"3. /agy doctor shows the server version when auth is OK.",
 					].join("\n"),
 					"info",
 				);
@@ -711,23 +794,15 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	});
 }
 
-/** Interactive settings picker (TUI only). Rows: the full runtime config
- *  surface (engine, mode, permissions, model, thinking, bridge, digest,
- *  system prompt). Picking acp runs the same self-service setup as
- *  `/agy engine acp` (binary + auth) right after the save. */
+/** Interactive settings picker (TUI only). Rows: the runtime config surface
+ *  (mode, permissions, model, thinking, bridge, digest, system prompt).
+ *  Engine switching is command-only: /agy engine stream-json|acp (the
+ *  command also runs self-service binary + auth setup for acp). */
 async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promise<void> {
 	const config = loadConfig();
 	const pending: PendingConfig = {};
 
 	const items: SettingItem[] = [
-		{
-			id: "engine",
-			label: "Turn engine",
-			description:
-				"stream-json: the streaming engine (default, supported). acp: Google's official ACP server (experimental, opt-in). Switch takes effect on the next pi start (or /reload); acp also runs binary + auth setup on save.",
-			currentValue: config.engine,
-			values: ["stream-json", "acp"],
-		},
 		{
 			id: "mode",
 			label: "Execution mode",
@@ -804,9 +879,7 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			Math.min(items.length + 4, 15),
 			getSettingsListTheme(),
 			(id, newValue) => {
-				if (id === "engine") {
-					pending.engine = newValue as Engine;
-				} else if (id === "mode") {
+				if (id === "mode") {
 					pending.mode = newValue as AgyMode;
 				} else if (id === "permissions") {
 					pending.skipPermissions = newValue === "auto-approved";
@@ -840,16 +913,13 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 
 	if (Object.keys(pending).length === 0) return;
 
-	// The engine latches at load: a plan mode active while the effective
-	// engine is (or will be) acp would silently run non-plan. ACP has no
-	// review-only mode (RC01); refuse the combination. Both sides fall back
-	// to the on-disk config so a fresh engine pick over a saved plan (and
-	// vice versa) is caught too.
-	const nextEngine = pending.engine ?? ctx.engine;
+	// The picker cannot switch engines (command-only: /agy engine), but the
+	// mode row can still produce plan while the latched engine is acp. ACP
+	// has no review-only mode (RC01); refuse the combination.
 	const nextMode = pending.mode ?? config.mode;
-	if (nextMode === "plan" && nextEngine === "acp") {
+	if (nextMode === "plan" && ctx.engine === "acp") {
 		ui.notify(
-			"plan + acp is not supported (RC01): the ACP engine has no review-only mode. Save mode accept-edits or pick the stream-json engine first.",
+			"plan + acp is not supported (RC01): the ACP engine has no review-only mode. /agy engine stream-json first, or /agy mode accept-edits.",
 			"warning",
 		);
 		return;
@@ -858,7 +928,6 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 	try {
 		const next = saveConfig(pending);
 		const changed = [
-			pending.engine !== undefined ? `engine=${next.engine}` : null,
 			pending.mode ? `mode=${next.mode}` : null,
 			pending.skipPermissions !== undefined
 				? `permissions=${next.skipPermissions ? "auto-approved" : "prompt"}`
@@ -873,26 +942,6 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			.filter(Boolean)
 			.join(", ");
 		ui.notify(`Saved: ${changed}`, "info");
-		if (pending.engine === "acp") {
-			// Same flow as /agy engine acp: persist the switch, then prepare
-			// the server so the restart just works.
-			ui.notify("Preparing the ACP server (binary + auth)…", "info");
-			const status = await ensureAcpReady({
-				configBin: loadConfig().acp.bin,
-				onProgress: (m) => ui.notify(m, "info"),
-			});
-			if (status.ok) {
-				saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
-				ui.notify(
-					status.needsLogin
-						? `ACP server ready. ${acpLoginPending("Your first ACP message (after the restart) opens the browser;")}`
-						: `ACP server ready (auth: ${status.auth}).`,
-					"info",
-				);
-			} else {
-				ui.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
-			}
-		}
 	} catch (err) {
 		ui.notify(
 			`Failed to save config: ${err instanceof Error ? err.message : String(err)}`,

package/package.json

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

@@ -0,0 +1,71 @@
+import { AcpConnection } from "./connection.js";
+import { hasAcpToken } from "./setup.js";
+
+// Explicit sign-in (/agy auth): spawn a short-lived server, send
+// `authenticate` (the RPC that fires the loopback listener + browser OAuth
+// flow), and wait for the token to land in the shared acp_token.json. A
+// dedicated process keeps the minutes-scale login ritual away from live
+// turns; the next driver connection picks the token up. The real server
+// blocks until the browser round-trip completes; the observed window is
+// minutes-scale (one flow timed out at ~8.5 minutes), so the timeout is
+// generous.
+
+export const AUTH_TIMEOUT_MS = 10 * 60_000;
+
+export interface AcpAuthOptions {
+	bin: string;
+	binArgs?: string[];
+	cwd?: string;
+	extraEnv?: Record<string, string>;
+	authUrlFile?: string;
+	/** The server is expected to have written acp_token.json by the time
+	 *  authenticate replies, but write-after-reply is unverified; after a
+	 *  successful reply the run polls for the token up to this long before
+	 *  SIGTERM, so a laggard write is never killed mid-flight. */
+	tokenGraceMs?: number;
+	timeoutMs?: number;
+	log?: (msg: string, data?: unknown) => void;
+}
+
+export interface AcpAuthResult {
+	ok: boolean;
+	/** Failure reason (spawn, timeout, -32000 family, concurrent run). Absent when ok. */
+	error?: string;
+}
+
+let authInFlight: Promise<AcpAuthResult> | null = null;
+
+export function runAcpAuth(opts: AcpAuthOptions): Promise<AcpAuthResult> {
+	const conn = new AcpConnection({
+		bin: opts.bin,
+		binArgs: opts.binArgs,
+		cwd: opts.cwd ?? process.cwd(),
+		extraEnv: opts.extraEnv,
+		authUrlFile: opts.authUrlFile,
+		log: opts.log ?? (() => {}),
+		onUpdate: () => {},
+		onExit: () => {},
+	});
+	const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+	const grace = opts.tokenGraceMs ?? 5_000;
+	const run = async (): Promise<AcpAuthResult> => {
+		try {
+			await conn.start();
+			await conn.request("authenticate", { methodId: "oauth-personal" }, opts.timeoutMs ?? AUTH_TIMEOUT_MS);
+			const deadline = Date.now() + grace;
+			while (!hasAcpToken() && Date.now() < deadline) await sleep(200);
+			return { ok: true };
+		} catch (err) {
+			return { ok: false, error: err instanceof Error ? err.message : String(err) };
+		} finally {
+			conn.kill();
+		}
+	};
+	// One sign-in at a time: two concurrent runs would race the OAuth loopback
+	// and the token write. A second invocation fails fast instead.
+	if (authInFlight) return Promise.resolve({ ok: false, error: "a sign-in is already running; wait for it to finish" });
+	authInFlight = run();
+	return authInFlight.finally(() => {
+		authInFlight = null;
+	});
+}

package/src/acp/browser-capture.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// The ACP server hands the Google OAuth URL ONLY to the browser-open call:
+// nothing on stdout or stderr, headless or not (verified per
+// docs/ACP-PROTOCOL-REFERENCE.md). The capture makes the URL visible:
+// BROWSER points at a wrapper that appends the URL to a record file and then
+// execs the real opener, and the connection watches the record file to log
+// "auth-url". Local users keep the automatic browser open; over SSH the user
+// copies the URL and forwards the redirect port.
+
+export interface AuthUrlCapture {
+	/** Spawn env for the ACP server (BROWSER -> wrapper script). */
+	browserEnv: Record<string, string>;
+	/** Record file the connection watches. */
+	file: string;
+	/** Most recent URL in the record file, or null. */
+	lastUrl(): string | null;
+}
+
+/** First existing executable named `name` on `env.PATH`, or null. */
+export function findOnPath(name: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+		if (!dir) continue;
+		const candidate = path.join(dir, name);
+		try {
+			const st = fs.statSync(candidate);
+			if (st.isFile() && (st.mode & 0o111) !== 0) return candidate;
+		} catch {
+			/* not here */
+		}
+	}
+	return null;
+}
+
+/** Last http(s) line of `file`, or null (absent/unreadable counts as empty). */
+export function readLastUrl(file: string): string | null {
+	try {
+		const lines = fs.readFileSync(file, "utf8").split("\n").filter((l) => /^https?:\/\//.test(l));
+		return lines.at(-1) ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** Port of the OAuth loopback redirect (redirect_uri param), or null. */
+export function parseAuthPort(url: string): number | null {
+	try {
+		const redirect = new URL(url).searchParams.get("redirect_uri");
+		if (!redirect) return null;
+		const port = new URL(redirect).port;
+		return port ? Number(port) : null;
+	} catch {
+		return null;
+	}
+}
+
+const shQuote = (s: string): string => `'${s.replace(/'/g, "'\\''")}'`;
+
+/** Create the capture (record file + wrapper script) and return the spawn
+ *  env. Idempotent: the wrapper is rewritten only when content changes. The
+ *  opener to forward to is resolved once, at write time: an existing BROWSER
+ *  wins, then xdg-open, then macOS open; with none available the wrapper
+ *  records the URL and exits (headless: capture without an opener). The
+ *  forward word-splits the BROWSER value, so flag forms (`open -a Chrome`)
+ *  work; a BROWSER path containing spaces does not (rare, and BROWSER lists
+ *  are not honored either - the first entry is what chains). Windows browser
+ *  resolution differs; no capture there. */
+export function setupAuthUrlCapture(dataDir = path.join(os.homedir(), ".pi", "agent", "antigravity-bridge"), env: NodeJS.ProcessEnv = process.env): AuthUrlCapture | null {
+	if (process.platform === "win32") return null;
+	const file = path.join(dataDir, "acp-auth-urls.log");
+	const wrapper = path.join(dataDir, "acp-browser-wrapper.sh");
+	try {
+		fs.mkdirSync(dataDir, { recursive: true });
+		// Truncate: the file mirrors the current login attempt only. OAuth
+		// URLs carry state + PKCE challenges, so keep the record private.
+		fs.writeFileSync(file, "", { mode: 0o600 });
+		const opener = env.BROWSER?.trim() || findOnPath("xdg-open", env) || findOnPath("open", env) || "";
+		const body = [
+			"#!/usr/bin/env sh",
+			"# Antigravity bridge: records the Google OAuth URL the ACP server hands",
+			"# to the browser, then forwards to the real opener. The bridge watches",
+			"# the record file and shows the URL in pi (copy it when logging in over",
+			"# SSH; forward the redirect port first).",
+			`printf '%s\\n' "$@" >> ${shQuote(file)}`,
+			`REAL=${shQuote(opener)}`,
+			'if [ -n "$REAL" ]; then set -f; exec $REAL "$@"; fi',
+			"",
+		].join("\n");
+		const write = (p: string, content: string, mode: number): void => {
+			try {
+				if (fs.readFileSync(p, "utf8") === content) return;
+			} catch {
+				/* new file */
+			}
+			fs.writeFileSync(p, content, { mode });
+		};
+		write(wrapper, body, 0o755);
+		return { browserEnv: { BROWSER: wrapper }, file, lastUrl: () => readLastUrl(file) };
+	} catch {
+		return null; // capture is best effort; login still works without it
+	}
+}

package/src/acp/connection.ts

@@ -20,8 +20,10 @@
 //     LIST; a dead URL is accepted at session time (lazy connect)
 
 import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parseAuthPort, readLastUrl } from "./browser-capture.js";
 import { JsonRpcResponseError, JsonRpcSession } from "./jsonrpc.js";
 
 export interface AcpMcpServer {
@@ -36,7 +38,7 @@ export interface AcpSessionInfo {
 }
 
 /** Auth failed (-32000 family). Message carries the remediation the server
- *  provided plus the /agy acp-auth pointer. */
+ *  provided plus the /agy auth-manual pointer. */
 export class AcpAuthError extends Error {
 	constructor(message: string) {
 		super(message);
@@ -63,6 +65,11 @@ export interface AcpConnectionOptions {
 	 *  "auto" selects the first allow option; "deny" fail-closes to the first
 	 *  reject option. Absent = deny (fail closed). */
 	permissions?: () => "auto" | "deny";
+	/** Record file for BROWSER-captured OAuth URLs (src/acp/browser-capture.ts).
+	 *  The server hands the login URL only to the browser-open call, so the
+	 *  wrapper records it there; the connection watches the file and logs
+	 *  "auth-url" {url, port} for every new URL. */
+	authUrlFile?: string;
 }
 
 const INIT_TIMEOUT_MS = 30_000;
@@ -80,6 +87,8 @@ export class AcpConnection {
 	agentInfo: Record<string, unknown> | undefined;
 	/** Last known mode/model config echo from set_config_option results. */
 	lastConfigOptions: unknown = undefined;
+	#authUrlWatcher: fs.FSWatcher | undefined;
+	#lastAuthUrl: string | null = null;
 
 	constructor(opts: AcpConnectionOptions) {
 		this.#opts = opts;
@@ -117,6 +126,7 @@ export class AcpConnection {
 			...(this.#opts.extraEnv ? { env: { ...process.env, ...this.#opts.extraEnv } } : {}),
 		});
 		this.#child = child;
+		if (this.#opts.authUrlFile) this.#watchAuthUrl();
 		child.stdout?.setEncoding("utf8");
 		child.stderr?.setEncoding("utf8");
 		// Pipe failures arrive asynchronously as stream 'error' events; the sync
@@ -373,9 +383,36 @@ export class AcpConnection {
 		}
 	}
 
+	/** Surface OAuth login URLs captured by the BROWSER wrapper: every new
+	 *  URL in the record file is logged once as "auth-url" {url, port}. Best
+	 *  effort only - a broken watch never affects turns. */
+	#watchAuthUrl(): void {
+		const file = this.#opts.authUrlFile!;
+		try {
+			const watcher = fs.watch(file, () => this.#emitAuthUrl());
+			// Without a listener, a watch 'error' event escapes as uncaught.
+			watcher.on("error", () => {
+				/* record file gone: login URL surfacing is off until respawn */
+			});
+			this.#authUrlWatcher = watcher;
+		} catch {
+			/* no watch; the one-shot check below still covers earlier writes */
+		}
+		this.#emitAuthUrl(); // URLs recorded before the watch started
+	}
+
+	#emitAuthUrl(): void {
+		const url = readLastUrl(this.#opts.authUrlFile!);
+		if (!url || url === this.#lastAuthUrl) return;
+		this.#lastAuthUrl = url;
+		this.#opts.log("auth-url", { url, port: parseAuthPort(url) });
+	}
+
 	#finish(reason: string): void {
 		if (this.#exited) return;
 		this.#exited = true;
+		this.#authUrlWatcher?.close();
+		this.#authUrlWatcher = undefined;
 		this.abortAll(`connection exited: ${reason || "process gone"}`);
 		this.#opts.onExit({ code: null, signal: null, stderrTail: this.#stderrTail });
 	}
@@ -387,7 +424,7 @@ export function translateError(method: string, err: unknown): Error {
 		if (err.code === -32000) {
 			const detail = typeof err.data === "object" && err.data !== null ? (err.data as { message?: unknown }).message : undefined;
 			const detailText = typeof detail === "string" ? `: ${detail}` : `: ${err.message}`;
-			return new AcpAuthError(`ACP authentication required for ${method}${detailText}. Run /agy acp-auth for setup instructions.`);
+			return new AcpAuthError(`ACP authentication required for ${method}${detailText}. Run /agy auth to sign in; /agy auth-manual has manual steps.`);
 		}
 		// Typed protocol errors survive: callers probe .code (-32601 cancel-
 		// unsupported, -32602 param shape). The method prefix is lost — describe()

package/src/acp/driver.ts

@@ -41,6 +41,9 @@ export interface AcpDriverOptions {
 	/** Extra argv for the binary (tests: node + fake-server script). */
 	binArgs?: string[];
 	extraEnv?: Record<string, string>;
+	/** Record file for BROWSER-captured OAuth URLs; passed to the connection,
+	 *  which logs "auth-url" when the server tries to open a login. */
+	authUrlFile?: string;
 	/** Bridge registration for session/new AND session/load. */
 	mcpServers?: () => AcpMcpServer[];
 	log?: (msg: string, data?: unknown) => void;
@@ -422,6 +425,7 @@ export class AcpDriver implements TurnDriver {
 			bin: resolveAcpBinary(typeof this.#opts.bin === "function" ? this.#opts.bin() : this.#opts.bin),
 			binArgs: this.#opts.binArgs,
 			extraEnv: this.#opts.extraEnv,
+			authUrlFile: this.#opts.authUrlFile,
 			cwd: request.cwd,
 			mcpServers: this.#opts.mcpServers,
 			log: (msg, data) => this.#log(msg, data),

package/src/acp/setup.ts

@@ -48,8 +48,8 @@ export type AcpSetupStatus =
 			bin: string;
 			binarySource: "env" | "config" | "installed" | "existing";
 			auth: string;
-			/** True when auth was just set to oauth-personal: the server opens
-			 *  Google login in the browser on the first ACP message. */
+			/** True when auth was just set to oauth-personal: /agy auth opens
+			 *  the Google login in the browser. */
 			needsLogin: boolean;
 			/** Human-readable actions taken (empty when everything was ready). */
 			actions: string[];
@@ -70,10 +70,10 @@ export const MANUAL_SETUP = [
 	"   (~/.local/opt/agy-acp/current/agy_acp_server.par works; 'current' is a",
 	"   symlink to the build dir).",
 	'3. Log in: put {"auth":{"type":"oauth-personal"}} in',
-	"   ~/.gemini/antigravity-acp/settings.json and complete the Google login that",
-	"   opens in your browser on your first ACP message. That login IS your",
+	"   ~/.gemini/antigravity-acp/settings.json and run /agy auth, then complete",
+	"   the Google login that opens in your browser. That login IS your",
 	"   Antigravity subscription (Google AI Plus/Pro/Ultra).",
-	"Details: /agy acp-auth",
+	"Details: /agy auth-manual",
 ].join("\n");
 
 export function platformKey(): string {
@@ -227,6 +227,23 @@ export interface AuthState {
 	type?: string;
 }
 
+/** Token presence WITHOUT reading any credential value: acp_token.json is
+ *  stat()ed, never opened. The token only exists after the browser login
+ *  round-trip, so this is the real proof of a completed login. */
+function tokenPresent(target: string): boolean {
+	try {
+		fs.statSync(path.join(target, "acp_token.json"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Whether a login token exists (default dir, or an explicit one). */
+export function hasAcpToken(dir?: string): boolean {
+	return tokenPresent(dir ?? path.join(os.homedir(), ".gemini", "antigravity-acp"));
+}
+
 /** Auth state WITHOUT reading any credential value: settings.json carries
  *  only auth.type (+ non-secret gcp placement), acp_token.json is stat()ed. */
 export function readAuthState(dir?: string): AuthState {
@@ -240,12 +257,7 @@ export function readAuthState(dir?: string): AuthState {
 	} catch {
 		/* absent or garbage = unconfigured */
 	}
-	try {
-		fs.statSync(path.join(target, "acp_token.json"));
-		return { configured: true, type: "token" };
-	} catch {
-		return { configured: false };
-	}
+	return tokenPresent(target) ? { configured: true, type: "token" } : { configured: false };
 }
 
 /** Write a minimal auth block into settings.json. The server reads this file
@@ -327,7 +339,7 @@ export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupS
 	// before the first spawn, so a fresh write takes effect. oauth-personal is
 	// THE default: it is the Antigravity subscription (same Google account and
 	// plan as the agy CLI login). gemini-api-key (metered paid API) stays a
-	// manual option for headless boxes (/agy acp-auth); never the default.
+	// manual option for headless boxes (/agy auth-manual); never the default.
 	const gdir = defaultGeminiDir(opts);
 	const auth = readAuthState(gdir);
 	if (!auth.configured) {
@@ -344,12 +356,18 @@ export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupS
 			};
 		}
 	}
+	// settings.json alone proves nothing: setup writes it before the login,
+	// the token file only appears after the browser round-trip. oauth-personal
+	// without a token = login still pending, and every caller (switch toast,
+	// session_start self-heal) must keep saying so until the token exists.
+	// gemini-api-key has no browser login; a present token file means done.
+	const needsLogin = auth.type !== "gemini-api-key" && !tokenPresent(gdir);
 	return {
 		ok: true,
 		bin: binary.bin!,
 		binarySource: binary.source!,
 		auth: auth.type ?? "token",
-		needsLogin: false,
+		needsLogin,
 		actions,
 	};
 }

package/src/config.ts

@@ -39,7 +39,7 @@ export interface AcpConfig {
 }
 
 export interface AgyConfig {
-	/** Turn engine. Switching requires a pi restart (drivers wire at load). */
+	/** Engine. Switching requires a pi restart (drivers wire at load). */
 	engine: Engine;
 	/** Official-server ACP engine options (used when engine = "acp"). */
 	acp: AcpConfig;