@zhuxixi/pi-agent-board 0.3.0

package/src/core/prompt-transport.mjs

@@ -0,0 +1,13 @@
+/** Helpers for safely delivering prompts to Pi child processes. */
+
+/**
+ * Protect a prompt that is delivered as a positional CLI argument.
+ * Pi parses argv before it knows which tokens are prompt text, so a leading `-`
+ * would be treated as another flag and abort the run.
+ * @param {string} text
+ * @returns {string}
+ */
+export function encodePromptForCliArg(text) {
+	const raw = String(text ?? "");
+	return /^\s*-/.test(raw) ? ` ${raw}` : raw;
+}

package/src/core/pty-attach-jiggle-retry.mjs

@@ -0,0 +1,90 @@
+/** Pure logic for attach jiggle-retry: detect full-clear, schedule backoff retries. */
+
+export const BACKOFF_MS = Object.freeze([120, 500, 1500, 3000]);
+export const MAX_RETRIES = BACKOFF_MS.length;
+
+// Verified empirically in issue #2: a resize jiggle makes the child pi-tui run
+// fullRender(true), whose output begins with a full clear — a controlled test
+// against a live idle session received 2 clear sequences + ~920KB full repaint
+// per jiggle. So \x1b[2J in the socket output is a reliable "jiggle landed"
+// signal. If pi-tui ever changes fullRender to skip the clear, the detector
+// silently degrades to the old one-shot behavior after MAX_RETRIES.
+const FULL_CLEAR = "\x1b[2J";
+/** Carry enough bytes to catch a split escape sequence at chunk boundary. */
+const CARRY_LEN = FULL_CLEAR.length - 1; // 3 bytes: \x1b, \x1b[, \x1b[2
+
+/**
+ * @typedef {Object} JiggleRetryState
+ * @property {number} retryIndex - Current retry round (0 = initial, not yet retried).
+ * @property {boolean} clearDetected - Whether a full-clear sequence was seen.
+ * @property {boolean} stopped - Whether the retry chain has been stopped.
+ */
+
+/** Create initial retry state. */
+export function createJiggleRetryState() {
+	return { retryIndex: 0, clearDetected: false, stopped: false };
+}
+
+/**
+ * Feed PTY output data into the state machine.
+ * Returns new state, updated carry buffer, and whether a clear was found.
+ * @param {JiggleRetryState} state
+ * @param {string} data - New output data chunk.
+ * @param {string} carry - Leftover partial escape sequence from previous chunk.
+ * @returns {{ state: JiggleRetryState, carry: string, clearFound: boolean }}
+ */
+export function feedOutput(state, data, carry) {
+	const combined = carry + data;
+	const clearFound = hasFullClearSequence(combined);
+	const newCarry = clearFound ? "" : tailCarry(combined);
+	const newState = clearFound ? { ...state, clearDetected: true } : state;
+	return { state: newState, carry: newCarry, clearFound };
+}
+
+/**
+ * Get the delay before the next retry, or null if no more retries.
+ * @param {JiggleRetryState} state
+ * @returns {number | null}
+ */
+export function nextRetryDelay(state) {
+	if (state.stopped || state.clearDetected) return null;
+	if (state.retryIndex >= MAX_RETRIES) return null;
+	return BACKOFF_MS[state.retryIndex];
+}
+
+/**
+ * Advance to the next retry round.
+ * @param {JiggleRetryState} state
+ * @returns {JiggleRetryState}
+ */
+export function advanceRetry(state) {
+	return { ...state, retryIndex: state.retryIndex + 1 };
+}
+
+/**
+ * Stop the retry chain (attach settled, component closed, etc.).
+ * @param {JiggleRetryState} state
+ * @returns {JiggleRetryState}
+ */
+export function stopRetry(state) {
+	return { ...state, stopped: true };
+}
+
+/**
+ * Check if data contains the full-clear escape sequence.
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function hasFullClearSequence(data) {
+	return data.includes(FULL_CLEAR);
+}
+
+/** Extract the tail carry for cross-chunk boundary detection. */
+function tailCarry(data) {
+	// We only need to carry up to CARRY_LEN bytes to catch a split \x1b[2J.
+	const tail = data.slice(-CARRY_LEN);
+	// Find the last \x1b in the tail — everything before it can't be part of
+	// a split escape sequence.
+	const escIdx = tail.lastIndexOf("\x1b");
+	return escIdx >= 0 ? tail.slice(escIdx) : "";
+}

