@zhuxixi/pi-agent-board 0.8.0 → 0.9.0

package/src/core/terminal-query-sequences.mjs

@@ -0,0 +1,132 @@
+/**
+ * Terminal query sequence extraction and color-scheme report mapping for the
+ * PTY attach client (issue #128).
+ *
+ * The attach client rebuilds the child screen in a headless terminal model, so
+ * the child's terminal capability queries (OSC 11 background color, color
+ * scheme change notifications) are consumed locally and never reach the real
+ * terminal. extractOscQuerySequences pulls exactly those query/notify forms
+ * out of the child output stream so the attach client can forward them to the
+ * real terminal; the replies travel back through the existing input
+ * passthrough (handleInput fallback). Setting forms (e.g. `\x1b]11;rgb:...`)
+ * are deliberately NOT extracted: forwarding those would repaint the local
+ * terminal's own colors.
+ *
+ * Kitty keyboard protocol / DA1 negotiation (`\x1b[>7u`, `\x1b[?u`, `\x1b[c`)
+ * is intentionally out of scope: the child negotiates once at spawn, before
+ * any attach client exists, and pushing kitty flags would retune the shared
+ * real-terminal keyboard stack under the local Pi's feet.
+ *
+ * Pure functions only — no I/O, no pi-tui import (the report format below is
+ * pinned by unit tests that round-trip it through pi-tui's parser).
+ */
+
+// OSC 11 background-color QUERY. The `?` payload is what makes it a query;
+// the SET form `\x1b]11;rgb:...` never matches this prefix (`;r` vs `;?`).
+const OSC11_QUERY_PREFIX = "\x1b]11;?";
+const OSC11_QUERY_BEL = OSC11_QUERY_PREFIX + "\x07";
+const OSC11_QUERY_ST = OSC11_QUERY_PREFIX + "\x1b\\";
+
+// Color-scheme change notification switch (host Pi toggles it at startup and
+// when its own setting changes; the real terminal then reports scheme changes
+// as `\x1b[?997;{1|2}n` reports). Fixed-form CSI, no variadic fields.
+const COLOR_SCHEME_NOTIFY_ON = "\x1b[?2031h";
+const COLOR_SCHEME_NOTIFY_OFF = "\x1b[?2031l";
+
+// Carry slack aligned with the extractor family in pty-attach.ts (payload cap
+// + 4096). Our longest target is 8 bytes, so 4096 is ample even for a
+// malformed no-terminator tail, and slice(-N) keeps the carry bounded.
+export const OSC_QUERY_CARRY_MAX_BYTES = 4096;
+
+const TARGETS = [OSC11_QUERY_PREFIX, COLOR_SCHEME_NOTIFY_ON, COLOR_SCHEME_NOTIFY_OFF];
+const MAX_TARGET_LENGTH = Math.max(...TARGETS.map((t) => t.length));
+
+/**
+ * Extract forwardable terminal query / notify sequences from a child output
+ * chunk. Returns the sequences (in order) and the carry: the unmatched tail
+ * to prepend to the next chunk. The carry is either a target prefix suffix
+ * (sequence split across chunks) or an unterminated OSC 11 query waiting for
+ * its BEL/ST terminator.
+ */
+export function extractOscQuerySequences(input) {
+	const sequences = [];
+	let scanFrom = 0;
+	let carryStart = -1;
+	while (scanFrom < input.length) {
+		const osc = input.indexOf(OSC11_QUERY_PREFIX, scanFrom);
+		const notifyOn = input.indexOf(COLOR_SCHEME_NOTIFY_ON, scanFrom);
+		const notifyOff = input.indexOf(COLOR_SCHEME_NOTIFY_OFF, scanFrom);
+		const start = firstIndex(firstIndex(osc, notifyOn), notifyOff);
+		if (start < 0) break;
+		if (start === osc) {
+			const after = start + OSC11_QUERY_PREFIX.length;
+			const bel = input.indexOf("\x07", after);
+			const st = input.indexOf("\x1b\\", after);
+			const end = firstTerminator(bel, st);
+			if (!end) {
+				carryStart = start;
+				break;
+			}
+			const [endIndex, terminatorLength] = end;
+			const seq = input.slice(start, endIndex + terminatorLength);
+			// Strict form: an OSC 11 query has no payload between `?` and the
+			// terminator. Anything else (e.g. `\x1b]11;?<junk>\x07`) is not a
+			// query we forward.
+			if (seq === OSC11_QUERY_BEL || seq === OSC11_QUERY_ST) sequences.push(seq);
+			scanFrom = endIndex + terminatorLength;
+		} else {
+			// Fixed-form CSI notify switch: an indexOf hit is always complete.
+			const seq = start === notifyOn ? COLOR_SCHEME_NOTIFY_ON : COLOR_SCHEME_NOTIFY_OFF;
+			sequences.push(seq);
+			scanFrom = start + seq.length;
+		}
+	}
+	const carry = carryStart >= 0
+		? input.slice(carryStart).slice(-OSC_QUERY_CARRY_MAX_BYTES)
+		: queryPrefixSuffix(input);
+	return { sequences, carry };
+}
+
+/**
+ * Longest suffix of `input` that is a strict prefix of one of our target
+ * sequences (empty when none matches). Used as the carry when every target
+ * occurrence in this chunk was complete.
+ */
+function queryPrefixSuffix(input) {
+	const max = Math.min(input.length, MAX_TARGET_LENGTH - 1);
+	for (let len = max; len > 0; len--) {
+		const suffix = input.slice(-len);
+		if (TARGETS.some((t) => t.startsWith(suffix))) return suffix;
+	}
+	return "";
+}
+
+function firstIndex(a, b) {
+	if (a < 0) return b;
+	if (b < 0) return a;
+	return Math.min(a, b);
+}
+
+function firstTerminator(bel, st) {
+	if (bel < 0 && st < 0) return null;
+	if (bel >= 0 && (st < 0 || bel < st)) return [bel, 1];
+	return [st, 2];
+}
+
+// Color-scheme report expected by pi-tui's parseTerminalColorSchemeReport
+// (node_modules/@earendil-works/pi-tui/dist/terminal-colors.js:19):
+// /^\x1b\[\?997;(1|2)n$/ with "2" => light, "1" => dark (line 57). Note the
+// report code point is 997 — the QUERY the host sends is `\x1b[?996n`.
+const COLOR_SCHEME_REPORTS = {
+	light: "\x1b[?997;2n",
+	dark: "\x1b[?997;1n",
+};
+
+/**
+ * Map a color scheme ("light" | "dark") to the report sequence the host Pi's
+ * pi-tui parser consumes. Returns "" for anything else; callers skip sending
+ * on empty.
+ */
+export function toColorSchemeReport(scheme) {
+	return Object.hasOwn(COLOR_SCHEME_REPORTS, scheme) ? COLOR_SCHEME_REPORTS[scheme] : "";
+}

