@zhuxixi/pi-agent-board 0.7.0 → 0.9.0

package/src/core/terminal-attach-protocol.mjs

@@ -0,0 +1,252 @@
+import { ringChunksAfter } from "./terminal-model.mjs";
+import {
+	captureTerminalSnapshot,
+	synthesizeFullRedrawFrame,
+	TERMINAL_SNAPSHOT_VERSION,
+} from "./terminal-snapshot.mjs";
+
+/**
+ * Capture-and-subscribe protocol for one attach socket (issue #91, D2 phase 3).
+ *
+ * Pure state machine: no sockets, no fs — `send` is injected and the runner
+ * feeds `onOutput` for every chunk it broadcasts. Correctness rests on two
+ * invariants:
+ *
+ * 1. Snapshot capture is async (parser idle wait), but output keeps flowing.
+ *    Chunks fed during capture are retained in the model ring; the catch-up
+ *    flush after the frame replays exactly the chunks past `dto.snapshotSeq`.
+ *    The ring therefore IS the gap buffer — nothing is buffered twice.
+ * 2. Delivery order per socket is gap-free and duplicate-free: live output is
+ *    only forwarded when `seq === lastSeq + 1`; any discontinuity downgrades
+ *    the socket to `resnapshot_required` instead of stitching (spec: never
+ *    recover from a partial tail).
+ *
+ * Ownership contract (runner seam): once a socket speaks `subscribe_terminal`,
+ * its output stream is owned by this state machine — the runner must exclude it
+ * from the legacy fire-and-forget output broadcast (`subscribed()` is the
+ * sticky marker for that exclusion). Delivering both streams would duplicate
+ * every chunk.
+ */
+
+/**
+ * Wire frame version axis: the synthesized full-redraw frame format carried in
+ * `snapshot_frame` payloads (Route B). Clients advertising a different
+ * `frameVersion` on `subscribe_terminal` are rejected — the wire contract must
+ * match exactly; there is no negotiated degradation inside this protocol.
+ *
+ * This axis is independent from {@link TERMINAL_SNAPSHOT_VERSION} (the DTO
+ * capture format, an internal artifact that never crosses the wire in Route B).
+ */
+export const TERMINAL_FRAME_VERSION = 1;
+
+export { TERMINAL_SNAPSHOT_VERSION };
+
+/**
+ * @typedef {ReturnType<typeof createTerminalSubscription>} TerminalSubscription
+ */
+
+/**
+ * Create the per-socket terminal subscription state.
+ *
+ * @param {{
+ *   model: import("./terminal-model.mjs").TerminalModel,
+ *   send: (msg: Record<string, unknown>) => void,
+ * }} opts
+ */
+export function createTerminalSubscription({ model, send: rawSend, generation }) {
+	/** @type {"idle" | "capturing" | "live"} */
+	let state = "idle";
+	let lastSeq = 0;
+	// Sticky protocol-ownership marker: set the moment a socket speaks
+	// subscribe_terminal, never reset (not even by gap downgrade or snapshot
+	// failure). The runner excludes subscribed sockets from the legacy output
+	// broadcast; delivery then belongs to this state machine alone.
+	let subscribed = false;
+
+	// Choke-point guard (CR R1 blocking): every protocol write funnels through
+	// this wrapper, so a synchronous socket.write throw can never escape into
+	// the runner's uncaughtException crash path (a runner crash kills the
+	// hosted child). Pinned semantics (tested): a send-throw is treated like
+	// socket death — the subscription downgrades to "idle" silently, further
+	// sends are swallowed no-ops, live fan-out stops, and the runner's socket
+	// error/close handler owns the actual cleanup. "live" transitions are
+	// gated on sendBroken so a throw mid-replay or mid-snapshot cannot
+	// resurrect a dead socket into live state.
+	let sendBroken = false;
+	const send = (msg) => {
+		if (sendBroken) return;
+		try {
+			rawSend(msg);
+		} catch {
+			sendBroken = true;
+			state = "idle";
+		}
+	};
+
+	const fail = (code, extra = {}) => {
+		send({ type: "error", code, ...extra });
+	};
+
+	/**
+	 * Fresh-snapshot path (first subscribe or unrecoverable cursor). Frame
+	 * metadata comes from the captured DTO, so a resize racing the async
+	 * capture cannot produce a half-old header.
+	 * @param {{ resnapshot?: boolean }} [marks]
+	 */
+	async function startSnapshot({ resnapshot = false } = {}) {
+		state = "capturing";
+		try {
+			const empty = model.lastSeq === 0;
+			const begin = /** @type {Record<string, unknown>} */ ({
+				type: "snapshot_begin",
+				snapshotSeq: 0,
+				cols: model.cols,
+				rows: model.rows,
+				frameVersion: TERMINAL_FRAME_VERSION,
+				// Runner boot identity (issue #91 phase 5): lets a reconnecting
+				// client detect a runner replacement from the snapshot answer alone.
+				...(generation ? { generation } : {}),
+			});
+			if (empty) {
+				// Runner (re)started and the new child has produced no output yet:
+				// the "host starting" baseline. No frame; live output starts at seq 1.
+				// The resnapshot marker applies here too: a client presenting a stale
+				// cursor must discard its local buffer either way (whole-branch review:
+				// marker contract must be consistent across resnapshot paths).
+				begin.empty = true;
+				if (resnapshot) begin.resnapshot = true;
+				send(begin);
+				lastSeq = 0;
+				send({ type: "snapshot_end", nextSeq: lastSeq + 1 });
+				if (!sendBroken) state = "live";
+				return;
+			}
+			const dto = await captureTerminalSnapshot(model);
+			begin.snapshotSeq = dto.snapshotSeq;
+			begin.cols = dto.cols;
+			begin.rows = dto.rows;
+			if (resnapshot) begin.resnapshot = true;
+			send(begin);
+			send({
+				type: "snapshot_frame",
+				frameVersion: TERMINAL_FRAME_VERSION,
+				data: await synthesizeFullRedrawFrame(dto),
+			});
+			// Catch-up flush: chunks fed while the capture was in flight (they are
+			// already part of the parser state past dto.snapshotSeq, so replaying
+			// the ring past that cursor is exact — no gap, no duplicate).
+			const after = ringChunksAfter(model, dto.snapshotSeq);
+			if (after.evicted) {
+				// Ring pressure during capture: refuse to stitch, ask for a redo.
+				state = "idle";
+				send({ type: "resnapshot_required", lastSeq, missing: dto.snapshotSeq + 1 });
+				return;
+			}
+			for (const chunk of after.chunks) {
+				send({ type: "output", seq: chunk.seq, data: chunk.data });
+				lastSeq = chunk.seq;
+			}
+			if (after.chunks.length === 0) lastSeq = dto.snapshotSeq;
+			send({ type: "snapshot_end", nextSeq: lastSeq + 1 });
+			if (!sendBroken) state = "live";
+		} catch (err) {
+			state = "idle";
+			fail("snapshot_failed", { message: err instanceof Error ? err.message : String(err) });
+		}
+	}
+
+	/**
+	 * Reconnect path with a still-retained cursor. Fully synchronous: the ring
+	 * read and the replay writes cannot interleave with feedOutput, so the
+	 * subscription lands in live state with lastSeq === model.lastSeq.
+	 * @param {number} sinceSeq
+	 */
+	function startReplay(sinceSeq) {
+		const after = ringChunksAfter(model, sinceSeq);
+		for (const chunk of after.chunks) {
+			send({ type: "output", seq: chunk.seq, data: chunk.data });
+		}
+		lastSeq = model.lastSeq;
+		if (!sendBroken) state = "live";
+	}
+
+	/**
+	 * Handle one client→runner terminal message. Returns true when consumed.
+	 *
+	 * `subscribe_terminal` is the only message of this protocol. Defensive
+	 * frameVersion gate: a client that carries a `frameVersion` we do not emit
+	 * is rejected up front instead of receiving a frame it cannot parse.
+	 *
+	 * @param {any} msg
+	 * @returns {boolean}
+	 */
+	function handleMessage(msg) {
+		if (!msg || msg.type !== "subscribe_terminal") return false;
+		// Every subscribe_terminal speaker is protocol-managed from here on,
+		// including rejected ones (frameVersion mismatch, invalid cursor): the
+		// legacy broadcast stream must never interleave with this protocol.
+		subscribed = true;
+		if (msg.frameVersion !== undefined && msg.frameVersion !== TERMINAL_FRAME_VERSION) {
+			fail("frame_version_mismatch", { supported: TERMINAL_FRAME_VERSION, received: msg.frameVersion });
+			return true;
+		}
+		if (
+			msg.sinceSeq !== undefined &&
+			(!Number.isInteger(msg.sinceSeq) || msg.sinceSeq < 0)
+		) {
+			fail("invalid_since_seq", { sinceSeq: msg.sinceSeq });
+			return true;
+		}
+		if (state === "capturing") return true; // snapshot already in flight; ignore duplicates
+		if (msg.sinceSeq === undefined) {
+			// .catch belt-and-braces (CR R1): the snapshot flow already funnels
+			// failures into fail() — which is now throw-safe via the choke point —
+			// but a stray rejection must never surface as an unhandledRejection
+			// crash (the runner treats that as fatal).
+			void startSnapshot().catch(() => {});
+		} else if (msg.sinceSeq > model.lastSeq || msg.sinceSeq < model.evictedThrough) {
+			// Client ahead of the runner (foreign cursor) or needs an evicted
+			// range: both mean "no shared baseline" — fresh snapshot, marked so
+			// the client discards its local buffer first.
+			void startSnapshot({ resnapshot: true }).catch(() => {});
+		} else {
+			// Ring invariant: (evictedThrough, lastSeq] is always contiguous, so
+			// sinceSeq === evictedThrough is a COMPLETE replay, not a partial tail.
+			startReplay(msg.sinceSeq);
+		}
+		return true;
+	}
+
+	/**
+	 * Live fan-out for one chunk. Called by the runner for every chunk it
+	 * broadcasts, in feed order. No-op while a snapshot is in flight (the
+	 * catch-up flush owns delivery for that window).
+	 *
+	 * @param {number} seq
+	 * @param {string} data
+	 */
+	function onOutput(seq, data) {
+		if (state !== "live") return;
+		if (seq === lastSeq + 1) {
+			lastSeq = seq;
+			send({ type: "output", seq, data });
+			return;
+		}
+		// Gap: never skip silently, never fabricate. One marker, then the client
+		// must re-subscribe (fresh snapshot or replay from its real cursor).
+		state = "idle";
+		send({ type: "resnapshot_required", lastSeq, missing: seq });
+	}
+
+	return {
+		handleMessage,
+		onOutput,
+		/** Sticky: true once the socket sent subscribe_terminal. The runner uses
+		 *  this to keep the socket out of the legacy output broadcast. */
+		subscribed: () => subscribed,
+		/** Socket went away; the runner drops its reference. */
+		detach() {
+			state = "idle";
+		},
+	};
+}

