@estebanforge/pi-antigravity-bridge 1.8.7 → 1.8.8

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.8] - 2026-10-27
+
+### Fixed
+
+- **Short-circuit observational-memory background turns instead of letting Gemini hunt the missing observer tool.** pi-observational-memory's turn-end observer falls back to the session model, and its prompt demands a private `record_observations` tool the bridge never sends; on antigravity models that spawned autonomous `find`/`grep`/`sed` shell sweeps (~500 ms per cycle) hunting the tool before reporting "observer found nothing new in this chunk". `streamSimple` now detects the observer context structurally (its `record_observations`/`record_reflections`/`drop_observations` tool names) and finalizes with a clean empty stop, which engages the observer's empty-backoff instead of erroring every turn; a one-time per-process `observational-memory-unsupported` warning explains the gap.
+
+- **Strip Antigravity's echoed `<SYSTEM_MESSAGE>` notifications and default Queued Messages to send-immediately.** The backend injects async background-task notifications wrapped in `<SYSTEM_MESSAGE>` blocks, and Gemini (notably 3.8 Flash) echoes them verbatim as assistant text; a stateful streaming sanitizer (`src/stream-sanitizer.ts`) now suppresses the exact preamble+block pattern in both engines' text paths, failing open at EOF so legitimate text is never lost. Separately, the engines' default "Queued Messages" behavior buffered user input until turn end while pi sends interactive input mid-turn; the bridge now writes `"queuedMessages": "send-immediately"` to each engine's settings.json when unset (atomic, existing config respected, corrupt files never touched).
+
+- **Deliver image pixels across all the paths that used to lose them.** Verified live 2026-10-22 (couch session): gemini-3.8-flash read a screenshot, the parked bridge call escalated, the model never polled `bridge_poll_result`, and the stranded redelivery carried text only — the image never reached it and the model fell back to hunting OCR libraries. Late/stranded redeliveries now carry image blocks via `driver.run` (ACP native prompt blocks; stream-json stages them), user-attached images on the stream-json engine stage to temp files with a prompt note pointing at the bridge read tool (the CLI turn input is text-only; `src/prompt-images.ts`), and both engines now advertise `text+image` input. The tool-priority note states outright that `read` returns visible images (models refused screenshots from priors) and mandates polling `bridge_poll_result` before other work after a STILL RUNNING ack. Staging failures degrade to an explicit "image(s) could not be delivered" note instead of dropping silently.
+
 ## [1.8.7] - 2026-10-21
 
 ### Changed

package/extensions/index.ts

@@ -63,6 +63,7 @@ import { runAcpAuth } from "../src/acp/auth.js";
 import { setAuthInvalidatedHook } from "../src/acp/connection.js";
 import { setupAuthUrlCapture } from "../src/acp/browser-capture.js";
 import { clearAcpAuthVerified, ensureAcpReady, inspectAcpSetup } from "../src/acp/setup.js";