package/src/ui/dashboard.ts

@@ -14,6 +14,7 @@ import { requestDashboardRender } from "../core/dashboard-render.mjs";
 import { normalizeGenericStatusText } from "../core/derive.mjs";
 import { firstSentence, truncate } from "../core/heuristics.mjs";
 import {
+	browseTabCompletion,
 	canonicalModelRef,
 	clampThinkingLevel,
 	listDirectorySuggestions,
@@ -596,13 +597,24 @@ export class DashboardComponent implements Component {
 			return;
 		}
 		if (launch.picker === "cwd" && matchesKey(data, Key.tab)) {
-			if (launch.cwdPickerMode === "favorites" && launch.cwdSuggestions.length > 0) {
-				const completed = launch.cwdSuggestions[launch.cwdSuggestionIndex] ?? launch.cwdSuggestions[0];
-				launch.cwdQuery = completed;
-				const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
-				launch.cwdPickerMode = state.mode;
-				launch.cwdSuggestions = state.suggestions;
-				launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completed));
+			if (launch.cwdSuggestions.length > 0) {
+				if (launch.cwdPickerMode === "browse") {
+					const completion = browseTabCompletion(launch.cwdQuery, launch.cwdSuggestions, launch.cwdSuggestionIndex);
+					if (completion) {
+						launch.cwdQuery = completion.query;
+						const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+						launch.cwdPickerMode = state.mode;
+						launch.cwdSuggestions = state.suggestions;
+						launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completion.completed));
+					}
+				} else {
+					const completed = launch.cwdSuggestions[launch.cwdSuggestionIndex] ?? launch.cwdSuggestions[0];
+					launch.cwdQuery = completed;
+					const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+					launch.cwdPickerMode = state.mode;
+					launch.cwdSuggestions = state.suggestions;
+					launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completed));
+				}
 			}
 			return;
 		}