package/src/core/terminal-model.mjs

@@ -0,0 +1,222 @@
+import xtermHeadless from "@xterm/headless";
+
+// @xterm/headless is CommonJS; named import from ESM fails, so destructure.
+const { Terminal } = /** @type {any} */ (xtermHeadless);
+
+/**
+ * Canonical terminal model for one hosted view (issue #91, D2/D5).
+ *
+ * The PTY runner owns one model per host: every child output chunk is assigned a
+ * strictly increasing `outputSeq`, fed to a real terminal state machine
+ * (@xterm/headless by default), and retained in a bounded in-memory ring so a
+ * late subscriber can replay chunks after a snapshot cursor. This module is the
+ * pure-ish core: no fs, no sockets — the runner wires it into `child.onData`.
+ *
+ * The canonical state lives for the runner's lifetime only; it is never
+ * persisted across runner restarts (runner death kills the child; a new child
+ * establishes a fresh baseline).
+ */
+
+/** Default ring retention: chunk count cap. */
+export const DEFAULT_RING_CHUNK_CAP = 2048;
+/** Default ring retention: total buffered bytes cap (4 MiB). */
+export const DEFAULT_RING_BYTE_CAP = 4 * 1024 * 1024;
+
+/**
+ * Default parser factory. `write(data, cb)` callbacks are supported by
+ * @xterm/headless v6 and fire after the chunk is fully parsed, which makes
+ * `whenIdle` deterministic without polling.
+ *
+ * @param {{ cols: number, rows: number, scrollback: number }} opts
+ */
+export function defaultParserFactory({ cols, rows, scrollback }) {
+	return new Terminal({ cols, rows, scrollback, allowProposedApi: true });
+}
+
+/**
+ * @typedef {{
+ *   seq: number,
+ *   data: string,
+ * }} RingChunk
+ */
+
+/**
+ * @typedef {object} TerminalModel
+ * @property {(opts: { cols: number, rows: number, scrollback: number }) => unknown} parserFactory
+ * @property {unknown} parser injected terminal state machine
+ * @property {number} cols
+ * @property {number} rows
+ * @property {number} scrollback
+ * @property {number} ringChunkCap
+ * @property {number} ringByteCap
+ * @property {number} lastSeq seq of the last fed chunk; 0 before the first chunk
+ * @property {number} pendingWrites in-flight parser writes (write called, callback not yet fired)
+ * @property {Array<() => void>} idleWaiters
+ * @property {RingChunk[]} ring oldest-first retained chunks
+ * @property {number} ringBytes total buffered bytes across ring chunks
+ * @property {number} evictedThrough highest seq evicted from the ring; 0 when nothing was evicted
+ */
+
+/**
+ * Create a canonical terminal model. The parser factory is injectable so tests
+ * can drive seq/ring logic with a deterministic fake and render tests can use
+ * the real @xterm/headless parser.
+ *
+ * @param {{
+ *   cols?: number,
+ *   rows?: number,
+ *   scrollback?: number,
+ *   ringChunkCap?: number,
+ *   ringByteCap?: number,
+ *   parserFactory?: typeof defaultParserFactory,
+ * }} [opts]
+ * @returns {TerminalModel}
+ */
+export function createTerminalModel({
+	cols = 80,
+	rows = 24,
+	scrollback = 2000,
+	ringChunkCap = DEFAULT_RING_CHUNK_CAP,
+	ringByteCap = DEFAULT_RING_BYTE_CAP,
+	parserFactory = defaultParserFactory,
+} = {}) {
+	return {
+		parserFactory,
+		parser: parserFactory({ cols, rows, scrollback }),
+		cols,
+		rows,
+		scrollback,
+		ringChunkCap,
+		ringByteCap,
+		lastSeq: 0,
+		pendingWrites: 0,
+		idleWaiters: [],
+		ring: [],
+		ringBytes: 0,
+		evictedThrough: 0,
+	};
+}
+
+/**
+ * Feed one child output chunk: assign the next seq, append to the ring (with
+ * eviction), and hand the exact bytes to the parser in feed order. Escape
+ * sequences split across chunk boundaries stay correct because every chunk is
+ * forwarded to the parser verbatim, in order.
+ *
+ * Fire-and-forget by design; callers that need the parse result await
+ * `whenIdle(model)` first (e.g. before capturing a snapshot).
+ *
+ * @param {TerminalModel} model
+ * @param {string} data
+ * @returns {number} the seq assigned to this chunk
+ */
+export function feedOutput(model, data) {
+	const seq = model.lastSeq + 1;
+	model.lastSeq = seq;
+	appendRing(model, { seq, data });
+	// Increment before write so a synchronously-firing callback still observes
+	// consistent accounting.
+	model.pendingWrites += 1;
+	model.parser.write(data, () => {
+		model.pendingWrites -= 1;
+		if (model.pendingWrites === 0 && model.idleWaiters.length > 0) {
+			const waiters = model.idleWaiters;
+			model.idleWaiters = [];
+			for (const resolve of waiters) resolve();
+		}
+	});
+	return seq;
+}
+
+/**
+ * Evict-then-append retention: trim oldest chunks until both caps hold. The
+ * newest chunk is never evicted by its own append (a single oversized chunk
+ * alone in the ring is allowed; subscribers needing anything before it get a
+ * fresh snapshot instead of a stitched tail).
+ *
+ * @param {TerminalModel} model
+ * @param {RingChunk} chunk
+ */
+function appendRing(model, chunk) {
+	model.ring.push(chunk);
+	model.ringBytes += Buffer.byteLength(chunk.data, "utf8");
+	while (
+		model.ring.length > 1 &&
+		(model.ring.length > model.ringChunkCap || model.ringBytes > model.ringByteCap)
+	) {
+		const evicted = model.ring.shift();
+		model.ringBytes -= Buffer.byteLength(evicted.data, "utf8");
+		model.evictedThrough = evicted.seq;
+	}
+}
+
+/**
+ * Resolve once every chunk fed so far has been fully parsed. Deterministic:
+ * backed by parser write callbacks (no timing-based polling). Safe to call
+ * repeatedly and concurrently; waiters are released in registration order.
+ *
+ * @param {TerminalModel} model
+ * @returns {Promise<void>}
+ */
+export function whenIdle(model) {
+	if (model.pendingWrites === 0) return Promise.resolve();
+	return new Promise((resolve) => {
+		model.idleWaiters.push(resolve);
+	});
+}
+
+/**
+ * Chunks strictly after `seq`, or an eviction marker when part of the requested
+ * range `(seq, ...]` is no longer retained. Callers must treat `evicted: true`
+ * as "fresh snapshot required" — never stitch from a partial tail.
+ *
+ * @param {TerminalModel} model
+ * @param {number} seq cursor to read from (e.g. a snapshot's snapshotSeq)
+ * @returns {{ evicted: false, chunks: RingChunk[] } | { evicted: true, evictedThrough: number }}
+ */
+export function ringChunksAfter(model, seq) {
+	if (seq < model.evictedThrough) {
+		return { evicted: true, evictedThrough: model.evictedThrough };
+	}
+	const chunks = [];
+	for (const chunk of model.ring) {
+		if (chunk.seq > seq) chunks.push(chunk);
+	}
+	return { evicted: false, chunks };
+}
+
+/**
+ * Resize the model and its parser (reflow is the parser's job). Cols/rows on
+ * the model are the authoritative post-resize dimensions for snapshot metadata.
+ *
+ * @param {TerminalModel} model
+ * @param {number} cols
+ * @param {number} rows
+ */
+export function resizeTerminalModel(model, cols, rows) {
+	model.cols = cols;
+	model.rows = rows;
+	const parser = /** @type {{ resize: (c: number, r: number) => void }} */ (model.parser);
+	parser.resize(cols, rows);
+}
+
+/**
+ * Resize the real PTY and the canonical terminal model as ONE paired step
+ * (CR R1 advisory): the model reflows only when `child.resize` succeeded, so
+ * snapshot geometry always mirrors the actual child grid. A throw (child
+ * racing exit) leaves the PTY at its old geometry and the model matching it,
+ * instead of a canonical model that misrepresents the real child output.
+ *
+ * @param {{ resize: (cols: number, rows: number) => void }} child duck-typed PTY handle
+ * @param {TerminalModel} model
+ * @param {number} cols
+ * @param {number} rows
+ */
+export function resizeChildAndModel(child, model, cols, rows) {
+	try {
+		child.resize(cols, rows);
+		resizeTerminalModel(model, cols, rows);
+	} catch {
+		/* child racing exit; PTY kept its old geometry — model stays consistent */
+	}
+}

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] : "";
+}