@estebanforge/pi-antigravity-bridge 1.4.8 → 1.4.10

package/src/provider.ts

@@ -36,6 +36,8 @@ import { mapAgyToolToNative } from "./native-tools.js";
 import { type AgyEffort, type AgyModelEntry } from "./models.js";
 import { SessionStore } from "./sessions.js";
 import { loadConfig } from "./config.js";
+import { GATE_MARKER, mapNativeToShadow, stripMarkerFields } from "./approval-gate.js";
+import type { ApprovalDecision, ApprovalPayload, ApprovalParkApi } from "./mcp-server.js";
 import path from "node:path";
 import { TurnDiffContext, createExecGitOps, formatInlineDiff, parseEditToolInput } from "./diff-render.js";
 
@@ -72,7 +74,7 @@ function extractUserPrompt(context: Context): string | null {
 
 /** Image blocks of the latest user message (pi-ai ImageContent: base64 data
  *  + mimeType). The ACP engine forwards them as typed content blocks; the
- *  legacy CLI prompt is text-only, so its driver simply ignores these. */
+ *  stream-json CLI prompt is text-only, so its driver simply ignores these. */
 function extractImages(context: Context): Array<{ data: string; mimeType: string }> {
 	const last = context.messages[context.messages.length - 1];
 	if (!last || last.role !== "user" || typeof last.content === "string") return [];
@@ -114,12 +116,14 @@ export const SYSTEM_PROMPT_END = "[END SYSTEM PROMPT]";
 
 /** Brief tool-priority note appended inside every system prompt block: agy
  *  runs embedded in pi, so its native interactive tools never reach the
- *  user. Equivalent Pi Bridge tools must win. Concrete clash observed live:
- *  agy picked its native ask_question over the bridge's ask_user_question
- *  and the question never displayed. Rides the systemPrompt gate: the note
- *  ships only when the system prompt ships. */
+ *  user. Equivalent Pi Bridge tools must win. Concrete clashes observed
+ *  live: agy picked its native ask_question over the bridge's
+ *  ask_user_question and the question never displayed; on ACP its native
+ *  view_file rejects real filesystem paths (artifact sandbox), so reads of
+ *  the user's machine must go through the bridge. Rides the systemPrompt
+ *  gate: the note ships only when the system prompt ships. */
 export const TOOL_PRIORITY_NOTE =
-	"[Tool priority: this conversation runs inside pi, not as a standalone agy session; the user only sees what surfaces in pi. Native interactive tools, for example ask_question, never reach the user. When a Pi Bridge tool covers the same purpose, always use the Pi Bridge tool; for user questions use ask_user_question. Long-running bridge calls do not fail: after ~20 seconds the bridge answers STILL RUNNING with a callId; fetch the result with bridge_poll_result and poll until it lands. For work you already know is long, prefer exec_command's session-output pattern or background agents so you keep working while it runs.]";
+	"[Tool priority: this conversation runs inside pi, not as a standalone agy session; the user only sees what surfaces in pi. Native interactive tools, for example ask_question, never reach the user. When a Pi Bridge tool covers the same purpose, always use the Pi Bridge tool; for user questions use ask_user_question. Your native file tools such as view_file only read brain artifacts and reject real filesystem paths; for any path on the user's machine use the Pi Bridge tools (read, ls, grep, find, edit, execute). Long-running bridge calls do not fail: after ~20 seconds the bridge answers STILL RUNNING with a callId; fetch the result with bridge_poll_result and poll until it lands. For work you already know is long, prefer exec_command's session-output pattern or background agents so you keep working while it runs.]";
 
 /** Assemble the full agy prompt: system prompt block, pi-side digest, user
  *  prompt. Empty parts are dropped. Pure; exported for unit testing.
@@ -292,8 +296,8 @@ function sessionKey(
 ): string {
 	const sid = (options as { sessionId?: string } | undefined)?.sessionId;
 	const base = sid && sid.length > 0 ? `sid:${sid}` : `cwd:${cwd}`;
-	// Engine-scoped keys (plan 9.4): one ACP turn must never touch the legacy
-	// binding and vice versa. Un-suffixed keys = legacy, byte-compatible with
+	// Engine-scoped keys (plan 9.4): one ACP turn must never touch the stream
+	// binding and vice versa. Un-suffixed keys = stream-json, byte-compatible with
 	// every store that predates the ACP engine.
 	return base + (engine === "acp" ? "@acp" : "");
 }
@@ -310,12 +314,12 @@ export interface BlockState {
 export interface StreamSimpleDeps {
 	entries: AgyModelEntry[];
 	store: SessionStore;
-	/** Legacy stream-json driver (the tested default engine). Turns run on the
+	/** Stream-json driver (the tested default engine). Turns run on the
 	 *  driver and bridge calls park as toolUse round-trips. Required with
 	 *  roundTrips. */
 	driver?: TurnDriver;
 	/** Official-server ACP engine. Opt-in via config.engine = "acp"; when
-	 *  absent the config switch falls back to the legacy driver. */
+	 *  absent the config switch falls back to the stream driver. */
 	acpDriver?: TurnDriver;
 	roundTrips?: ToolRoundTrips;
 	/** Replay store for the display-only antigravity wrapper tool. Required
@@ -388,8 +392,19 @@ const BRIDGE_TIMEOUT_MS = 480_000;
 /** Bounded memory of failed bridge parks (late-delivery tombstones). */
 const MAX_PARK_TOMBSTONES = 64;
 
+/** One MCP tool-result content block: text always; image blocks carry base64
+ *  pixels and ride to the model on BOTH engines (ACP probe 2026-09-05;
+ *  stream-json probe 2026-09-07: the CLI's MCP client delivers tool-result
+ *  image content to the model). */
+export interface BridgeContentBlock {
+	type: string;
+	text?: string;
+	data?: string;
+	mimeType?: string;
+}
+
 export interface BridgeCallResultShape {
-	content: Array<{ type: string; text?: string }>;
+	content: BridgeContentBlock[];
 	isError: boolean;
 }
 
@@ -413,6 +428,11 @@ export const ESCALATE_AFTER_MS = 20_000;
 /** Escalated parks carry a longer TTL: human-gated tools (commit previews,
  *  permission dialogs) legitimately block for many minutes. */
 export const ESCALATED_TIMEOUT_MS = 1_800_000;
+/** Human-decision budget for one parked approval (docs/TODO.md 2.5). Same
+ *  envelope as the G9 park; the staged hook timeout exceeds it with margin
+ *  (approval-hook.stagedTimeoutSeconds). Exported: the extension needs the
+ *  same number for hooks.json staging and the hook script deadline. */
+export const APPROVAL_PARK_MS = BRIDGE_TIMEOUT_MS;
 
 export interface PollView {
 	state: "running" | "done" | "failed";
@@ -420,6 +440,7 @@ export interface PollView {
 	text?: string;
 	isError?: boolean;
 	reason?: string;
+	images?: Array<{ data: string; mimeType: string }>;
 }
 
 /** Escalated bridge calls. Bounded: past the cap, oldest settled entries
@@ -440,12 +461,13 @@ export class EscalationRegistry {
 		this.#calls.set(callId, { name, state: "running" });
 		this.#trim();
 	}
-	settleDone(callId: string, text: string, isError: boolean): void {
+	settleDone(callId: string, text: string, isError: boolean, images: Array<{ data: string; mimeType: string }> = []): void {
 		const e = this.#calls.get(callId);
 		if (!e) return;
 		e.state = "done";
 		e.text = text;
 		e.isError = isError;
+		if (images.length > 0) e.images = images;
 		this.#trim();
 	}
 	settleFailed(callId: string, reason: string): void {
@@ -501,15 +523,27 @@ export function formatPollAnswer(callId: string, view: PollView | undefined): Br
 			isError: true,
 		};
 	}
-	return { content: [{ type: "text", text: view.text || "(no output)" }], isError: view.isError ?? false };
+	return {
+		content: [
+			...(view.images ?? []).map((i) => ({ type: "image", data: i.data, mimeType: i.mimeType })),
+			{ type: "text", text: view.text || "(no output)" },
+		],
+		isError: view.isError ?? false,
+	};
 }
 
 interface PendingRoundTrip {
 	/** "bridge": parked MCP HTTP call; resolve() completes it.
 	 *  "rt": native re-exec / wrapper round-trip; pi already executed, the
-	 *  toolResult only confirms continuation, nothing remote to settle. */
-	kind: "bridge" | "rt";
+	 *  toolResult only confirms continuation, nothing remote to settle.
+	 *  "approval": parked approval gate decision; resolve() maps the shadow
+	 *  tool result to allow/deny and completes the /approval ticket. */
+	kind: "bridge" | "rt" | "approval";
 	name: string;
+	/** Approval entries only: the agy native tool this decision is for. */
+	nativeName?: string;
+	/** Approval entries only: park start, for the latency audit field. */
+	started?: number;
 	resolve?: (r: BridgeCallResultShape | BridgeEscalation) => void;
 	reject?: (e: Error) => void;
 	timer?: NodeJS.Timeout;
@@ -554,13 +588,17 @@ export class ToolRoundTrips {
 	#escalations = new EscalationRegistry();
 	#escalateAfterMs: number;
 	#getDriver: () => TurnDriver;
-	#log: (s: string, d?: unknown) => void;
+	#log: (s: string, d?: unknown, level?: "debug" | "info" | "warn" | "error") => void;
+	/** Approval park controls (mcp-server handle). Assigned by the extension
+	 *  only after at least one shadow tool is registered, so an approval
+	 *  toolUse can never dispatch to the REAL builtin and execute locally. */
+	#approvalPark?: ApprovalParkApi;
 
 	/** Accepts a driver or a getter: with two engines wired, the ACTIVE driver
 	 *  is resolved at call time from config (plan §9.5). */
 	constructor(
 		driver: TurnDriver | (() => TurnDriver),
-		log?: (s: string, d?: unknown) => void,
+		log?: (s: string, d?: unknown, level?: "debug" | "info" | "warn" | "error") => void,
 		opts: { escalateAfterMs?: number } = {},
 	) {
 		this.#getDriver = typeof driver === "function" ? driver : () => driver;
@@ -591,6 +629,79 @@ export class ToolRoundTrips {
 		return this.#escalations.poll(callId);
 	}
 
+	/** Wire the approval park (mcp-server handle.approvals). The extension
+	 *  assigns this AFTER the shadow tools are registered; see onApproval. */
+	set approvalPark(api: ApprovalParkApi | undefined) {
+		this.#approvalPark = api;
+	}
+
+	/** Approval gate (docs/TODO.md 2.5): a PreToolUse hook parked a native agy
+	 *  tool call. Interrupt the pi-side view of the still-running agy turn
+	 *  with a toolUse for the SHADOW tool (same bridge_call mechanism as G9,
+	 *  so both drivers pause their turn timers); pi's permission extensions
+	 *  gate it, the shadow execute() consults the fallback policy, and the
+	 *  arriving toolResult maps to the terminal decision (resolve()).
+	 *  Every failure path denies fail-closed: an approval must never be
+	 *  granted by accident. */
+	onApproval(ticket: string, payload: ApprovalPayload): void {
+		const deny = (reason: string): void => {
+			this.#log("approval-denied-pre-park", { ticket, reason });
+			this.#approvalPark?.resolve(ticket, { allow: false, reason });
+		};
+		if (!this.#approvalPark) return deny("shadow tools are not registered");
+		const native = payload?.toolCall?.name;
+		if (typeof native !== "string" || native.length === 0) return deny("approval payload has no tool name");
+		const handle = this.#getDriver().activeHandle;
+		if (!handle) return deny("no active antigravity turn");
+		const args = (payload.toolCall.args && typeof payload.toolCall.args === "object"
+			? payload.toolCall.args
+			: {}) as Record<string, unknown>;
+		const mapped = mapNativeToShadow(native, args);
+		if (!mapped) return deny(`tool ${native} is not in the approval matcher set`);
+		const entry: PendingRoundTrip = {
+			kind: "approval",
+			name: mapped.shadow,
+			nativeName: native,
+			started: Date.now(),
+			timer: setTimeout(() => {
+				this.#failApproval(
+					ticket,
+					`approval gate timed out after ${Math.round(APPROVAL_PARK_MS / 1000)}s`,
+					"timeout",
+				);
+			}, APPROVAL_PARK_MS),
+		};
+		this.#pending.set(ticket, entry);
+		handle.pushExternal({
+			type: "bridge_call",
+			callId: ticket,
+			name: mapped.shadow,
+			args: {
+				...mapped.input,
+				[GATE_MARKER]: true,
+				__agyTicket: ticket,
+				__agyTool: native,
+			},
+		});
+		this.#log("approval-parked", { ticket, native, shadow: mapped.shadow });
+	}
+
+	/** Settle a parked approval with a deny. Used by the park timeout and
+	 *  failAll; the ticket is answered (fail closed) and the pending entry
+	 *  dropped, so the late shadow tool result logs as approval-late. */
+	#failApproval(ticket: string, reason: string, cause: "timeout" | "shutdown"): void {
+		const entry = this.#pending.get(ticket);
+		this.#pending.delete(ticket);
+		if (entry?.timer) clearTimeout(entry.timer);
+		const resolved = this.#approvalPark?.resolve(ticket, { allow: false, reason }) ?? false;
+		this.#log(
+			resolved ? `approval-${cause}` : "approval-late",
+			{ ticket, native: entry?.nativeName, shadow: entry?.name, reason },
+			resolved && cause === "timeout" ? "warn" : "debug",
+		);
+		this.#getDriver().kickIdle();
+	}
+
 	/** Fail all pending calls (driver recycle/shutdown path). Escalated bridge
 	 *  calls are skipped: their HTTP request was already answered with a poll
 	 *  handle, and the agy turn ending does NOT make the still-running pi tool
@@ -599,6 +710,10 @@ export class ToolRoundTrips {
 	failAll(reason: string): void {
 		for (const id of [...this.#pending.keys()]) {
 			const entry = this.#pending.get(id);
+			if (entry?.kind === "approval") {
+				this.#failApproval(id, reason, "shutdown");
+				continue;
+			}
 			if (entry?.kind === "bridge" && entry.escalated) continue;
 			this.#fail(id, reason);
 		}
@@ -675,7 +790,10 @@ export class ToolRoundTrips {
 				}, this.#escalateAfterMs);
 			}
 			this.#pending.set(callId, entry);
-			handle.pushExternal({ type: "bridge_call", callId, name, args });
+			// Strip the internal marker fields from model-supplied args (peer
+			// review 2026-09-07): a real bridge call must never arrive at the
+			// shadow's gate branch with a forged __agyGate/__agyTicket.
+			handle.pushExternal({ type: "bridge_call", callId, name, args: stripMarkerFields(args) });
 		});
 	};
 
@@ -686,8 +804,15 @@ export class ToolRoundTrips {
 	}
 
 	/** Complete a parked call from a pi toolResult message. Returns false when
-	 *  the id matches nothing pending. */
-	resolve(toolCallId: string, text: string, isError: boolean): boolean {
+	 *  the id matches nothing pending. Image blocks ride the result on both
+	 *  engines (probe-verified on each); the late-delivery prompt stays
+	 *  text-only (see PI-BRIDGE-GAPS). */
+	resolve(
+		toolCallId: string,
+		text: string,
+		isError: boolean,
+		images: Array<{ data: string; mimeType: string }> = [],
+	): boolean {
 		const entry = this.#pending.get(toolCallId);
 		if (!entry) return false;
 		this.#pending.delete(toolCallId);
@@ -698,14 +823,47 @@ export class ToolRoundTrips {
 			this.#log("round-trip-rt-done", { callId: toolCallId, name: entry.name, isError });
 			return true;
 		}
+		if (entry.kind === "approval") {
+			clearTimeout(entry.timer);
+			this.#pending.delete(toolCallId);
+			// Decision mapping (docs/TODO.md 2.5): block/error -> deny with the
+			// text (pi turns a tool_call block into an error tool result, so both
+			// paths land here); synthetic success -> allow.
+			const decision: ApprovalDecision = isError
+				? { allow: false, reason: text || `blocked by approval gate (${entry.nativeName})` }
+				: { allow: true };
+			const delivered = this.#approvalPark?.resolve(toolCallId, decision) ?? false;
+			// Audit trail (docs/TODO.md 2.7): decision, source, latency.
+			this.#log(
+				delivered ? "approval-decision" : "approval-late",
+				{
+					ticket: toolCallId,
+					native: entry.nativeName,
+					shadow: entry.name,
+					decision: decision.allow ? "allow" : "deny",
+					source: isError ? "extension-block" : "policy",
+					reason: decision.allow ? undefined : decision.reason,
+					latencyMs: Date.now() - (entry.started ?? 0),
+				},
+				delivered ? "info" : "debug",
+			);
+			this.#getDriver().kickIdle();
+			return true;
+		}
 		// Escalated call: the HTTP response already carried the poll handle, so
 		// the result lands in the registry for the next bridge_poll_result. The
 		// original promise settled with the sentinel; re-resolving is a silent
 		// no-op, so gate it to keep that explicit.
 		if (entry.escalated) {
-			this.#escalations.settleDone(toolCallId, text, isError);
+			this.#escalations.settleDone(toolCallId, text, isError, images);
 		} else {
-			entry.resolve!({ content: [{ type: "text", text }], isError });
+			entry.resolve!({
+				content: [
+					...images.map((i) => ({ type: "image", data: i.data, mimeType: i.mimeType })),
+					{ type: "text", text },
+				],
+				isError,
+			});
 		}
 		this.#getDriver().kickIdle();
 		this.#log("round-trip-resolved", { callId: toolCallId, name: entry.name, isError });
@@ -713,19 +871,40 @@ export class ToolRoundTrips {
 	}
 }
 
-/** Extract toolResult messages whose toolCallId is still parked, as text. */
+/** Image blocks of a tool result (pi's read on an image file, screenshots).
+ *  Forwarded to agy as MCP image content (see BridgeContentBlock) on both
+ *  engines. Size relies on pi's own inline-image resize cap upstream; no
+ *  second cap here. */
+function extractResultImages(content: unknown): Array<{ data: string; mimeType: string }> {
+	if (!Array.isArray(content)) return [];
+	return content
+		.filter(
+			(b): b is { type: "image"; data: string; mimeType: string } =>
+				typeof b === "object" && b !== null && (b as { type?: string }).type === "image",
+		)
+		.map((b) => ({ data: b.data, mimeType: b.mimeType }))
+		.filter((i) => typeof i.mimeType === "string" && typeof i.data === "string" && i.data.length > 0);
+}
+
+/** Extract toolResult messages whose toolCallId is still parked, as text plus
+ *  any image blocks (forwarded as MCP image content on both engines). */
 export function collectToolResults(
 	messages: Message[],
 	pendingIds: readonly string[],
-): Array<{ toolCallId: string; text: string; isError: boolean }> {
+): Array<{ toolCallId: string; text: string; isError: boolean; images: Array<{ data: string; mimeType: string }> }> {
 	if (pendingIds.length === 0) return [];
 	const pending = new Set(pendingIds);
-	const out: Array<{ toolCallId: string; text: string; isError: boolean }> = [];
+	const out: Array<{ toolCallId: string; text: string; isError: boolean; images: Array<{ data: string; mimeType: string }> }> = [];
 	for (const m of messages) {
 		if (m.role !== "toolResult") continue;
 		const id = (m as { toolCallId?: string }).toolCallId;
 		if (!id || !pending.has(id)) continue;
-		out.push({ toolCallId: id, text: blocksToText(m.content).trim(), isError: m.isError === true });
+		out.push({
+			toolCallId: id,
+			text: blocksToText(m.content).trim(),
+			isError: m.isError === true,
+			images: extractResultImages(m.content),
+		});
 	}
 	return out;
 }
@@ -823,7 +1002,7 @@ export function consumeActivity(
 			appendText(stream, blocks, activity.delta);
 			return "continue";
 		case "thought":
-			// Legacy: token count only (no body). ACP: thought TEXT deltas —
+			// Stream-json: token count only (no body). ACP: thought TEXT deltas —
 			// rendered through the same thinking block pipeline (9.2).
 			if (typeof activity.delta === "string" && activity.delta.length > 0) {
 				appendThinking(stream, blocks, activity.delta);
@@ -963,7 +1142,13 @@ async function runTurnDriver(
 	const escalatedNames = results
 		.map((r) => deps.roundTrips.poll(r.toolCallId)?.name)
 		.filter((n): n is string => Boolean(n));
-	for (const r of results) deps.roundTrips.resolve(r.toolCallId, r.text, r.isError);
+	// Images ride tool results on BOTH engines (ACP probe 2026-09-05;
+	// stream-json probe 2026-09-07: the CLI's MCP client delivers tool-result
+	// image content to the model — two-tone PNG named from the result alone,
+	// no decoders in the frame trail). The late-delivery prompt and the
+	// stream-json prompt attachments stay text-only by design.
+	for (const r of results)
+		deps.roundTrips.resolve(r.toolCallId, r.text, r.isError, r.images);
 
 	// Late delivery: a toolResult whose park already failed (the abort/timeout
 	// path failed the park while the pi tool kept running). The work is done,
@@ -1107,7 +1292,7 @@ async function runTurnDriver(
 
 /** Build the streamSimple closure. Captures the model catalog + session store
  *  resolved at extension load. When a driver is provided, turns run on the
- *  persistent stream-json engine (config.engine selects; legacy remains as
+ *  persistent stream-json engine (config.engine selects; stream remains as
  *  fallback). */
 export function createStreamSimple(
 	deps: StreamSimpleDeps,
@@ -1139,8 +1324,8 @@ export function createStreamSimple(
 				replay: deps.replay,
 				nativeActive: deps.nativeActive,
 				// Record the engine of the driver that will ACTUALLY run: if the
-				// ACP driver is absent, the config switch falls back to legacy,
-				// and keying the session as @acp would store a legacy
+				// ACP driver is absent, the config switch falls back to stream,
+				// and keying the session as @acp would store a stream
 				// conversationId under the wrong engine scope.
 				engine: selected === deps.acpDriver ? "acp" : "stream-json",
 				log: deps.log,