@@ -1583,7 +1595,7 @@ export class DashboardComponent implements Component {
 			} else {
 				lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => displayPath(value)));
 				lines.push("");
-				lines.push(t.fg("dim", "type to filter folders · enter choose · esc back"));
+				lines.push(t.fg("dim", "type to filter folders · tab complete · enter choose · esc back"));
 			}
 		} else if (launch.picker === "model") {
 			lines.push(t.fg("warning", `model› ${singleLineInput(launch.modelQuery)}${cursor()}`));

package/src/ui/pty-attach.ts

@@ -11,6 +11,7 @@ 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 { extractOscQuerySequences, toColorSchemeReport } from "../core/terminal-query-sequences.mjs";
 import { clampInt, parseMouseInputChunk, resolveWheelLines, scrollViewportTop, selectionDragScrollLines } from "../core/pty-scroll.mjs";
 
 export type PtyAttachResult = { action: "detached" } | { action: "closed"; exitCode?: number | null };
@@ -170,6 +171,7 @@ export class PtyAttachComponent implements Component {
 	private jiggleStartTimer: ReturnType<typeof setTimeout> | null = null;
 	private osc52Carry = "";
 	private passthroughCarry = "";
+	private oscQueryCarry = "";
 	private readonly connectStartedAt = Date.now();
 	// Set once the first socket connect succeeds; drives the reconnect give-up
 	// policy (short window after a live session dies, long window during cold
@@ -214,6 +216,10 @@ export class PtyAttachComponent implements Component {
 	private attaching = true;
 	private attachSettleTimer: ReturnType<typeof setTimeout> | null = null;
 	private attachHardTimeout: ReturnType<typeof setTimeout> | 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.
+	private colorSchemeBridgeUnsubscribe: (() => void) | null = null;
 	private gracefulSocketCloseTimer: ReturnType<typeof setTimeout> | null = null;
 	// Force a single full-clear on the first paint so the prior session/dashboard can't
 	// ghost behind this overlay; every later paint uses the TUI's coalesced, throttled,
@@ -287,6 +293,18 @@ export class PtyAttachComponent implements Component {
 			this.send({ type: "input", data });
 			return;
 		}
+		if (matchesKey(data, "ctrl+\\")) {
+			// Unconditional, terminal-independent escape (issue #126): 0x1c is a
+			// single raw ASCII byte every terminal forwards unchanged in raw
+			// mode — no modifier-encoding dependency like Ctrl+Left (macOS
+			// Terminal.app never emits it, WezTerm consumes it for tab
+			// switching). Only caveat (documented in README): layouts where
+			// `\` sits on AltGr may never produce this byte; the escape ladder
+			// still covers those. matchesKey also covers the kitty CSI-u and
+			// modifyOtherKeys encodings of the same chord.
+			this.detach();
+			return;
+		}
 		if (matchesKey(data, Key.ctrl("left"))) {
 			// Explicit detach chord (issue #89): single ← is gated on editor state
 			// (it doubles as cursor-left inside a non-empty draft), so a user with
@@ -340,7 +358,7 @@ export class PtyAttachComponent implements Component {
 		}
 		const header =
 			this.theme.fg("accent", this.theme.bold(` ${this.opts.title} `)) +
-			this.theme.fg("muted", `${this.status} · click opens links · dblclick/drag selects+copies · Ctrl+← detach`);
+			this.theme.fg("muted", `${this.status} · opens links · drag selects+copies · Ctrl+←/Ctrl+\\ detach`);
 		return [clip(header, width), ...body.map((l) => clipTerminalLine(l, width)), this.theme.fg("dim", "─".repeat(width))];
 	}
 
@@ -356,7 +374,7 @@ export class PtyAttachComponent implements Component {
 		out.push(center(this.theme.fg("accent", this.theme.bold(title)), width));
 		out.push(center(this.theme.fg("muted", detail), width));
 		out.push("");
-		out.push(center(this.theme.fg("dim", "Ctrl+← to detach"), width));
+		out.push(center(this.theme.fg("dim", "Ctrl+←/Ctrl+\\ to detach"), width));
 		while (out.length < height) out.push("");
 		return out.slice(0, height);
 	}
@@ -568,6 +586,56 @@ export class PtyAttachComponent implements Component {
 		// buffer, instead of diffing banner lines into buffer lines.
 		this.scheduleRender(true);
 		this.startDesyncProbe();
+		// Issue #128: the settle transition is the single point where `attaching`
+		// flips false (never re-armed), so both hooks run at most once per attach.
+		this.attachColorSchemeBridge();
+		this.replayBackgroundQuery();
+	}
+
+	/** Issue #128 D2: the local pi-tui consumes the child's color-scheme
+	 * traffic (996 queries / 2031 notifications forwarded by D1) — reports
+	 * never reach the child. onTerminalColorSchemeChange fires from that same
+	 * consumption point, so the bridge repackages each event as a 997 report
+	 * on the child pty, where the child's pi-tui parser consumes it. Once per
+	 * attach (settle is single-shot + explicit guard); kill switch skips it. */
+	private attachColorSchemeBridge(): void {
+		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES === "0") return;
+		if (this.colorSchemeBridgeUnsubscribe) return;
+		try {
+			this.colorSchemeBridgeUnsubscribe = this.tui.onTerminalColorSchemeChange((scheme) => {
+				const data = toColorSchemeReport(scheme);
+				if (data) this.send({ type: "input", data });
+			});
+		} catch {
+			/* best-effort: an unbridgeable TUI keeps pre-#128 behavior */
+		}
+	}
+
+	/** Called on every terminal path (close() covers detach/dispose; the exit
+	 * branch calls done() without close(), so it unsubscribes explicitly). */
+	private detachColorSchemeBridge(): void {
+		const unsubscribe = this.colorSchemeBridgeUnsubscribe;
+		this.colorSchemeBridgeUnsubscribe = null;
+		if (!unsubscribe) return;
+		try {
+			unsubscribe();
+		} catch {
+			/* best-effort: a stale listener must not block teardown */
+		}
+	}
+
+	/** 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 */
+		}
 	}
 
 	private startDesyncProbe(): void {
@@ -1117,6 +1185,10 @@ export class PtyAttachComponent implements Component {
 					this.editorEmpty = typeof msg.empty === "boolean" ? msg.empty : null;
 				} else if (msg.type === "exit") {
 					this.status = "host exited";
+					// The exit path calls done() directly (host disposes later);
+					// drop the #128 bridge now so A7 symmetry doesn't depend on
+					// the host honoring dispose().
+					this.detachColorSchemeBridge();
 					this.done({ action: "closed", exitCode: msg.exitCode ?? null });
 				} else if (msg.type === "error") this.status = `error: ${msg.message ?? "host error"}`;
 				if (shouldScheduleAttachRenderForMessage(msg.type)) needsRender = true;
@@ -1228,6 +1300,15 @@ export class PtyAttachComponent implements Component {
 			this.passthroughCarry = carry;
 			toWrite.push(...sequences);
 		}
+		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES !== "0") {
+			// Issue #128 D1: forward the child's terminal capability queries
+			// (OSC 11 background probe, 2031 scheme-notify switch) to the real
+			// terminal; set-forms and kitty/DA negotiation stay excluded (see
+			// extractOscQuerySequences).
+			const { sequences, carry } = extractOscQuerySequences(this.oscQueryCarry + data);
+			this.oscQueryCarry = carry;
+			toWrite.push(...sequences);
+		}
 		for (const seq of toWrite) {
 			try {
 				this.tui.terminal.write(seq);
@@ -1322,6 +1403,7 @@ export class PtyAttachComponent implements Component {
 		}
 		this.closed = true;
 		this.imeCoalesceUninstall?.();
+		this.detachColorSchemeBridge();
 		this.attachClient.close();
 		this.jiggleRetry.restoreAndStop();
 		this.disableMouseScroll();