@zhuxixi/pi-agent-board 0.10.0 → 0.10.2

package/src/ui/pty-attach.ts

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
 import { createConnection, type Socket } from "node:net";
-import type { Component, KeybindingsManager, RgbColor, TUI, TerminalColorScheme } from "@earendil-works/pi-tui";
+import type { Component, KeybindingsManager, RgbColor, TUI, TerminalColorScheme, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { CURSOR_MARKER, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { findHttpUrlAtCells, findWordRangeAtCells } from "../core/pty-links.mjs";
 import { createAttachOutputRenderScheduler, detectCursorDesync, isPtyCursorHidden, nextAttachRender, projectPtyCursor, shouldScheduleAttachRenderForMessage } from "../core/pty-attach-render.mjs";
@@ -11,8 +11,8 @@ import { evaluateAttachReconnect, shouldEscapeAttach } from "../core/pty-attach-
 import { installImeCursorCoalesce } from "../core/ime-cursor-coalesce.mjs";
 import { createJiggleRetryController } from "../core/pty-attach-jiggle-controller.mjs";
 import { createTerminalAttachClient } from "../core/terminal-attach-client.mjs";
-import { colorSchemeForBackgroundRgb, extractOscQuerySequences, toColorSchemeReport } from "../core/terminal-query-sequences.mjs";
-import { clampInt, parseMouseInputChunk, resolveWheelLines, scrollViewportTop, selectionDragScrollLines } from "../core/pty-scroll.mjs";
+import { backgroundRgbFromTerminalColors, buildSettleSchemePatch, colorSchemeForBackgroundRgb, extractOscQuerySequences, resolveProbeApi, toColorSchemeReport } from "../core/terminal-query-sequences.mjs";
+import { clampInt, parseMouseInputChunk, resolveAttachMouseAction, resolveWheelLines, scrollViewportTop, selectionDragScrollLines, shouldOwnOuterMouseMode } from "../core/pty-scroll.mjs";
 
 export type PtyAttachResult = { action: "detached" } | { action: "closed"; exitCode?: number | null };
 
@@ -21,10 +21,21 @@ type ThemeLike = {
 	bold(text: string): string;
 };
 
+/** Diagnostic patch emitted at attach settle (DiagnosticEvent-compatible; built by buildSettleSchemePatch). */
+export interface AttachSettleDiagnosticPatch {
+	source: string;
+	level: "info" | "warn";
+	code: string;
+	message: string;
+	details: { probeApi?: string; outcome: string; report?: string; late?: boolean };
+}
+
 export interface PtyAttachOptions {
 	socketPath: string;
 	screenLogPath?: string;
 	title: string;
+	/** Issue #161: receives settle-scheme diagnostic patches. Default: no-op. */
+	onDiagnostic?: (event: AttachSettleDiagnosticPatch) => void;
 }
 
 const require = createRequire(import.meta.url);
@@ -113,6 +124,7 @@ interface BufferLineLike {
 interface BufferCellLike {
 	getWidth(): number;
 	getChars(): string;
+	hasExtendedAttrs(): number;
 	extended?: { urlId?: number; _urlId?: number };
 	getFgColor(): number;
 	getBgColor(): number;
@@ -224,6 +236,10 @@ export class PtyAttachComponent implements Component {
 	private attaching = true;
 	private attachSettleTimer: ReturnType<typeof setTimeout> | null = null;
 	private attachHardTimeout: ReturnType<typeof setTimeout> | null = null;
+	// Last scheme delivered to the child at settle (issue #161). Starts null:
+	// null never matches the duplicate check, so a timeout-then-late sequence
+	// still delivers. Single-shot per attach — settle runs at most once.
+	private sentScheme: TerminalColorScheme | null = null;
 	// Issue #128 D2: unsubscriber for the color-scheme bridge registered at
 	// attach settle; nulled on every terminal path so the TUI never keeps a
 	// listener pointing at a dead attach surface.
@@ -352,6 +368,22 @@ export class PtyAttachComponent implements Component {
 		this.send({ type: "input", data });
 	}
 
+	/** Issue #167: fullscreen TUI (pi ≥1.0) consumes raw SGR mouse sequences in
+	 * TuiAltScreen and delivers normalized events to overlays here instead — the
+	 * legacy handleInput mouse path never runs in that mode. Only the
+	 * middle-click paste is ours; every other event returns undefined so pi's
+	 * own fullscreen selection and the wheel defer path keep working. */
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		const action = resolveAttachMouseAction(event, {
+			nativePasteEnabled: process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0",
+		});
+		if (action !== "paste-primary") return undefined;
+		this.clearPendingClick();
+		this.clearSelection();
+		this.pastePrimarySelection();
+		return { handled: true, render: false };
+	}
+
 	render(width: number): string[] {
 		this.resizeIfNeeded(width);
 		const height = this.tui.terminal?.rows ?? 24;
@@ -597,7 +629,10 @@ export class PtyAttachComponent implements Component {
 		// Issue #128: the settle transition is the single point where `attaching`
 		// flips false (never re-armed), so these hooks run at most once per attach.
 		this.attachColorSchemeBridge();
-		this.replayBackgroundQuery();
+		// Use only the tracked TUI probe. An extra terminal.write(OSC 11) has
+		// no local query owner, so its reply falls through handleInput into the
+		// child PTY. Settle can precede the child's raw-mode startup, making
+		// the line discipline echo that reply as visible ^[]11;rgb:... text.
 		this.reportRealTerminalColorScheme();
 	}
 
@@ -633,52 +668,89 @@ export class PtyAttachComponent implements Component {
 		}
 	}
 
-	/** Issue #128 D3: the child probed OSC 11 at spawn, before any attach
-	 * client existed, so its background-color answer was lost. Re-ask the REAL
-	 * terminal once now; the reply travels back through the existing input
-	 * passthrough (handleInput fallback) to the child. Silent on failure — a
-	 * missing answer keeps the pre-#128 fallback theme. */
-	private replayBackgroundQuery(): void {
-		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES === "0") return;
-		try {
-			this.tui.terminal.write("\x1b]11;?\x07");
-		} catch {
-			/* best-effort: enhancement, never critical */
-		}
-	}
-
-	/** Issue #148: #128's replay only helps while the child still has a PENDING
-	 * OSC 11 query. That precondition does not hold here: the child's probe fires
-	 * at spawn (long before attach), and Pi's leaked pending state — a timeout
-	 * settles the query but leaves it queued and keeps the reply counter up —
-	 * makes the next arriving reply get consumed by that stale entry and
-	 * discarded, resolving nothing. So the client stops relying on the child's
-	 * probe entirely: it asks the REAL terminal itself (pi-tui's public query API)
-	 * and hands the child a 997 color-scheme report, which Pi consumes
-	 * unconditionally (no pending-query precondition — see
-	 * consumeTerminalColorSchemeReport). Same kill switch as #128 D1-D3.
-	 *
-	 * One probe only (CR round-1 advisory): the local pi-tui has the same leak, so
-	 * when a stale entry sits in ITS queue the reply is swallowed before this
-	 * promise can see it, and retrying would append another stale entry per
-	 * attempt — failing identically while poisoning the host's own detection. The
-	 * degraded case stays the documented pre-#148 silence. */
+	/** Issue #148/#161: at settle, ask the REAL terminal itself (feature-detected
+	 * public query API — pi-tui >= 0.99 renamed it to queryTerminalColors) and
+	 * hand the child an unconditional 997 color-scheme report. One probe per
+	 * attach; the pre-#148 silence on failure is now observable via
+	 * onDiagnostic. Same kill switch as #128 D1-D3. */
 	private reportRealTerminalColorScheme(): void {
-		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES === "0") return;
+		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES === "0") {
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ outcome: "suppressed" }));
+			return;
+		}
 		void this.probeAndReportRealTerminalColorScheme();
 	}
 
 	private async probeAndReportRealTerminalColorScheme(): Promise<void> {
-		let rgb: RgbColor | undefined;
+		const probe = resolveProbeApi(this.tui as never);
+		if (probe.api === "none") {
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: "none", outcome: "no_probe_api" }));
+			return;
+		}
+		let result: { rgb?: RgbColor; anyColors: boolean };
 		try {
-			rgb = await this.tui.queryTerminalBackgroundColor({ timeoutMs: REAL_TERMINAL_SCHEME_PROBE_TIMEOUT_MS });
+			result = await probe.invoke(
+				this.tui as never,
+				REAL_TERMINAL_SCHEME_PROBE_TIMEOUT_MS,
+				(colors) => this.handleLateSettleColors(probe.api, colors),
+			);
 		} catch {
-			/* best-effort: a failed probe keeps the pre-#148 behavior */
+			/* best-effort: a failed probe keeps the pre-#148 behavior, but recorded */
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: probe.api, outcome: "error" }));
+			return;
+		}
+		const rgb = result?.rgb;
+		if (!rgb) {
+			// Outcome rule (spec §2.3): any color answered but no background =>
+			// no_background; nothing answered at all => timeout. The old API only
+			// queries OSC 11, so its undefined is always a timeout.
+			const outcome = result && result.anyColors ? "no_background" : "timeout";
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: probe.api, outcome }));
+			return;
+		}
+		this.deliverSettleScheme(colorSchemeForBackgroundRgb(rgb) ?? undefined, probe.api, false);
+	}
+
+	/** pi-tui >= 0.99 late replies: deliver only when the scheme differs from
+	 * what was already sent (sentScheme starts null and never matches, so the
+	 * timeout-then-late path delivers). Closed => dropped, but recorded. */
+	private handleLateSettleColors(api: "colors" | "background" | "none", colors: unknown): void {
+		if (this.closed) {
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: api, outcome: "dropped_closed" }));
+			return;
+		}
+		const rgb = backgroundRgbFromTerminalColors(colors as never);
+		const scheme = rgb ? colorSchemeForBackgroundRgb(rgb) ?? undefined : undefined;
+		if (!scheme) return;
+		if (this.sentScheme === scheme) {
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: api, outcome: "duplicate_skipped" }));
+			return;
 		}