package/src/core/pty-attach-render.mjs

@@ -0,0 +1,51 @@
+/**
+ * Decide whether the next attach repaint should force a full clear.
+ *
+ * The first attach paint always forces once so the previous dashboard/session surface
+ * cannot ghost behind the overlay. Later paints stay differential unless a caller
+ * explicitly requests a hard reset.
+ */
+export function nextAttachRender(firstPaint, force = false) {
+	return {
+		force: Boolean(force || firstPaint),
+		firstPaint: false,
+	};
+}
+
+/**
+ * Attach output should repaint only after @xterm/headless finishes parsing the chunk.
+ * Status/control messages can repaint immediately because they mutate header/overlay state.
+ */
+export function shouldScheduleAttachRenderForMessage(type) {
+	return type === "hello" || type === "status" || type === "exit" || type === "error";
+}
+
+export const ATTACH_OUTPUT_RENDER_INTERVAL_MS = 40;
+
+/**
+ * Coalesce PTY parser callbacks into a bounded stream of repaint requests.
+ *
+ * node-pty commonly splits one child-TUI update across many small chunks. Rendering
+ * after each @xterm/headless write callback exposes those intermediate frames and can
+ * drive the outer TUI near its 60 fps limit. A trailing throttle keeps output live
+ * while presenting only parsed snapshots at roughly 25 fps.
+ */
+export function createAttachOutputRenderScheduler(requestRender, delayMs = ATTACH_OUTPUT_RENDER_INTERVAL_MS) {
+	let timer = null;
+	let disposed = false;
+	return {
+		request() {
+			if (disposed || timer) return;
+			timer = setTimeout(() => {
+				timer = null;
+				if (!disposed) requestRender();
+			}, delayMs);
+			timer.unref?.();
+		},
+		dispose() {
+			disposed = true;
+			if (timer) clearTimeout(timer);
+			timer = null;
+		},
+	};
+}

package/src/core/pty-input.mjs

