@zhuxixi/pi-agent-board 0.6.2 → 0.8.0

package/src/core/terminal-snapshot.mjs

@@ -0,0 +1,440 @@
+import assert from "node:assert/strict";
+import { createTerminalModel, defaultParserFactory, feedOutput, whenIdle } from "./terminal-model.mjs";
+
+/**
+ * Terminal snapshot serialization for the canonical terminal model (issue #91,
+ * D2/D5). The versioned DTO is the project-owned snapshot contract — xterm.js
+ * private buffer objects never leave the module. A single full-redraw frame
+ * synthesis implementation serves both directions:
+ *
+ *  - hydrate: frame → independent parser (equivalence-testable, A4/A5b)
+ *  - wire route B: the same frame goes on the socket and the UI feeds its
+ *    existing xterm verbatim (route decision evidence in the plan).
+ *
+ * The canonical state lives for the runner's lifetime only; snapshots are
+ * generated on demand from the live parser, never persisted.
+ */
+
+export const TERMINAL_SNAPSHOT_VERSION = 1;
+export const DEFAULT_SCROLLBACK_SNAPSHOT_CAP = 256;
+
+/**
+ * Cell attribute flags (own wire encoding, documented here — deliberately not
+ * xterm.js internals).
+ */
+export const CELL_FLAGS = {
+	BOLD: 1,
+	DIM: 2,
+	ITALIC: 4,
+	UNDERLINE: 8,
+	BLINK: 16,
+	INVERSE: 32,
+	INVISIBLE: 64,
+	STRIKETHROUGH: 128,
+	OVERLINE: 256,
+};
+
+/**
+ * Color encoding for DTO cells: -1 = default; 0-255 = palette index;
+ * RGB_MARKER | 0xRRGGBB = direct color (marker bit keeps it disjoint from
+ * palette indexes).
+ */
+const DEFAULT_COLOR = -1;
+const RGB_MARKER = 0x1000000;
+
+/**
+ * @typedef {string | [ch: string, fg: number, bg: number, flags: number]} SnapshotCell
+ * A cell entry: plain string = char with default attributes; tuple = char with
+ * explicit color/attribute encoding; "" = zero-width continuation cell of a
+ * wide char (regenerated by the preceding wide char on hydrate, never emitted).
+ */
+
+/**
+ * @typedef {object} TerminalSnapshotDto
+ * @property {1} version
+ * @property {"terminal_snapshot"} kind
+ * @property {number} cols
+ * @property {number} rows
+ * @property {number} snapshotSeq seq of the last chunk incorporated
+ * @property {{ x: number, y: number }} cursor viewport-relative; x may equal
+ *   cols — the parser's wrap-pending state (captured faithfully, never clamped)
+ * @property {Record<string, boolean | string>} modes parser modes (full set)
+ * @property {SnapshotCell[][]} viewport rows of the viewport grid
+ * @property {SnapshotCell[][]} scrollback up to scrollbackCap lines directly
+ *   above the viewport, oldest first
+ * @property {boolean} scrollbackTruncated true when more scrollback existed
+ *   than the cap allowed
+ */
+
+/**
+ * Capture one cell as a DTO entry. Blank default-attribute cells collapse to
+ * their char (keeps the DTO compact); everything else is an explicit tuple.
+ *
+ * @param {any} cell xterm.js IBufferCell
+ * @returns {SnapshotCell}
+ */
+function captureCell(cell) {
+	if (cell.getWidth() === 0) return "";
+	const ch = cell.getChars() || " ";
+	const fg = cell.isFgDefault()
+		? DEFAULT_COLOR
+		: cell.isFgRGB()
+			? RGB_MARKER | (cell.getFgColor() & 0xffffff)
+			: cell.isFgPalette()
+				? cell.getFgColor() & 0xff
+				: DEFAULT_COLOR;
+	const bg = cell.isBgDefault()
+		? DEFAULT_COLOR
+		: cell.isBgRGB()
+			? RGB_MARKER | (cell.getBgColor() & 0xffffff)
+			: cell.isBgPalette()
+				? cell.getBgColor() & 0xff
+				: DEFAULT_COLOR;
+	let flags = 0;
+	if (cell.isBold()) flags |= CELL_FLAGS.BOLD;
+	if (cell.isDim()) flags |= CELL_FLAGS.DIM;
+	if (cell.isItalic()) flags |= CELL_FLAGS.ITALIC;
+	if (cell.isUnderline()) flags |= CELL_FLAGS.UNDERLINE;
+	if (cell.isBlink()) flags |= CELL_FLAGS.BLINK;
+	if (cell.isInverse()) flags |= CELL_FLAGS.INVERSE;
+	if (cell.isInvisible()) flags |= CELL_FLAGS.INVISIBLE;
+	if (cell.isStrikethrough()) flags |= CELL_FLAGS.STRIKETHROUGH;
+	if (cell.isOverline()) flags |= CELL_FLAGS.OVERLINE;
+	return flags === 0 && fg === DEFAULT_COLOR && bg === DEFAULT_COLOR ? ch : [ch, fg, bg, flags];
+}
+
+/**
+ * @param {any} buffer xterm.js IBuffer
+ * @param {number} lineIndex absolute buffer line
+ * @param {number} cols
+ * @returns {SnapshotCell[]}
+ */
+function captureLine(buffer, lineIndex, cols) {
+	const line = buffer.getLine(lineIndex);
+	/** @type {SnapshotCell[]} */
+	const cells = new Array(cols);
+	if (!line) {
+		cells.fill(" ");
+		return cells;
+	}
+	for (let x = 0; x < cols; x++) cells[x] = captureCell(line.getCell(x));
+	return cells;
+}
+
+/**
+ * Snapshot the parser mode flags (full set exposed by @xterm/headless).
+ *
+ * @param {any} parser
+ */
+function captureModes(parser) {
+	return { ...parser.modes };
+}
+
+/**
+ * Generate a versioned TerminalSnapshot DTO from the canonical model. Waits
+ * for all pending parser writes so the grid read is deterministic.
+ *
+ * @param {import("./terminal-model.mjs").TerminalModel} model
+ * @param {{ scrollbackCap?: number }} [opts]
+ * @returns {Promise<TerminalSnapshotDto>}
+ */
+export async function captureTerminalSnapshot(model, { scrollbackCap = DEFAULT_SCROLLBACK_SNAPSHOT_CAP } = {}) {
+	await whenIdle(model);
+	const parser = /** @type {any} */ (model.parser);
+	const buffer = parser.buffer.active;
+	const cols = model.cols;
+	const rows = model.rows;
+	const baseY = buffer.baseY;
+	/** @type {SnapshotCell[][]} */
+	const viewport = [];
+	for (let y = 0; y < rows; y++) viewport.push(captureLine(buffer, baseY + y, cols));
+	const available = baseY;
+	const take = Math.min(scrollbackCap, available);
+	/** @type {SnapshotCell[][]} */
+	const scrollback = [];
+	for (let k = take; k >= 1; k--) scrollback.push(captureLine(buffer, baseY - k, cols));
+	return {
+		version: TERMINAL_SNAPSHOT_VERSION,
+		kind: "terminal_snapshot",
+		cols,
+		rows,
+		snapshotSeq: model.lastSeq,
+		cursor: { x: buffer.cursorX, y: buffer.cursorY },
+		modes: captureModes(parser),
+		viewport,
+		scrollback,
+		scrollbackTruncated: available > scrollbackCap,
+	};
+}
+
+/** @param {number} color @param {boolean} isFg @param {string[]} p */
+function pushColor(p, color, isFg) {
+	if (color === DEFAULT_COLOR) {
+		p.push(isFg ? "39" : "49");
+	} else if (color >= RGB_MARKER) {
+		const rgb = color - RGB_MARKER;
+		p.push(`${isFg ? 38 : 48};2;${(rgb >> 16) & 255};${(rgb >> 8) & 255};${rgb & 255}`);
+	} else if (color <= 7) {
+		p.push(String((isFg ? 30 : 40) + color));
+	} else if (color <= 15) {
+		p.push(String((isFg ? 90 : 100) + (color - 8)));
+	} else {
+		p.push(`${isFg ? 38 : 48};5;${color}`);
+	}
+}
+
+/** @param {number} fg @param {number} bg @param {number} flags */
+function sgrSequence(fg, bg, flags) {
+	/** @type {string[]} */
+	const p = ["0"];
+	if (flags & CELL_FLAGS.BOLD) p.push("1");
+	if (flags & CELL_FLAGS.DIM) p.push("2");
+	if (flags & CELL_FLAGS.ITALIC) p.push("3");
+	if (flags & CELL_FLAGS.UNDERLINE) p.push("4");
+	if (flags & CELL_FLAGS.BLINK) p.push("5");
+	if (flags & CELL_FLAGS.INVERSE) p.push("7");
+	if (flags & CELL_FLAGS.INVISIBLE) p.push("8");
+	if (flags & CELL_FLAGS.STRIKETHROUGH) p.push("9");
+	if (flags & CELL_FLAGS.OVERLINE) p.push("53");
+	pushColor(p, fg, true);
+	pushColor(p, bg, false);
+	return `\x1b[${p.join(";")}m`;
+}
+
+/**
+ * Emit one DTO row as run-length SGR + text. Emits every column position in
+ * order (wide-char continuation cells are skipped: the parser regenerates them
+ * when the wide char prints), so no intermediate positioning is needed within
+ * a row.
+ *
+ * @param {string[]} parts
+ * @param {SnapshotCell[]} cells
+ */
+function emitRow(parts, cells) {
+	let runKey = null;
+	let runSgr = "";
+	let runText = "";
+	const flush = () => {
+		if (runText) parts.push(runSgr, runText);
+		runText = "";
+	};
+	for (const entry of cells) {
+		if (entry === "") continue;
+		const tuple = Array.isArray(entry);
+		const ch = tuple ? entry[0] : entry;
+		const fg = tuple ? entry[1] : DEFAULT_COLOR;
+		const bg = tuple ? entry[2] : DEFAULT_COLOR;
+		const flags = tuple ? entry[3] : 0;
+		const key = `${fg}/${bg}/${flags}`;
+		if (key !== runKey) {
+			flush();
+			runKey = key;
+			runSgr = sgrSequence(fg, bg, flags);
+		}
+		runText += ch;
+	}
+	flush();
+}
+
+/**
+ * Re-apply the captured parser modes. Bracketed paste, focus reporting, mouse
+ * tracking and synchronized output are restored so live output after the
+ * snapshot behaves like the original session.
+ *
+ * @param {Record<string, boolean | string>} m
+ */
+function modesSequence(m) {
+	const dec = (n, v) => `\x1b[?${n}${v ? "h" : "l"}`;
+	let s = "";
+	s += dec(1, Boolean(m.applicationCursorKeysMode));
+	s += m.applicationKeypadMode ? "\x1b=" : "\x1b>";
+	s += dec(2004, Boolean(m.bracketedPasteMode));
+	s += m.insertMode ? "\x1b[4h" : "\x1b[4l";
+	switch (m.mouseTrackingMode) {
+		case "x10":
+			s += "\x1b[?9h";
+			break;
+		case "vt200":
+			s += "\x1b[?1000h";
+			break;
+		case "button":
+			s += "\x1b[?1002h";
+			break;
+		case "any":
+			s += "\x1b[?1003h";
+			break;
+		default:
+			s += "\x1b[?9l\x1b[?1000l\x1b[?1002l\x1b[?1003l";
+	}
+	s += dec(6, Boolean(m.originMode));
+	s += dec(45, Boolean(m.reverseWraparoundMode));
+	s += dec(7, Boolean(m.wraparoundMode));
+	s += dec(1004, Boolean(m.sendFocusMode));
+	s += dec(2026, Boolean(m.synchronizedOutputMode));
+	return s;
+}
+
+/**
+ * Park the cursor at the captured position. x === cols is the parser's
+ * wrap-pending state (Task-1 review ruling: captured faithfully, never
+ * clamped) — reproduced by re-emitting the target row: with autowrap on, the
+ * char landing in the last column re-arms pending. Insert mode must be off
+ * while re-emitting (it would shift instead of overwrite); wraparound and
+ * insert are restored after emission (mode sets never move the cursor).
+ *
+ * Origin mode is NEVER toggled here: headless v6 homes the cursor on DECOM
+ * set AND reset (observed), so a toggle after the park would re-home the
+ * just-parked cursor, and a toggle before it is unnecessary — the frame
+ * preamble guarantees a full scroll region (\x1b[r), under which
+ * origin-relative CUP addresses the same cell as absolute CUP, and origin
+ * mode does not affect character emission. The explicit ?6h re-assert keeps
+ * the park self-contained; it must stay before any CUP.
+ *
+ * @param {string[]} parts
+ * @param {TerminalSnapshotDto} dto
+ */
+function parkCursor(parts, dto) {
+	const { x, y } = dto.cursor;
+	const row = dto.viewport[y] ?? [];
+	if (dto.modes.originMode) parts.push("\x1b[?6h");
+	if (x >= dto.cols) {
+		parts.push("\x1b[?7h\x1b[4l", `\x1b[${y + 1};1H`);
+		emitRow(parts, row);
+		if (dto.modes.wraparoundMode === false) parts.push("\x1b[?7l");
+		if (dto.modes.insertMode) parts.push("\x1b[4h");
+		return;
+	}
+	parts.push(`\x1b[${y + 1};${x + 1}H`);
+}
+
+/**
+ * Synthesize a full-redraw VT frame from a snapshot DTO (or directly from a
+ * model, which is captured first — one grid-walk implementation serves both).
+ * The frame is self-contained: safe to write into a DIRTY terminal (wire route
+ * B reuse), not just a fresh hydrate parser.
+ *
+ * Frame layout: clean slate (DECSTR + clear viewport/scrollback + home + full
+ * region + content-emission invariants: autowrap on, origin off, insert off) →
+ * scrollback lines pushed through the bottom-row scroll one by one → viewport
+ * rows via absolute CUP + SGR runs → captured modes → cursor park.
+ *
+ * @param {TerminalSnapshotDto | import("./terminal-model.mjs").TerminalModel} source
+ * @returns {Promise<string>}
+ */
+export async function synthesizeFullRedrawFrame(source) {
+	/** @type {TerminalSnapshotDto} */
+	const dto =
+		/** @type {any} */ (source)?.kind === "terminal_snapshot"
+			? /** @type {TerminalSnapshotDto} */ (source)
+			: await captureTerminalSnapshot(/** @type {any} */ (source));
+	const parts = [
+		// DECSTR resets modes/regions/SGR; 2J clears the viewport, 3J clears
+		// scrollback (ignored gracefully where unsupported); r resets the region;
+		// then force the invariants content emission relies on.
+		"\x1b[!p\x1b[2J\x1b[3J\x1b[H\x1b[r\x1b[?7h\x1b[?6l\x1b[4l",
+	];
+	// Scrollback + viewport in ONE continuous top-down stream: total emissions
+	// = scrollback.length + rows, so exactly scrollback.length line feeds fire
+	// at the bottom row and the first `scrollback.length` emissions scroll into
+	// scrollback in order (verified P4 probe: CR LF after a full-width
+	// wrap-pending row advances exactly one line). The last viewport row gets
+	// no trailing newline (it would fire an extra scroll); the cursor park
+	// below positions the cursor afterwards.
+	for (const line of dto.scrollback) {
+		emitRow(parts, line);
+		parts.push("\r\n");
+	}
+	for (let y = 0; y < dto.rows - 1; y++) {
+		emitRow(parts, dto.viewport[y] ?? []);
+		parts.push("\r\n");
+	}
+	emitRow(parts, dto.viewport[dto.rows - 1] ?? []);
+	parts.push(modesSequence(dto.modes));
+	parkCursor(parts, dto);
+	return parts.join("");
+}
+
+/**
+ * Rebuild an independent terminal model from a snapshot DTO: the synthesized
+ * full-redraw frame is fed through a fresh parser. This is both the route-A
+ * hydrate engine and the route-B wire-encoding producer.
+ *
+ * @param {TerminalSnapshotDto} dto
+ * @param {typeof defaultParserFactory} [parserFactory]
+ * @returns {Promise<import("./terminal-model.mjs").TerminalModel>}
+ */
+export async function hydrateTerminalSnapshot(dto, parserFactory = defaultParserFactory) {
+	assertSnapshotContract(dto);
+	const model = createTerminalModel({ cols: dto.cols, rows: dto.rows, parserFactory });
+	feedOutput(model, await synthesizeFullRedrawFrame(dto));
+	await whenIdle(model);
+	return model;
+}
+
+/**
+ * @param {TerminalSnapshotDto} dto
+ */
+function assertSnapshotContract(dto) {
+	if (!dto || dto.kind !== "terminal_snapshot" || dto.version !== TERMINAL_SNAPSHOT_VERSION) {
+		throw new TypeError(
+			`unsupported terminal snapshot: kind=${/** @type {any} */ (dto)?.kind} version=${/** @type {any} */ (dto)?.version} (supported: v${TERMINAL_SNAPSHOT_VERSION})`,
+		);
+	}
+	if (!Number.isInteger(dto.cols) || dto.cols < 1 || !Number.isInteger(dto.rows) || dto.rows < 1) {
+		throw new TypeError(`invalid terminal snapshot dimensions: ${dto.cols}x${dto.rows}`);
+	}
+}
+
+/**
+ * First-difference-detail line comparison (deepEqual on 22k-cell arrays gives
+ * unusable diffs).
+ *
+ * @param {SnapshotCell[]} got
+ * @param {SnapshotCell[]} want
+ * @param {string} label
+ */
+function assertLinesEqual(got, want, label) {
+	const same =
+		got.length === want.length && got.every((v, i) => JSON.stringify(v) === JSON.stringify(want[i]));
+	if (!same) {
+		const i = got.findIndex((v, j) => JSON.stringify(v) !== JSON.stringify(want[j]));
+		throw new Error(
+			`${label}: cell ${i} — got ${JSON.stringify(got[i])} want ${JSON.stringify(want[i])}\n  got:  ${JSON.stringify(got)}\n  want: ${JSON.stringify(want)}`,
+		);
+	}
+}
+
+/**
+ * Equivalence walker for hydrate round-trip tests (A4/A5b): dimensions, modes,
+ * cursor (including wrap-pending x === cols), full viewport grid, and the
+ * scrollback lines directly above the viewport up to the cap.
+ *
+ * @param {import("./terminal-model.mjs").TerminalModel} modelA source model
+ * @param {import("./terminal-model.mjs").TerminalModel} modelB hydrated model
+ * @param {{ scrollbackCap?: number }} [opts]
+ */
+export function assertSnapshotEquivalence(modelA, modelB, { scrollbackCap = DEFAULT_SCROLLBACK_SNAPSHOT_CAP } = {}) {
+	const bufA = /** @type {any} */ (modelA.parser).buffer.active;
+	const bufB = /** @type {any} */ (modelB.parser).buffer.active;
+	assert.equal(modelB.cols, modelA.cols, "cols mismatch");
+	assert.equal(modelB.rows, modelA.rows, "rows mismatch");
+	assert.deepEqual(captureModes(modelB.parser), captureModes(modelA.parser), "modes mismatch");
+	assert.equal(bufB.cursorX, bufA.cursorX, `cursor.x mismatch (wrap-pending must survive verbatim)`);
+	assert.equal(bufB.cursorY, bufA.cursorY, "cursor.y mismatch");
+	for (let y = 0; y < modelA.rows; y++) {
+		assertLinesEqual(
+			captureLine(bufB, bufB.baseY + y, modelB.cols),
+			captureLine(bufA, bufA.baseY + y, modelA.cols),
+			`viewport row ${y}`,
+		);
+	}
+	const expectedScrollback = Math.min(scrollbackCap, bufA.baseY);
+	assert.equal(bufB.baseY, expectedScrollback, "scrollback depth above viewport mismatch");
+	for (let k = 1; k <= expectedScrollback; k++) {
+		assertLinesEqual(
+			captureLine(bufB, bufB.baseY - k, modelB.cols),
+			captureLine(bufA, bufA.baseY - k, modelA.cols),
+			`scrollback line -${k}`,
+		);
+	}
+}