+import { ensureQueuedMessagesDefaults } from "../src/queued-messages.js";
 import type { TurnDriver, TurnOutcome } from "../src/driver-types.js";
 import { CONFIG_PATH, loadConfig, logsDir, MAX_TURN_CAP_MIN, parseCapMinutes, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
 import { agyMissingMessage, ENGINE_SETTINGS_ROW_ID, engineSettingsRow, isAgyInstalled, savedEngineMessage, showEnginePicker, shouldOfferEnginePicker } from "../src/engine-picker.js";
@@ -117,6 +118,8 @@ function resolveAgyBinary(): string {
 }
 
 export default async function (pi: ExtensionAPI): Promise<void> {
+	ensureQueuedMessagesDefaults({ onlyIfDirExists: true });
+
 	// Claim the AskAntigravity tool for this process. pi-ask-antigravity (if also
 	// installed) checks this in-process flag OR the bridge's package.json on disk
 	// and defers. See that extension's isBridgeInstalled().
@@ -144,9 +147,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// kickIdle, and reentry pointing at the other engine (round-7 finding).
 	const engine: Engine = loadConfig().engine;
 	// Engine switching requires a restart, so the catalog-time engine read is
-	// authoritative for input advertising: image attach rides only when turns
-	// will run on the ACP engine (the stream-json CLI prompt is text-only).
-	const modelInput: Array<"text" | "image"> = engine === "acp" ? ["text", "image"] : ["text"];
+	// authoritative for input advertising. Both engines accept images: ACP
+	// rides native content blocks; stream-json stages user attachments to
+	// temp files and the prompt points the model at them (prompt-images.ts).
+	const modelInput: Array<"text" | "image"> = ["text", "image"];
 	const models = entries.map((e) => toPiModel(e, modelInput));
 
 	// failAll reasons the bridge treats as routine (turn end / shutdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.8.7",
+  "version": "1.8.8",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. Use antigravity/* models in Pi. Full /model picker support. Models runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",

package/src/acp/driver.ts

@@ -736,6 +736,13 @@ export class AcpDriver implements TurnDriver {
 
 	#settle(turn: ActiveTurn, outcome: TurnOutcome): void {
 		if (turn.closed) return;
+		const flushed = turn.response.flush();
+		if (flushed) {
+			turn.textDeltas += 1;
+			turn.textTokens += estimateTokens(flushed);
+			this.#emit(turn, { type: "text", delta: flushed });
+		}
+		outcome.response = turn.response.text;
 		// Gate B stopgap: synthesize usage on clean turns while the server sends
 		// none. Runs BEFORE close so the usage activity drains through the
 		// normal #nextActivity loop (provider maps it onto partial.usage).

package/src/acp/events.ts

@@ -14,6 +14,10 @@
 //   - available_commands_update { availableCommands: [...] }
 // Usage: ABSENT on RC01 (Gate B) — mapped defensively should a future build add it.
 
+import { StreamSanitizer, sanitizeSystemMessage } from "../stream-sanitizer.js";
+
+export { StreamSanitizer, sanitizeSystemMessage };
+
 /** Map one `update` object to a driver-level event, or null when the update
  *  carries nothing the driver consumes (plan/commands are doctor/phase-2
  *  material; user_message_chunk is load replay and must never reach pi as
@@ -218,38 +222,60 @@ export function mapStopReason(stopReason: unknown): {
 const FLIP_MIN_CHARS = 32;
 
 export class TextAccumulator {
-	#acc = "";
+	#rawAcc = "";
+	#sanitizedAcc = "";
 	#cumulative: boolean | undefined;
+	#sanitizer = new StreamSanitizer();
 
 	/** Returns the delta to emit, or null when nothing new should be emitted. */
 	append(delta: string): string | null {
+		let rawEmit: string | null = null;
 		if (this.#cumulative === undefined) this.#cumulative = false;
 		else if (
 			!this.#cumulative &&
-			this.#acc.length >= FLIP_MIN_CHARS &&
-			delta.length > this.#acc.length &&
-			delta.startsWith(this.#acc)
+			this.#rawAcc.length >= FLIP_MIN_CHARS &&
+			delta.length > this.#rawAcc.length &&
+			delta.startsWith(this.#rawAcc)
 		) {
 			this.#cumulative = true;
 		}
 		if (this.#cumulative) {
-			if (!delta.startsWith(this.#acc)) {
+			if (!delta.startsWith(this.#rawAcc)) {
 				// Misflip evidence: back to deltas.
 				this.#cumulative = false;
-				this.#acc += delta;
-				return delta;
+				this.#rawAcc += delta;
+				rawEmit = delta;
+			} else if (delta.length <= this.#rawAcc.length) {
+				return null; // duplicate frame
+			} else {
+				rawEmit = delta.slice(this.#rawAcc.length);
+				this.#rawAcc = delta;
 			}
-			if (delta.length <= this.#acc.length) return null; // duplicate frame
-			const emit = delta.slice(this.#acc.length);
-			this.#acc = delta;
-			return emit;
+		} else {
+			this.#rawAcc += delta;
+			rawEmit = delta;
+		}
+
+		if (rawEmit === null) return null;
+		const sanitized = this.#sanitizer.push(rawEmit);
+		if (sanitized.length > 0) {
+			this.#sanitizedAcc += sanitized;
+			return sanitized;
+		}
+		return null;
+	}
+
+	flush(): string | null {
+		const flushed = this.#sanitizer.flush();
+		if (flushed.length > 0) {
+			this.#sanitizedAcc += flushed;
+			return flushed;
 		}
-		this.#acc += delta;
-		return delta;
+		return null;
 	}
 
 	get text(): string {
-		return this.#acc;
+		return this.#sanitizedAcc;
 	}
 }
 

package/src/acp/setup.ts

@@ -16,6 +16,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { ensureQueuedMessagesInFile, QUEUED_MESSAGES_SEND_IMMEDIATELY } from "../queued-messages.js";
 
 export const REGISTRY_URL =
 	"https://raw.githubusercontent.com/agentclientprotocol/registry/main/antigravity-acp/agent.json";
@@ -312,7 +313,11 @@ export function writeAuthType(type: "gemini-api-key" | "oauth-personal", dir?: s
 		/* fresh file */
 	}
 	const prevAuth = (typeof settings.auth === "object" && settings.auth !== null ? settings.auth : {}) as Record<string, unknown>;
-	fs.writeFileSync(file, `${JSON.stringify({ ...settings, auth: { ...prevAuth, type } }, null, 2)}\n`, { mode: 0o600 });
+	const nextSettings: Record<string, unknown> = { ...settings, auth: { ...prevAuth, type } };
+	if (typeof nextSettings.queuedMessages !== "string" || !nextSettings.queuedMessages.trim()) {
+		nextSettings.queuedMessages = QUEUED_MESSAGES_SEND_IMMEDIATELY;
+	}
+	fs.writeFileSync(file, `${JSON.stringify(nextSettings, null, 2)}\n`, { mode: 0o600 });
 }
 
 export interface BinaryResolution {
@@ -386,6 +391,7 @@ export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupS
 	// plan as the agy CLI login). gemini-api-key (metered paid API) stays a
 	// manual option for headless boxes (/agy auth-manual); never the default.
 	const gdir = defaultGeminiDir(opts);
+	ensureQueuedMessagesInFile(path.join(gdir, "settings.json"));
 	const auth = readAuthState(gdir);
 	if (!auth.configured) {
 		try {

package/src/driver-types.ts

@@ -32,7 +32,8 @@ export interface DriverTurnRequest extends DriverProfile {
 	prompt: string;
 	/** Image blocks riding with the prompt. ACP forwards them as typed
 	 *  content blocks (probe 2026-09-03: 64x64 two-tone PNG answered
-	 *  correctly); the stream-json CLI prompt is text-only and ignores them. */
+	 *  correctly); on stream-json the provider stages them to files, so the
+	 *  driver itself ignores this field. */
 	images?: Array<{ data: string; mimeType: string }>;
 	/** ACP only: pi-side context delivered as a native `embeddedContext`
 	 *  resource block instead of inline prompt text (G1 on ACP). Stream-json

package/src/driver.ts

@@ -21,7 +21,9 @@ import { isKnownNoiseLine, MAX_FRAME_BYTES, stripGluedNoise } from "./frame-guar
 import { bridgeMcpConfigDir, bridgeMcpConfigExists } from "./mcp-server.js";
 import { gateHooksStaged } from "./approval-hook.js";
 import { parkedTurnAnswer } from "./parked-turn.js";
+import { defaultCliSettingsPath, ensureQueuedMessagesInFile } from "./queued-messages.js";
 import { redactText } from "./redact.js";
+import { StreamSanitizer, sanitizeSystemMessage } from "./stream-sanitizer.js";
 import type {
 	AgyUsage,
 	DriverActivity,
@@ -44,6 +46,8 @@ export type {
 	TurnOutcome,
 } from "./driver-types.js";
 
+export { StreamSanitizer, sanitizeSystemMessage };
+
 const LIFECYCLE_LIMIT = 24;
 const THINKING_TOKEN_FLOOR = 64;
 
@@ -61,6 +65,8 @@ interface ActiveTurn {
 	idleTimer?: NodeJS.Timeout;
 	onAbort?: () => void;
 	response: string;
+	rawResponse: string;
+	sanitizer: StreamSanitizer;
 	usage?: AgyUsage;
 	conversationId?: string;
 	/** Wall clock at turn creation; the parked-turn probe filters
@@ -305,6 +311,8 @@ export class StreamDriver implements TurnDriver {
 			resolve,
 			outcome,
 			response: "",
+			rawResponse: "",
+			sanitizer: new StreamSanitizer(),
 			sawResult: false,
 			sawModelStep: false,
 			cumulativeText: undefined,
@@ -370,6 +378,8 @@ export class StreamDriver implements TurnDriver {
 		this.#boundConversation = request.conversationId ?? undefined;
 		this.#stderrTail = "";
 
+		ensureQueuedMessagesInFile(defaultCliSettingsPath());
+
 		const args: string[] = ["--add-dir", request.cwd];
 		// The bridge dir carries .agents/mcp_config.json (tool bridge) and, when
 		// the approval gate is on, .agents/hooks.json (gate staging). Only this
@@ -571,7 +581,11 @@ export class StreamDriver implements TurnDriver {
 				const ok = r.status === "OK" || r.status === "SUCCESS";
 				const status = ok ? "OK" : "ERROR";
 				// Prefer the streamed accumulation, fall back to the result body.
-				const response = turn.response || (typeof r.response === "string" ? r.response : "");
+				const fallback = typeof r.response === "string" ? sanitizeSystemMessage(r.response) : "";
+				const response = turn.response || fallback;
+				if (!turn.response && fallback) {
+					turn.sanitizer.reset();
+				}
 				turn.response = response;
 				this.#settle(turn, {
 					conversationId: turn.conversationId,
@@ -596,36 +610,54 @@ export class StreamDriver implements TurnDriver {
 		// misflips (round-7 review): short accumulations never flip, and a
 		// cumulative frame that no longer extends the accumulator is evidence
 		// of a misflip - fall back to append mode.
+		let rawDelta = "";
 		if (turn.cumulativeText === undefined) {
 			turn.cumulativeText = false;
 		} else if (
 			!turn.cumulativeText &&
-			shouldFlipToCumulative(turn.response, text)
+			shouldFlipToCumulative(turn.rawResponse, text)
 		) {
 			turn.cumulativeText = true;
 		}
 		if (turn.cumulativeText) {
-			if (!text.startsWith(turn.response)) {
+			if (!text.startsWith(turn.rawResponse)) {
 				// Misflip evidence: back to deltas.
 				turn.cumulativeText = false;
-				turn.response += text;
-				emit(turn, { type: "text", delta: text });
+				turn.rawResponse += text;
+				rawDelta = text;
+			} else if (text.length > turn.rawResponse.length) {
+				rawDelta = text.slice(turn.rawResponse.length);
+				turn.rawResponse = text;
+			} else {
 				return;
 			}
-			if (text.length > turn.response.length) {
-				const delta = text.slice(turn.response.length);
-				turn.response = text;
-				emit(turn, { type: "text", delta });
+		} else {
+			turn.rawResponse += text;
+			rawDelta = text;
+		}
+
+		if (rawDelta.length > 0) {
+			const sanitizedDelta = turn.sanitizer.push(rawDelta);
+			if (sanitizedDelta.length > 0) {
+				turn.response += sanitizedDelta;
+				emit(turn, { type: "text", delta: sanitizedDelta });
 			}
-			return;
 		}
-		turn.response += text;
-		emit(turn, { type: "text", delta: text });
 	}
 
 	#settle(turn: ActiveTurn, outcome: TurnOutcome): void {
 		if (turn.closed) return;
 		turn.closed = true;
+		const flushed = turn.sanitizer.flush();
+		if (flushed.length > 0) {
+			turn.response += flushed;
+			emit(turn, { type: "text", delta: flushed });
+		}
+		if (outcome.deadline && outcome.status === "OK") {
+			outcome.response = outcome.response || turn.response;
+		} else {
+			outcome.response = turn.response || outcome.response;
+		}
 		if (turn.overallTimer) clearTimeout(turn.overallTimer);
 		if (turn.idleTimer) clearTimeout(turn.idleTimer);
 		if (turn.onAbort && turn.request.signal) {
@@ -680,7 +712,7 @@ export class StreamDriver implements TurnDriver {
 			this.#settle(turn, {
 				conversationId: turn.conversationId,
 				status: "OK",
-				response: parked,
+				response: sanitizeSystemMessage(parked),
 				usage: turn.usage,
 				finished: true,
 				aborted: false,

package/src/models.ts

@@ -361,9 +361,8 @@ function thinkingLevelMapFor(efforts: readonly AgyEffort[]): ThinkingLevelMap {
 }
 
 /** Project an agy entry to pi's Model shape. `input` advertises accepted
- *  inputs: text-only (default) or text+image. The ACP engine forwards image
- *  blocks natively (probe 2026-09-03); the stream-json CLI prompt is text-only, so
- *  the extension decides by engine at load time. */
+ *  inputs; both engines accept images (ACP native content blocks,
+ *  stream-json staged files), so callers pass ["text", "image"] uniformly. */
 export function toPiModel(entry: AgyModelEntry, input: Array<"text" | "image"> = ["text"]): Model<Api> {
 	const effortDriven = !!entry.efforts && entry.efforts.length > 0;
 	return {
@@ -380,9 +379,8 @@ export function toPiModel(entry: AgyModelEntry, input: Array<"text" | "image"> =
 		// none is ever sent.
 		reasoning: effortDriven,
 		...(effortDriven ? { thinkingLevelMap: thinkingLevelMapFor(entry.efforts!) } : {}),
-		// Input advertising comes from the caller (engine-dependent): the ACP
-		// engine forwards image blocks; advertising images on the stream engine
-		// would let pi offer image attach only for them to be dropped.
+		// Input advertising comes from the caller: both engines deliver
+		// user-attached images now.
 		input,
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 		// Gemini long context. agy doesn't expose the real per-model window in

package/src/prompt-images.ts

@@ -0,0 +1,92 @@
+// Stream-json prompt staging: user-attached image blocks cannot ride the CLI's
+// text-only turn input, so they are staged to temp files and the prompt points
+// the model at them. The model views them through the bridge read tool, whose
+// tool-result image content the CLI's MCP client delivers (probe 2026-09-07).
+// The ACP engine does not use this module: image blocks ride session/prompt
+// natively.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const STAGE_DIR_PREFIX = "pi-bridge-img-";
+
+/** Retention for staged files: the model may re-read them on later turns of
+ *  the same conversation, so sweeps cannot delete a dir this turn's prompt
+ *  still references. */
+export const STAGE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface StagedImage {
+	data: string;
+	mimeType: string;
+}
+
+const EXT_BY_MIME: Record<string, string> = {
+	"image/png": ".png",
+	"image/jpeg": ".jpg",
+	"image/gif": ".gif",
+	"image/webp": ".webp",
+	"image/bmp": ".bmp",
+};
+
+function sweepStale(root: string): void {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(root);
+	} catch {
+		return;
+	}
+	const cutoff = Date.now() - STAGE_MAX_AGE_MS;
+	for (const entry of entries) {
+		if (!entry.startsWith(STAGE_DIR_PREFIX)) continue;
+		const full = path.join(root, entry);
+		try {
+			// lstat: never follow a symlink planted at our prefix in a shared tmp.
+			if (!fs.lstatSync(full).isDirectory()) continue;
+			if (fs.statSync(full).mtimeMs < cutoff) fs.rmSync(full, { recursive: true, force: true });
+		} catch {
+			// Raced with another process's sweep or deletion: nothing to do.
+		}
+	}
+}
+
+/** Write image blocks to a fresh staging dir under `root` (default the OS tmp
+ *  dir). Returns null on any failure (including an empty/malformed payload):
+ *  the turn then runs text-only instead of failing. */
+export function stagePromptImages(
+	images: Array<StagedImage>,
+	root?: string,
+): { dir: string; paths: string[] } | null {
+	const base = root ?? os.tmpdir();
+	let dir: string | null = null;
+	try {
+		sweepStale(base);
+		dir = fs.mkdtempSync(path.join(base, STAGE_DIR_PREFIX));
+		const paths = images.map((img, i) => {
+			const bytes = Buffer.from(img.data, "base64");
+			if (bytes.length === 0) throw new Error("empty image payload");
+			const ext = EXT_BY_MIME[img.mimeType] ?? ".bin";
+			const file = path.join(dir!, `image-${i + 1}${ext}`);
+			fs.writeFileSync(file, bytes, { mode: 0o600 });
+			return file;
+		});
+		return { dir, paths };
+	} catch {
+		// A mid-write failure must not leak a partial dir; the 24h sweep would
+		// reap it anyway, but the next staging call in this process is likely
+		// seconds away.
+		if (dir) {
+			try {
+				fs.rmSync(dir, { recursive: true, force: true });
+			} catch {
+				// Sweep reaps it later.
+			}
+		}
+		return null;
+	}
+}
+
+export function buildImageNote(paths: string[]): string {
+	const list = paths.map((p) => `- ${p}`).join("\n");
+	return `[The user attached ${paths.length} image(s) to this message. They are staged at:\n${list}\nView them by calling the pi read tool on these exact paths; the image content is delivered to you directly.]`;
+}

package/src/provider.ts

@@ -20,6 +20,7 @@
 import {
 	createAssistantMessageEventStream,
 	getCurrentSystemPrompt,
+	getCurrentTools,
 	type AssistantMessage,
 	type AssistantMessageEventStream,
 	type JsonValue,
@@ -44,6 +45,7 @@ import type { ApprovalDecision, ApprovalPayload, ApprovalParkApi } from "./mcp-s
 import path from "node:path";
 import { TurnDiffContext, createExecGitOps, formatInlineDiff, parseEditToolInput } from "./diff-render.js";
 import { stageSyspromptAgent } from "./sysprompt-agent.js";
+import { buildImageNote, stagePromptImages } from "./prompt-images.js";
 
 const DEFAULT_TIMEOUT_MIN = 10;
 
@@ -51,6 +53,29 @@ const DEFAULT_TIMEOUT_MIN = 10;
  *  the staged carrier agent (issue #2 inline-block fallback). */
 let warnedUserAgentConflict = false;
 
+/** Set of caller-scoped tool names declared by pi-observational-memory background workers.
+ *  Antigravity models run a closed tool loop on the backend CLI/ACP process and do not
+ *  support caller-scoped local tools. */
+export const OM_WORKER_TOOL_NAMES = new Set([
+	"record_observations",
+	"record_reflections",
+	"drop_observations",
+]);
+
+/** Detect if a turn belongs to a pi-observational-memory background worker. */
+export function isObservationalMemoryContext(context: TranscriptContext): boolean {
+	const currentTools = getCurrentTools(context.messages);
+	return currentTools.some((t) => OM_WORKER_TOOL_NAMES.has(t.name));
+}
+
+/** Track whether we have warned about observational-memory tool mismatch in this process. */
+let warnedObservationalMemoryMismatch = false;
+
+/** Reset latch for unit testing. */
+export function _resetObservationalMemoryWarnedForTesting(): void {
+	warnedObservationalMemoryMismatch = false;
+}
+
 /** conversationId -> staged carrier agent name. Gate-closed turns look the
  *  name up here so a conversation's agent field never flips: a change would
  *  recycle the agy process mid-conversation (profile drift), and a respawn
@@ -80,7 +105,8 @@ function extractUserPrompt(context: TranscriptContext): string | null {
 	if (!last || last.role !== "user") return null;
 	const content = last.content;
 	if (typeof content === "string") return content;
-	// Flatten text blocks; images ride separately via extractImages (ACP only).
+	// Flatten text blocks; images ride separately via extractImages (native
+	// blocks on ACP, staged files on stream-json via prompt-images.ts).
 	return content
 		.filter((b): b is { type: "text"; text: string } => b.type === "text")
 		.map((b) => b.text)
@@ -89,8 +115,9 @@ function extractUserPrompt(context: TranscriptContext): 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
- *  stream-json CLI prompt is text-only, so its driver simply ignores these. */
+ *  + mimeType). On the ACP engine they ride session/prompt as native
+ *  content blocks; on stream-json they are staged to temp files and the
+ *  prompt names the paths (see prompt-images.ts). */
 function extractImages(context: TranscriptContext): Array<{ data: string; mimeType: string }> {
 	const last = context.messages[context.messages.length - 1];
 	if (!last || last.role !== "user" || typeof last.content === "string") return [];
@@ -140,7 +167,7 @@ export const SYSTEM_PROMPT_END = "[END SYSTEM PROMPT]";
  *  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. 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). Delegate subagent work the same way: when pi's tool list includes a delegation tool (for example subagent, Agent, agent_spawn, agent_wait, or subagent_run), always delegate through it and never through the native invoke_subagent, run_subagent, or manage_subagents; use native ones only if no pi delegation tool is listed, because native subagents run inside agy and are invisible to pi and anything watching it. 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). Image files are visible to you: the Pi Bridge read tool returns image files as visible images (png, jpg, webp, gif, bmp), so never claim you cannot view images. When a bridge call answers STILL RUNNING, poll bridge_poll_result before doing other work: until you poll, the result (including any image) stays undelivered to you. Delegate subagent work the same way: when pi's tool list includes a delegation tool (for example subagent, Agent, agent_spawn, agent_wait, or subagent_run), always delegate through it and never through the native invoke_subagent, run_subagent, or manage_subagents; use native ones only if no pi delegation tool is listed, because native subagents run inside agy and are invisible to pi and anything watching it. 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.
@@ -922,7 +949,8 @@ export class ToolRoundTrips {
 	/** Complete a parked call from a pi toolResult message. Returns false when
 	 *  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). */
+	 *  text-only and its images re-attach through driver.run (native blocks on
+	 *  ACP, staged files on stream-json). */
 	resolve(
 		toolCallId: string,
 		text: string,
@@ -1033,6 +1061,9 @@ export interface LateToolResult {
 	reason: string;
 	text: string;
 	isError: boolean;
+	/** Image blocks of the stranded result (read on an image file). The
+	 *  redelivery prompt is text-only, so they ride driver.run images. */
+	images?: Array<{ data: string; mimeType: string }>;
 }
 
 /** Frame late tool results so agy treats them as the results its bridge calls
@@ -1308,8 +1339,10 @@ async function runTurnDriver(
 	// 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.
+	// no decoders in the frame trail). The late-delivery PROMPT stays
+	// text-only: image blocks ride driver.run images instead, so both
+	// engines deliver them (ACP native prompt blocks; stream-json staged
+	// files).
 	for (const r of results)
 		deps.roundTrips.resolve(r.toolCallId, r.text, r.isError, r.images);
 
@@ -1326,7 +1359,14 @@ async function runTurnDriver(
 	if (!isContinuation) {
 		for (const r of collectToolResults(context.messages, deps.roundTrips.deadIds)) {
 			const dead = deps.roundTrips.consumeDead(r.toolCallId);
-			if (dead) late.push({ name: dead.name, reason: dead.reason, text: r.text, isError: r.isError });
+			if (dead)
+				late.push({
+					name: dead.name,
+					reason: dead.reason,
+					text: r.text,
+					isError: r.isError,
+					images: r.images.length > 0 ? r.images : undefined,
+				});
 		}
 		if (late.length > 0) {
 			deps.log?.("late-result", { tools: late.map((l) => l.name), freshConversation: !existing?.conversationId }, "info");
@@ -1353,8 +1393,25 @@ async function runTurnDriver(
 				reason: "you never received this result: you ended your turn without calling bridge_poll_result",
 				text: view.text ?? "(no output)",
 				isError: view.isError ?? false,
+				images: view.images,
 			};
 		});
+	/** Stream-json has no image channel in the turn input: stage the blocks
+	 *  to temp files and let the note point the model at the bridge read
+	 *  tool, whose result images the CLI delivers (probe 2026-09-07). ACP
+	 *  rides native content blocks; no staging there. */
+	const stageImageNote = (imgs: Array<{ data: string; mimeType: string }>): string => {
+		if (deps.engine === "acp" || imgs.length === 0) return "";
+		const staged = stagePromptImages(imgs);
+		if (!staged) {
+			deps.log?.("turn-warning", { reason: "image-staging-failed", count: imgs.length }, "warn");
+			// Silence would strand the pixels forever: on a redelivery the claim
+			// is already consumed, so the model must at least learn the image
+			// existed and re-request it.
+			return `\n\n[${imgs.length} image(s) could not be delivered to this turn; ask the user to re-attach or re-read the original path.]`;
+		}
+		return `\n\n${buildImageNote(staged.paths)}`;
+	};
 
 	const entry = entries.find((e) => e.id === model.id) ?? null;
 	const agyModel = entry?.full ?? model.id;
@@ -1457,10 +1514,15 @@ async function runTurnDriver(
 				agent = stagedAgentByConversation.get(existing.conversationId);
 			}
 		}
+		// Late/stranded image results ride driver.run images (the redelivery
+		// prompt is text-only); user-message images ride them on ACP natively
+		// and staged files on stream-json.
+		const runImages = [...images, ...late.flatMap((l) => l.images ?? [])];
 		const fullPrompt =
-			late.length > 0
+			(late.length > 0
 				? buildLateResultPrompt(late, prompt || undefined)
-				: buildFullPrompt(sysPrompt, embeddedDigest ? "" : digest, prompt ?? "");
+				: buildFullPrompt(sysPrompt, embeddedDigest ? "" : digest, prompt ?? "")) +
+			stageImageNote(runImages);
 		try {
 			handle = await deps.driver.run({
 				cwd,
@@ -1472,7 +1534,7 @@ async function runTurnDriver(
 				inactivityMin: config.inactivityTimeoutMin,
 				conversationId: redeliveryConversation ?? existing?.conversationId ?? null,
 				prompt: fullPrompt,
-				images: images.length > 0 ? images : undefined,
+				images: runImages.length > 0 ? runImages : undefined,
 				agent,
 				contextBlock: embeddedDigest
 					? {
@@ -1569,6 +1631,7 @@ async function runTurnDriver(
 		if (more.length > 0) {
 			const conv = redeliveryConversation ?? outcome.conversationId ?? existing?.conversationId ?? null;
 			deps.log?.("escalated-redelivery-turn", { tools: more.map((s) => s.name), conversation: conv }, "info");
+			const moreImages = more.flatMap((s) => s.images ?? []);
 			try {
 				const lateHandle = await deps.driver.run({
 					cwd,
@@ -1579,7 +1642,8 @@ async function runTurnDriver(
 					timeoutMin: config.turnTimeoutMin,
 					inactivityMin: config.inactivityTimeoutMin,
 					conversationId: conv,
-					prompt: buildLateResultPrompt(more),
+					prompt: buildLateResultPrompt(more) + stageImageNote(moreImages),
+					images: moreImages.length > 0 ? moreImages : undefined,
 					agent: config.agent ?? (conv ? stagedAgentByConversation.get(conv) : undefined),
 					signal: options?.signal,
 				});
@@ -1650,6 +1714,34 @@ export function createStreamSimple(
 
 	return function streamSimple(model, context, options) {
 		const stream = createAssistantMessageEventStream();
+
+		// Short-circuit pi-observational-memory background workers.
+		// Observational memory workers declare caller-scoped tools (record_observations,
+		// record_reflections, drop_observations). Antigravity models run in a closed backend
+		// process with their own tool execution loop and do not support caller-scoped tools.
+		// If dispatched to agy, the model sees tool instructions without tools and enters
+		// an autonomous loop searching the disk for their implementation.
+		// Returning a clean stop with empty content triggers OM's empty-observer backoff,
+		// preventing high-frequency retries on subsequent turns.
+		if (isObservationalMemoryContext(context)) {
+			if (!warnedObservationalMemoryMismatch) {
+				warnedObservationalMemoryMismatch = true;
+				deps.log?.(
+					"turn-warning",
+					{
+						reason: "observational-memory-unsupported",
+						message:
+							"Observational memory background workers cannot run against Antigravity models (caller-scoped tools unsupported). Configure a dedicated model under 'observational-memory.model' in settings.json.",
+					},
+					"warn",
+				);
+			}
+			const partial = newAssistant(model);
+			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
+			finalize(stream, blocks, "stop");
+			return stream;
+		}
+
 		// Fire the async turn; return the stream synchronously per pi's contract.
 		// Engine selection: the latched load-time engine when the extension
 		// provides one, else the per-call config read (tests). One loadConfig()

package/src/queued-messages.ts

@@ -0,0 +1,171 @@
+// Settings manager for Antigravity's "Queued Messages" delivery strategy.
+//
+// In agy v1.2.14+, agy introduced the "Queued Messages" option:
+// - "queue" (agy default): hold follow-up / steering messages until current turn ends
+// - "send-immediately": interrupt the agent with follow-up / steering messages immediately
+//
+// Pi expects immediate message delivery / steering during interactive chat.
+// This module ensures that both the stream-json engine (~/.gemini/antigravity-cli/settings.json)
+// and ACP engine (~/.gemini/antigravity-acp/settings.json) default to "send-immediately"
+// so user steering works as expected in Pi without manual user configuration.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const QUEUED_MESSAGES_SEND_IMMEDIATELY = "send-immediately";
+
+export function defaultCliSettingsPath(): string {
+	return path.join(os.homedir(), ".gemini", "antigravity-cli", "settings.json");
+}
+
+export function defaultAcpSettingsPath(): string {
+	return path.join(os.homedir(), ".gemini", "antigravity-acp", "settings.json");
+}
+
+export interface EnsureFileResult {
+	path: string;
+	updated: boolean;
+	value: string;
+	error?: string;
+}
+
+export interface EnsureFileOptions {
+	defaultValue?: string;
+	onlyIfDirExists?: boolean;
+}
+
+/**
+ * Ensure `queuedMessages` is present in the specified settings.json file.
+ * If unset or empty, writes `send-immediately`.
+ *
+ * Safety guards:
+ * - If the file exists but has invalid JSON or is not an object, does NOT clobber; returns updated: false.
+ * - If the file already specifies a non-empty `queuedMessages`, leaves it untouched.
+ * - Resolves symlinks before writing to protect dotfiles managers.
+ * - Writes via temp file and atomic rename.
+ * - Traps any I/O exceptions so callers never crash on read-only or permission-denied files.
+ */
+export function ensureQueuedMessagesInFile(
+	filePath: string,
+	opts: EnsureFileOptions | string = {},
+): EnsureFileResult {
+	const options: EnsureFileOptions =
+		typeof opts === "string" ? { defaultValue: opts } : opts;
+	const defaultValue = options.defaultValue ?? QUEUED_MESSAGES_SEND_IMMEDIATELY;
+	const onlyIfDirExists = options.onlyIfDirExists ?? false;
+
+	let resolvedPath = filePath;
+	try {
+		if (fs.existsSync(filePath)) {
+			resolvedPath = fs.realpathSync(filePath);
+		}
+	} catch {
+		// Keep original path if realpath fails
+	}
+
+	const dir = path.dirname(resolvedPath);
+	if (onlyIfDirExists && !fs.existsSync(dir)) {
+		return { path: resolvedPath, updated: false, value: "" };
+	}
+
+	let settings: Record<string, unknown> = {};
+	let fileExists = false;
+
+	try {
+		const raw = fs.readFileSync(resolvedPath, "utf8");
+		fileExists = true;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(raw);
+		} catch (parseErr) {
+			// Malformed JSON: do NOT clobber the user's file.
+			return {
+				path: resolvedPath,
+				updated: false,
+				value: "",
+				error: `malformed JSON in ${resolvedPath}: ${String(parseErr)}`,
+			};
+		}
+
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return {
+				path: resolvedPath,
+				updated: false,
+				value: "",
+				error: `settings in ${resolvedPath} is not a JSON object`,
+			};
+		}
+		settings = parsed as Record<string, unknown>;
+	} catch (err: unknown) {
+		const code = (err as { code?: string })?.code;
+		if (code !== "ENOENT") {
+			// Read error other than absent file (e.g. EACCES): do not overwrite.
+			return {
+				path: resolvedPath,
+				updated: false,
+				value: "",
+				error: `failed reading ${resolvedPath}: ${String(err)}`,
+			};
+		}
+	}
+
+	const current = settings.queuedMessages;
+	if (typeof current === "string" && current.trim().length > 0) {
+		return { path: resolvedPath, updated: false, value: current };
+	}
+
+	settings.queuedMessages = defaultValue;
+
+	let tmpPath = "";
+	try {
+		fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+		tmpPath = path.join(dir, `.${path.basename(resolvedPath)}.${process.pid}.${Date.now()}.tmp`);
+		fs.writeFileSync(tmpPath, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+		fs.renameSync(tmpPath, resolvedPath);
+		return { path: resolvedPath, updated: true, value: defaultValue };
+	} catch (err) {
+		if (tmpPath) {
+			try {
+				fs.unlinkSync(tmpPath);
+			} catch {
+				/* ignore */
+			}
+		}
+		return {
+			path: resolvedPath,
+			updated: false,
+			value: "",
+			error: `failed writing ${resolvedPath}: ${String(err)}`,
+		};
+	}
+}
+
+export interface EnsureQueuedMessagesOptions {
+	cliSettingsPath?: string;
+	acpSettingsPath?: string;
+	defaultValue?: string;
+	onlyIfDirExists?: boolean;
+}
+
+export interface EnsureQueuedMessagesReport {
+	cli: EnsureFileResult;
+	acp: EnsureFileResult;
+}
+
+/**
+ * Ensure both stream-json (CLI) and ACP engines default to "send-immediately".
+ */
+export function ensureQueuedMessagesDefaults(
+	opts: EnsureQueuedMessagesOptions = {},
+): EnsureQueuedMessagesReport {
+	const cliPath = opts.cliSettingsPath ?? defaultCliSettingsPath();
+	const acpPath = opts.acpSettingsPath ?? defaultAcpSettingsPath();
+	const defVal = opts.defaultValue ?? QUEUED_MESSAGES_SEND_IMMEDIATELY;
+	const onlyIfDirExists = opts.onlyIfDirExists ?? false;
+
+	const cli = ensureQueuedMessagesInFile(cliPath, { defaultValue: defVal, onlyIfDirExists });
+	const acp = ensureQueuedMessagesInFile(acpPath, { defaultValue: defVal, onlyIfDirExists });
+
+	return { cli, acp };
+}

package/src/stream-sanitizer.ts

@@ -0,0 +1,180 @@
+// Stream Delta Sanitizer:
+// Google Antigravity injects asynchronous background task notifications into
+// the active LLM context formatted as:
+//   The following is a <SYSTEM_MESSAGE> not actually sent by the user...
+//   <SYSTEM_MESSAGE>
+//   [Message] timestamp=... sender=... content=...
+//   </SYSTEM_MESSAGE>
+//
+// Models (notably Gemini 3.8 Flash) frequently regurgitate or echo this preamble
+// verbatim as an assistant text response before proceeding with tools or answer.
+//
+// StreamSanitizer buffers and strips these blocks statefully across streaming
+// deltas so they never leak into the user's transcript.
+
+export const START_MARKER = "The following is a <SYSTEM_MESSAGE>";
+export const END_MARKER = "</SYSTEM_MESSAGE>";
+
+export const SYSTEM_MESSAGE_RE =
+	/(?:\r?\n)?The following is a <SYSTEM_MESSAGE>[\s\S]*?<\/SYSTEM_MESSAGE>(?:\r?\n)?/g;
+
+/** Non-streaming sanitization for full text strings (result bodies, parked turns, transcripts). */
+export function sanitizeSystemMessage(text: string): string {
+	if (!text) return "";
+	return text.replace(SYSTEM_MESSAGE_RE, "");
+}
+
+/** Stateful streaming sanitizer that inspects and suppresses <SYSTEM_MESSAGE> blocks across chunks. */
+export class StreamSanitizer {
+	#buffer = "";
+	#suppressing = false;
+	#suppressedAcc = "";
+	#emittedAny = false;
+
+	/**
+	 * Feed an incoming chunk of streamed text.
+	 * Returns the sanitized delta to emit downstream (empty string if suppressed or buffering).
+	 */
+	push(chunk: string): string {
+		if (!chunk) return "";
+		this.#buffer += chunk;
+		let out = "";
+
+		while (this.#buffer.length > 0) {
+			if (!this.#suppressing) {
+				const startIdx = this.#buffer.indexOf(START_MARKER);
+				if (startIdx !== -1) {
+					// There is a start marker in the buffer.
+					if (startIdx > 0) {
+						const before = this.#buffer.slice(0, startIdx);
+						if (!this.#emittedAny && before.trim() === "") {
+							// Discard leading padding before initial system message.
+						} else {
+							// Strip at most one trailing newline right before the block.
+							const trimmedBefore = before.replace(/\r?\n$/, "");
+							if (trimmedBefore.length > 0) {
+								out += trimmedBefore;
+								this.#emittedAny = true;
+							}
+						}
+					}
+					this.#buffer = this.#buffer.slice(startIdx + START_MARKER.length);
+					this.#suppressing = true;
+					this.#suppressedAcc = START_MARKER;
+					continue;
+				}
+
+				// START_MARKER is not yet in the buffer.
+				// Check if the tail of buffer matches a prefix of START_MARKER.
+				const maxOverlap = Math.min(this.#buffer.length, START_MARKER.length - 1);
+				let overlapLen = 0;
+				for (let len = maxOverlap; len > 0; len--) {
+					if (START_MARKER.startsWith(this.#buffer.slice(-len))) {
+						overlapLen = len;
+						break;
+					}
+				}
+
+				if (overlapLen > 0) {
+					const safeLen = this.#buffer.length - overlapLen;
+					if (safeLen > 0) {
+						out += this.#buffer.slice(0, safeLen);
+						this.#emittedAny = true;
+						this.#buffer = this.#buffer.slice(safeLen);
+					}
+					// Keep overlapLen in buffer to see if next chunk completes the marker.
+					break;
+				} else {
+					out += this.#buffer;
+					this.#emittedAny = true;
+					this.#buffer = "";
+					break;
+				}
+			} else {
+				// Suppressing inside <SYSTEM_MESSAGE>...</SYSTEM_MESSAGE>
+				const endIdx = this.#buffer.indexOf(END_MARKER);
+				if (endIdx !== -1) {
+					let afterEnd = endIdx + END_MARKER.length;
+					if (!this.#emittedAny) {
+						// Discard all leading newlines before the first real content.
+						while (
+							afterEnd < this.#buffer.length &&
+							(this.#buffer[afterEnd] === "\r" || this.#buffer[afterEnd] === "\n")
+						) {
+							afterEnd++;
+						}
+					} else {
+						// Consume trailing newlines after </SYSTEM_MESSAGE> to preserve paragraph spacing.
+						if (this.#buffer.startsWith("\r\n\r\n", afterEnd)) {
+							afterEnd += 4;
+						} else if (this.#buffer.startsWith("\n\n", afterEnd)) {
+							afterEnd += 2;
+						} else if (this.#buffer.startsWith("\r\n", afterEnd)) {
+							afterEnd += 2;
+						} else if (this.#buffer.startsWith("\n", afterEnd)) {
+							afterEnd += 1;
+						}
+					}
+					this.#buffer = this.#buffer.slice(afterEnd);
+					this.#suppressing = false;
+					this.#suppressedAcc = "";
+					continue;
+				}
+
+				// END_MARKER not yet encountered. Check if tail matches prefix of END_MARKER.
+				const maxOverlap = Math.min(this.#buffer.length, END_MARKER.length - 1);
+				let overlapLen = 0;
+				for (let len = maxOverlap; len > 0; len--) {
+					if (END_MARKER.startsWith(this.#buffer.slice(-len))) {
+						overlapLen = len;
+						break;
+					}
+				}
+
+				if (overlapLen > 0) {
+					this.#suppressedAcc += this.#buffer.slice(0, -overlapLen);
+					this.#buffer = this.#buffer.slice(-overlapLen);
+				} else {
+					this.#suppressedAcc += this.#buffer;
+					this.#buffer = "";
+				}
+				break;
+			}
+		}
+
+		return out;
+	}
+
+	/** Flush remaining buffered text when stream ends. */
+	flush(): string {
+		if (this.#suppressing) {
+			const unclosed = this.#suppressedAcc + this.#buffer;
+			this.#buffer = "";
+			this.#suppressedAcc = "";
+			this.#suppressing = false;
+			if (unclosed.length > 0) {
+				this.#emittedAny = true;
+			}
+			return unclosed;
+		}
+		const remaining = this.#buffer;
+		this.#buffer = "";
+		if (remaining.length > 0) {
+			this.#emittedAny = true;
+		}
+		return remaining;
+	}
+
+	/** Peek at non-suppressed buffer contents without consuming them. */
+	peek(): string {
+		return this.#suppressing ? "" : this.#buffer;
+	}
+
+	/** Reset state. */
+	reset(): void {
+		this.#buffer = "";
+		this.#suppressedAcc = "";
+		this.#suppressing = false;
+		this.#emittedAny = false;
+	}
+}