-		const scheme: TerminalColorScheme | undefined = colorSchemeForBackgroundRgb(rgb) ?? undefined;
+		this.deliverSettleScheme(scheme, api, true);
+	}
+
+	private deliverSettleScheme(scheme: TerminalColorScheme | undefined, api: "colors" | "background" | "none", late: boolean): void {
 		if (!scheme || this.closed) return;
 		const data = toColorSchemeReport(scheme);
-		if (data) this.send({ type: "input", data });
+		if (!data) return;
+		// CR round-1 advisory: send() silently no-ops while the control socket is
+		// disconnected (hard-timeout settle before the host finished connecting).
+		// Claiming "reported" there would be a lie the dedup then acts on, so
+		// record the drop and leave sentScheme unset — a later same-scheme late
+		// reply re-attempts instead of being swallowed as duplicate_skipped.
+		if (!this.connected) {
+			this.opts.onDiagnostic?.(buildSettleSchemePatch({ probeApi: api, outcome: "dropped_disconnected" }));
+			return;
+		}
+		this.sentScheme = scheme;
+		this.send({ type: "input", data });
+		const details: { probeApi: "colors" | "background" | "none"; outcome: "reported"; report: string; late?: boolean } = {
+			probeApi: api,
+			outcome: "reported",
+			report: scheme === "light" ? "997;2" : "997;1",
+		};
+		if (late) details.late = true;
+		this.opts.onDiagnostic?.(buildSettleSchemePatch(details));
 	}
 
 	private startDesyncProbe(): void {
@@ -778,7 +850,7 @@ export class PtyAttachComponent implements Component {
 	}
 
 	private enableMouseScroll(): void {
-		if (!this.mouseScrollEnabled()) return;
+		if (!this.ownsOuterMouseMode()) return;
 		try {
 			this.tui.terminal.write(XTSHIFTESCAPE_SELECT);
 			this.tui.terminal.write(MOUSE_ENABLE);
@@ -787,6 +859,15 @@ export class PtyAttachComponent implements Component {
 		}
 	}
 
+	/** Issue #169: in fullscreen mode TuiAltScreen owns outer-terminal mouse
+	 * reporting (asserted once at startup, never re-asserted) — writing any
+	 * mouse-mode sequence from here can only downgrade or kill it. tui.mode is
+	 * typed non-optional but old pi runtimes lack it; the strict inequality
+	 * then keeps today's (regular) behavior. */
+	private ownsOuterMouseMode(): boolean {
+		return shouldOwnOuterMouseMode(this.tui.mode, this.mouseScrollEnabled());
+	}
+
 	private mouseScrollEnabled(): boolean {
 		const mode = (process.env.AGENT_BOARD_ATTACH_MOUSE ?? "").trim().toLowerCase();
 		if (mode === "0" || mode === "off" || mode === "false") return false;
@@ -808,6 +889,7 @@ export class PtyAttachComponent implements Component {
 	}
 
 	private disableMouseScroll(): void {
+		if (!this.ownsOuterMouseMode()) return;
 		try {
 			this.tui.terminal.write(MOUSE_DISABLE);
 		} catch {
@@ -1688,6 +1770,8 @@ function clipTerminalLine(line: string, width: number): string {
 }
 
 function osc8UriForCell(term: XtermLike, cell: BufferCellLike): string {
+	// xterm leaves cached extended data on reused cells when this flag is unset.
+	if (!cell.hasExtendedAttrs()) return "";
 	const id = cell.extended?.urlId ?? cell.extended?._urlId ?? 0;
 	if (!id) return "";
 	const service = term._core?._oscLinkService;