package/src/core/types.mjs

@@ -120,6 +120,7 @@ export const GROUP_LABELS = {
  * @property {SteeringSummary} [steering] Compact plan/approval steering summary.
  * @property {CodeRefsSummary} [codeRefs] Compact issue/PR reference summary.
  * @property {AutoStateClassification|null} [autoState] Latest automatic terminal-state classification.
+ * @property {number} [materializedRevision] Coordinator-stamped monotonic revision (issue #91). Absent on legacy rows until the View State Coordinator first materializes the view.
  */
 
 /**
@@ -188,6 +189,7 @@ export const GROUP_LABELS = {
  * @property {EvidenceUsage|null} [usage]
  * @property {string|null} [stallReason]
  * @property {ReviewSummary|null} [evidenceSummary]
+ * @property {number} [materializedRevision] Coordinator-stamped monotonic revision shared with the view's state.json (issue #91). Absent on legacy rows until first coordinator materialization.
  * @property {AutoStateClassification|null} [autoState]
  */
 

package/src/index.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 import { createConnection } from "node:net";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resolvePiInvocation } from "./core/invocation.mjs";
-import { controlSocketPathFor, defaultRoot } from "./core/paths.mjs";
+import { defaultRoot, resolveControlEndpoint } from "./core/paths.mjs";
 import { listRows } from "./core/store.mjs";
 import { createService, envInt } from "./runtime/service.mjs";
 import { attachWarmHostSweeper } from "./core/warm-host-sweeper.mjs";
@@ -90,7 +90,7 @@ export default function piAgentBoard(pi: ExtensionAPI): void {
 
 	const updateStatus = (ctx: ExtensionContext) => {
 		try {
-			serviceFor(ctx).reconcile();
+			void serviceFor(ctx).reconcile().catch(() => {});
 			const rows = listRows(root);
 			const needs = rows.filter((r) => r.state?.semanticState === "needs_input").length;
 			const working = rows.filter((r) => r.alive).length;
@@ -115,14 +115,22 @@ export default function piAgentBoard(pi: ExtensionAPI): void {
 			const { createEditorStateReporter } = await import("./core/editor-state-reporter.mjs");
 			hostedEditorReporter = createEditorStateReporter({
 				getEditorText: () => ctx.ui.getEditorText(),
-				connect: () => createConnection(controlSocketPathFor(process.platform as "win32" | "linux" | "darwin", root, hostedViewId)),
+				connect: () => createConnection(resolveControlEndpoint({
+					// The runner injects the endpoint it actually bound (issue #103);
+					// falling back to the stable per-view address keeps older runners
+					// and legacy hosts working.
+					envSocketPath: process.env.AGENT_BOARD_CONTROL_SOCKET,
+					platform: process.platform as "win32" | "linux" | "darwin",
+					root,
+					viewId: hostedViewId,
+				})),
 			});
 			hostedEditorReporter.start();
 		}
 		updateStatus(ctx);
 		if (event.reason === "startup" && !isHostedChild && pi.getFlag("agent-board") === true && ctx.hasUI) {
 			const service = createService({ root, runnerScript: RUNNER_SCRIPT, ptyRunnerScript: PTY_RUNNER_SCRIPT, titleRunnerScript: TITLE_RUNNER_SCRIPT, autoStateRunnerScript: AUTO_STATE_RUNNER_SCRIPT, piCommand, piArgsPrefix, defaultCwd: ctx.cwd, availableModels: availableModelsFor(ctx) });
-			service.reconcile();
+			void service.reconcile().catch(() => {});
 			ctx.ui.setWorkingVisible(false);
 			ctx.ui.setHeader(() => ({ render: () => [], invalidate() {} }));
 			ctx.ui.setFooter(() => ({ render: () => [], invalidate() {} }));