@@ -0,0 +1,15 @@
+/** Helpers for deciding whether local attach shortcuts should be handled. */
+
+/**
+ * Best-effort detection of Pi's empty prompt/input line from projected terminal text.
+ * The attach surface must not steal editing keys (notably ←) while the child Pi editor
+ * contains text. Pi renders empty editor lines with prompt/continuation glyphs such as
+ * `›`, `┃`, or `│`; once user text is present, non-prompt content remains after this trim.
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function isProbablyEmptyPiInputLine(line) {
+	const withoutRightPadding = String(line || "").replace(/[\s\u00a0]+$/u, "");
+	const content = withoutRightPadding.replace(/^[\s\u00a0›>┃│|┆╎╏:]+/u, "");
+	return content.length === 0;
+}

package/src/core/pty-links.mjs

@@ -0,0 +1,71 @@
+const HTTP_URL_RE = /https?:\/\/[^\s<>"'`]+/g;
+const WORD_CHAR_RE = /[A-Za-z0-9_]/;
+
+export function trimTrailingUrlPunctuation(value) {
+	let url = value;
+	while (url.length > 0) {
+		if (/[.,;:!?]$/.test(url)) {
+			url = url.slice(0, -1);
+			continue;
+		}
+		const last = url.at(-1);
+		if (last === ")" && countChar(url, "(") < countChar(url, ")")) {
+			url = url.slice(0, -1);
+			continue;
+		}
+		if (last === "]" && countChar(url, "[") < countChar(url, "]")) {
+			url = url.slice(0, -1);
+			continue;
+		}
+		if (last === "}" && countChar(url, "{") < countChar(url, "}")) {
+			url = url.slice(0, -1);
+			continue;
+		}
+		break;
+	}
+	return url;
+}
+
+export function findHttpUrlRangeAtCells(cells, col) {
+	if (!Array.isArray(cells) || col < 0 || col >= cells.length) return null;
+	const text = cells.map(normalizeAsciiCell).join("");
+	HTTP_URL_RE.lastIndex = 0;
+	let match;
+	while ((match = HTTP_URL_RE.exec(text))) {
+		const url = trimTrailingUrlPunctuation(match[0]);
+		const start = match.index;
+		const end = start + url.length - 1;
+		if (col >= start && col <= end) return { text: url, start, end };
+	}
+	return null;
+}
+
+export function findHttpUrlAtCells(cells, col) {
+	return findHttpUrlRangeAtCells(cells, col)?.text ?? null;
+}
+
+export function findWordRangeAtCells(cells, col) {
+	if (!Array.isArray(cells) || col < 0 || col >= cells.length) return null;
+	const url = findHttpUrlRangeAtCells(cells, col);
+	if (url) return { ...url, kind: "url" };
+	const text = cells.map(normalizeAsciiCell);
+	if (!WORD_CHAR_RE.test(text[col] ?? "")) return null;
+	let start = col;
+	let end = col;
+	while (start > 0 && WORD_CHAR_RE.test(text[start - 1] ?? "")) start -= 1;
+	while (end + 1 < text.length && WORD_CHAR_RE.test(text[end + 1] ?? "")) end += 1;
+	return { text: text.slice(start, end + 1).join(""), start, end, kind: "word" };
+}
+
+function normalizeAsciiCell(cell) {
+	if (typeof cell !== "string" || cell.length !== 1) return " ";
+	return cell >= " " && cell <= "~" ? cell : " ";
+}
+
+function countChar(text, char) {
+	let count = 0;
+	for (const ch of text) {
+		if (ch === char) count += 1;
+	}
+	return count;
+}

package/src/core/pty-scroll.mjs

@@ -0,0 +1,155 @@
+export function clampInt(value, min, max) {
+	return Math.max(min, Math.min(max, Math.floor(value)));
+}
+
+/** Lines scrolled per mouse-wheel event in the attach viewport when unset/invalid. */
+export const DEFAULT_WHEEL_LINES = 1;
+/** Lower bound for $AGENT_BOARD_WHEEL_LINES. */
+export const MIN_WHEEL_LINES = 1;
+/** Upper bound for $AGENT_BOARD_WHEEL_LINES. */
+export const MAX_WHEEL_LINES = 50;
+
+/**
+ * Resolve how many lines a single mouse-wheel event scrolls in the attach viewport.
+ *
+ * Reads `AGENT_BOARD_WHEEL_LINES`, clamps it to `[MIN_WHEEL_LINES, MAX_WHEEL_LINES]`,
+ * and falls back to `DEFAULT_WHEEL_LINES` when unset, empty, or non-numeric. macOS
+ * inertial/momentum scrolling fires a *burst* of wheel events per gesture, so a small
+ * value here already scrolls quickly; the previous fixed `5` overshot badly.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {number}
+ */
+export function resolveWheelLines(env = process.env) {
+	const raw = String(env.AGENT_BOARD_WHEEL_LINES ?? "").trim();
+	if (!raw) return DEFAULT_WHEEL_LINES;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed)) return DEFAULT_WHEEL_LINES;
+	return clampInt(parsed, MIN_WHEEL_LINES, MAX_WHEEL_LINES);
+}
+
+function parseMouseEventPrefix(data, offset = 0) {
+	const input = data.slice(offset);
+	const sgr = /^\x1b\[(<|\?)(\d+);(\d+);(\d+)([Mm])/.exec(input);
+	if (sgr) {
+		const button = Number(sgr[2]);
+		const col = Number(sgr[3]);
+		const row = Number(sgr[4]);
+		if (!Number.isFinite(button) || !Number.isFinite(col) || !Number.isFinite(row)) return null;
+		return {
+			length: sgr[0].length,
+			raw: sgr[0],
+			mouse: {
+				encoding: sgr[1] === "?" ? "passive" : "sgr",
+				button,
+				col,
+				row,
+				action: sgr[5] === "m" ? "release" : button & 32 ? "move" : "press",
+			},
+		};
+	}
+
+	// X10/normal mouse: ESC [ M Cb Cx Cy. Cb is encoded as button + 32.
+	if (input.startsWith("\x1b[M") && input.length >= 6) {
+		const button = input.charCodeAt(3) - 32;
+		return {
+			length: 6,
+			raw: input.slice(0, 6),
+			mouse: {
+				encoding: "x10",
+				button,
+				col: input.charCodeAt(4) - 32,
+				row: input.charCodeAt(5) - 32,
+				action: button & 32 ? "move" : "press",
+			},
+		};
+	}
+	return null;
+}
+
+/**
+ * Parse a terminal mouse report.
+ * Supports standard SGR (`CSI < ...`), passive SGR (`CSI ? ...`), and X10 mouse encodings.
+ */
+export function parseMouseEvent(data) {
+	const parsed = parseMouseEventPrefix(data);
+	return parsed && parsed.length === data.length ? parsed.mouse : null;
+}
+
+/**
+ * Parse an input chunk that consists entirely of one or more concatenated mouse reports.
+ * Returns each decoded event with its exact raw byte sequence, or null if any non-mouse
+ * bytes are present in the chunk.
+ */
+export function parseMouseInputChunk(data) {
+	if (!data) return null;
+	const events = [];
+	let offset = 0;
+	while (offset < data.length) {
+		const parsed = parseMouseEventPrefix(data, offset);
+		if (!parsed) return null;
+		events.push(parsed);
+		offset += parsed.length;
+	}
+	return events;
+}
+
+/**
+ * Return +1 for wheel-up (scroll back), -1 for wheel-down, 0 for non-wheel input.
+ * Supports standard/passive SGR and X10/normal mouse encodings.
+ */
+export function mouseWheelDirection(data) {
+	const mouse = parseMouseEvent(data);
+	if (!mouse || (mouse.button & 64) === 0) return 0;
+	const wheelButton = mouse.button & 3;
+	if (wheelButton === 0) return 1;
+	if (wheelButton === 1) return -1;
+	return 0; // horizontal wheel: ignore
+}
+
+/**
+ * Compute the next local PTY viewport after a scroll gesture.
+ *
+ * `viewportTop === null` means follow bottom. `changed` reports whether the gesture
+ * would visibly move the local scrollback viewport; callers can forward unconsumed
+ * scroll keys/wheel events to the hosted TUI instead.
+ */
+export function scrollViewportTop(viewportTop, bottom, linesUp) {
+	const safeBottom = Math.max(0, Math.floor(bottom));
+	const current = viewportTop == null ? safeBottom : clampInt(viewportTop, 0, safeBottom);
+	const next = clampInt(current - linesUp, 0, safeBottom);
+	return {
+		viewportTop: next >= safeBottom ? null : next,
+		changed: next !== current,
+	};
+}
+
+/**
+ * Decide whether drag-selecting at/just beyond the viewport edge should auto-scroll.
+ * Positive values scroll up into older output; negative values scroll down.
+ */
+export function selectionDragScrollLines(row, bodyHeight) {
+	const safeHeight = Math.max(1, Math.floor(bodyHeight));
+	const topRow = 2;
+	const bottomRow = topRow + safeHeight - 1;
+	const pointerRow = Math.floor(row);
+	if (pointerRow < topRow) return 2;
+	if (pointerRow === topRow) return 1;
+	if (pointerRow > bottomRow) return -2;
+	if (pointerRow === bottomRow) return -1;
+	return 0;
+}
+
+/**
+ * Return a one-frame alternate PTY size that will force a hosted TUI to receive a
+ * SIGWINCH/redraw before restoring the real size. This mirrors the user-visible
+ * terminal zoom workaround without leaving the child at the wrong dimensions.
+ */
+export function resizeJiggleSize(cols, rows) {
+	const c = Math.max(1, Math.floor(cols));
+	const r = Math.max(1, Math.floor(rows));
+	if (c > 21 && r > 6) return { cols: c - 1, rows: r - 1 };
+	if (r > 6) return { cols: c, rows: r - 1 };
+	if (c > 21) return { cols: c - 1, rows: r };
+	return null;
+}