pi-squire 0.14.0 → 0.16.0

package/src/widget-render.ts

@@ -0,0 +1,181 @@
+import { stripVTControlCharacters } from "node:util";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { AncestorRow } from "./widget-ancestors.ts";
+import type { DelegateRow } from "./widget-data.ts";
+
+export type WidgetTheme = Pick<Theme, "fg" | "bold">;
+
+/** Foreign names and labels are text, not terminal commands or multiline layout. */
+export function widgetText(value: string): string {
+	return [...stripVTControlCharacters(value).replace(/\s+/g, " ")]
+		.filter((character) => {
+			const code: number = character.codePointAt(0) ?? 0;
+			return code >= 32 && (code < 127 || code > 159);
+		})
+		.join("")
+		.trim()
+		.slice(0, 2048);
+}
+
+function age(timestamp: number, now: number): string {
+	const minutes: number = Math.floor(Math.max(0, now - timestamp) / 60_000);
+	if (minutes < 1) return "just now";
+	if (minutes < 60) return `${minutes}m ago`;
+	return `${Math.floor(minutes / 60)}h ago`;
+}
+
+function appearance(row: DelegateRow): { icon: string; color: "accent" | "success" | "warning" | "error" } {
+	if (row.running) return { icon: "◌", color: "accent" };
+	if (row.state === "done") return { icon: "✓", color: "success" };
+	if (row.state === "failed") return { icon: "✗", color: "error" };
+	return { icon: "!", color: "warning" };
+}
+
+function metadata(row: DelegateRow, width: number, coreWidth: number, now: number): string {
+	const model: string = widgetText(row.model.split("/").slice(1).join("/") || row.model);
+	const seen: string = row.lastActive === undefined ? "" : `file ${age(row.lastActive, now)}`;
+	const columns: string[] = [seen, model].filter(Boolean);
+	// Remove model, then file-age, before sacrificing identity/state/title.
+	while (columns.length && coreWidth + visibleWidth(` · ${columns.join(" · ")}`) > width) columns.pop();
+	return columns.length ? ` · ${columns.join(" · ")}` : "";
+}
+
+function entry(row: DelegateRow, width: number, connector: string, theme: WidgetTheme, now: number): string {
+	const { icon, color } = appearance(row);
+	const state: string = widgetText(row.state);
+	const name: string = widgetText(row.identity);
+	if (width < 16) return truncateToWidth(`${theme.fg(color, icon)} ${theme.bold(name)}`, width);
+	const prefix: string = `${theme.fg("dim", connector)} ${theme.fg(color, icon)} `;
+	const suffix: string = ` · ${theme.fg(color, state)}`;
+	const title: string = widgetText(row.title ?? "");
+	const preferred: number = visibleWidth(prefix + name + suffix) + (title ? Math.min(24, visibleWidth(title)) + 2 : 0);
+	const extra: string = metadata(row, width, preferred, now);
+	const room: number = Math.max(1, width - visibleWidth(prefix + suffix + extra));
+	const identity: string = truncateToWidth(name, room);
+	const titleRoom: number = room - visibleWidth(identity) - 2;
+	const description: string = title && title !== name && titleRoom >= 4 ? `  ${truncateToWidth(title, titleRoom)}` : "";
+	return truncateToWidth(`${prefix}${theme.bold(identity)}${description}${suffix}${theme.fg("dim", extra)}`, width);
+}
+
+/** One secondary line; descendant task counts take priority when both do not fit. */
+export function activityLine(
+	row: DelegateRow,
+	width: number,
+	last: boolean,
+	theme: WidgetTheme,
+	summary = "",
+): string | undefined {
+	const activity: string =
+		row.running && row.activity
+			? `${row.activity.kind === "response" ? "response: " : ""}${widgetText(row.activity.text)}`
+			: "";
+	const facts: string = widgetText(summary);
+	if (!activity && !facts) return;
+	const prefix: string = last ? "   └─ " : "│  └─ ";
+	let text: string = [activity, facts].filter(Boolean).join(" · ");
+	if (facts && visibleWidth(prefix + text) > width) text = facts;
+	return truncateToWidth(theme.fg("dim", prefix + text), width);
+}
+
+export type WidgetRenderOptions = {
+	offset?: number;
+	selectedKey?: string;
+	focused?: boolean;
+	ancestors?: readonly AncestorRow[];
+	ancestryError?: string;
+};
+
+function selectableEntry(
+	row: DelegateRow,
+	width: number,
+	last: boolean,
+	theme: WidgetTheme,
+	now: number,
+	options: WidgetRenderOptions,
+): string {
+	const gutter: string = options.focused ? "  " : "";
+	const marker: string = options.focused && row.key === options.selectedKey ? theme.fg("accent", "▸ ") : gutter;
+	return marker + entry(row, width - visibleWidth(marker), last ? "└─" : "├─", theme, now);
+}
+
+function ancestorLines(ancestors: readonly AncestorRow[], options: WidgetRenderOptions, theme: WidgetTheme): string[] {
+	return ancestors.map((ancestor, index) => {
+		const gutter: string = options.focused ? "  " : "";
+		const marker: string = options.focused && ancestor.key === options.selectedKey ? theme.fg("accent", "▸ ") : gutter;
+		const connector: string = index ? `${"  ".repeat(index - 1)}└─ ` : "";
+		return (
+			marker +
+			connector +
+			"↑ " +
+			theme.bold(widgetText(ancestor.identity)) +
+			(ancestor.parent ? " (parent)" : "") +
+			(ancestor.title ? `  ${widgetText(ancestor.title)}` : "")
+		);
+	});
+}
+
+function more(count: number): string {
+	return `${count} more direct delegate${count === 1 ? "" : "s"}`;
+}
+
+function childLines(
+	rows: readonly DelegateRow[],
+	cap: number,
+	width: number,
+	theme: WidgetTheme,
+	now: number,
+	options: WidgetRenderOptions,
+): string[] {
+	const depth: number = options.ancestors?.length ?? 0;
+	const indent: string = "  ".repeat(depth);
+	const gutter: string = options.focused ? "  " : "";
+	const branch: string = depth ? `${"  ".repeat(depth - 1)}└─ ` : "";
+	const lines: string[] = [gutter + branch + theme.fg("accent", theme.bold("Delegates"))];
+	const start: number = Math.max(0, Math.min(options.offset ?? 0, rows.length - cap));
+	const visible: readonly DelegateRow[] = rows.slice(start, start + cap);
+	const hidden: number = rows.length - start - visible.length;
+	if (start) lines.push(gutter + indent + theme.fg("dim", `├─ ↑ ${more(start)}`));
+	for (const [index, row] of visible.entries()) {
+		const last: boolean = index === visible.length - 1 && hidden === 0;
+		lines.push(indent + selectableEntry(row, width - indent.length, last, theme, now, options));
+		const secondary: string | undefined = activityLine(
+			row,
+			width - gutter.length - indent.length,
+			last,
+			theme,
+			row.summary,
+		);
+		if (secondary) lines.push(gutter + indent + secondary);
+	}
+	if (hidden) lines.push(gutter + indent + theme.fg("dim", `└─ +${more(hidden)}`));
+	return lines;
+}
+
+/** Pure layout: the cap counts child entries, not physical lines or hidden children. */
+export function renderDelegateWidget(
+	rows: readonly DelegateRow[],
+	cap: number,
+	width: number,
+	theme: WidgetTheme,
+	now: number = Date.now(),
+	options: WidgetRenderOptions = {},
+): string[] {
+	if (width <= 0) return [];
+	const ancestors: readonly AncestorRow[] = options.ancestors ?? [];
+	if (!ancestors.length && (cap === 0 || !rows.length) && !options.ancestryError) return [];
+	const gutter: string = options.focused ? "  " : "";
+	const lines: string[] = ancestorLines(ancestors, options, theme);
+	if (options.ancestryError) lines.push(gutter + theme.fg("warning", widgetText(options.ancestryError)));
+	if (cap > 0 && rows.length) lines.push(...childLines(rows, cap, width, theme, now, options));
+	if (options.focused)
+		lines.push(
+			theme.fg(
+				"dim",
+				ancestors.some((ancestor) => ancestor.key === options.selectedKey)
+					? "↑↓ select · enter switch · esc prompt"
+					: "↑↓ select · enter details · esc prompt",
+			),
+		);
+	return lines.map((line) => truncateToWidth(line, width));
+}

package/src/widget-selection.ts

@@ -0,0 +1,58 @@
+/** Compact-list state only. Stable keys never confer action authority. */
+export class WidgetSelection {
+	private keys: readonly string[] = [];
+	private ancestors = 0;
+	private cap = 0;
+	private index = 0;
+	private start = 0;
+	active = false;
+
+	get selectedKey(): string | undefined {
+		return this.keys[this.index];
+	}
+	get offset(): number {
+		return this.start;
+	}
+
+	update(children: readonly string[], cap: number, ancestors: readonly string[] = []): void {
+		const selected: string | undefined = this.selectedKey;
+		const keys: readonly string[] = [...ancestors, ...(cap > 0 ? children : [])];
+		this.keys = keys;
+		this.ancestors = ancestors.length;
+		this.cap = cap;
+		const retained: number = selected === undefined ? -1 : keys.indexOf(selected);
+		this.index = retained >= 0 ? retained : Math.max(0, Math.min(this.index, keys.length - 1));
+		if (!keys.length) this.leave();
+		this.scroll();
+	}
+
+	enter(): boolean {
+		if (!this.keys.length) return false;
+		this.active = true;
+		this.index = Math.max(0, this.ancestors - 1);
+		this.scroll();
+		return true;
+	}
+
+	leave(): void {
+		this.active = false;
+		this.start = 0;
+	}
+
+	move(direction: -1 | 1): void {
+		if (direction === -1 && this.index === 0) this.leave();
+		else this.index = Math.max(0, Math.min(this.keys.length - 1, this.index + direction));
+		this.scroll();
+	}
+
+	private scroll(): void {
+		const child: number = this.index - this.ancestors;
+		if (!this.active || child < 0 || this.cap === 0) {
+			this.start = 0;
+			return;
+		}
+		if (child < this.start) this.start = child;
+		if (child >= this.start + this.cap) this.start = child - this.cap + 1;
+		this.start = Math.max(0, Math.min(this.start, this.keys.length - this.ancestors - this.cap));
+	}
+}

package/src/widget-settings.ts

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type WidgetSettings = { placement: "aboveEditor" | "belowEditor"; maxEntries: number };
+export const DEFAULT_WIDGET_SETTINGS: WidgetSettings = { placement: "aboveEditor", maxEntries: 3 };
+
+/** Cosmetic settings never block delegation; the caller reports errors and uses defaults. */
+export function widgetSettings(): WidgetSettings {
+	const file: string = join(getAgentDir(), "squire", "settings.json");
+	let value: unknown;
+	try {
+		value = JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { ...DEFAULT_WIDGET_SETTINGS };
+		throw new Error(`could not read widget settings in ${file}: ${String(error)}`);
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error(`invalid widget settings in ${file}: expected an object`);
+	const settings: Record<string, unknown> = value as Record<string, unknown>;
+	const placement: unknown =
+		settings.delegateWidgetPlacement === undefined ? "above" : settings.delegateWidgetPlacement;
+	const cap: unknown = settings.delegateWidgetMaxEntries === undefined ? 3 : settings.delegateWidgetMaxEntries;
+	if (placement !== "above" && placement !== "below")
+		throw new Error(`invalid delegateWidgetPlacement in ${file}: expected above or below`);
+	if (typeof cap !== "number" || !Number.isSafeInteger(cap) || cap < 0)
+		throw new Error(`invalid delegateWidgetMaxEntries in ${file}: expected a nonnegative integer`);
+	return { placement: placement === "above" ? "aboveEditor" : "belowEditor", maxEntries: cap };
+}

package/src/widget-summary.ts

@@ -0,0 +1,51 @@
+// Counts delegated tasks (launch ids), not stable sessions or registry cap charges.
+import { isStarted, type Recorded, sessionIdOf } from "./results.ts";
+import type { TmuxWindow } from "./tmux.ts";
+import type { VisibleFact, VisibleFacts } from "./tree-view.ts";
+import { windowState } from "./windows.ts";
+
+type Outcome = "done" | "failed" | "stopped" | "missing" | "running" | "unknown";
+function outcome(fact: VisibleFact, windows: TmuxWindow[] | undefined): Outcome {
+	const record: Recorded | undefined = fact.semantic;
+	if (!record || !isStarted(record) || record.accountingOnly) return "unknown";
+	if (record.result) {
+		const status: string = record.result.status;
+		return status === "done" || status === "failed" || status === "stopped" ? status : "unknown";
+	}
+	if (record.closed || record.gone) return "missing";
+	if (fact.entry?.finished || fact.entry?.closed || fact.entry?.closing || fact.entry?.gone) return "unknown";
+	return windowState(windows, record) === "open" ? "running" : "unknown";
+}
+
+function below(facts: VisibleFact[], sessionId: string): VisibleFact[] {
+	const sessions: Set<string> = new Set([sessionId]);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const { record } of facts) {
+			if (!isStarted(record) || !record.identity || !sessions.has(record.identity.parent)) continue;
+			const id: string = sessionIdOf(record);
+			if (!sessions.has(id)) {
+				sessions.add(id);
+				changed = true;
+			}
+		}
+	}
+	return facts.filter(({ record }) => isStarted(record) && record.identity && sessions.has(record.identity.parent));
+}
+
+export function taskSummary(view: VisibleFacts, sessionId: string, windows: TmuxWindow[] | undefined): string {
+	const descendants: VisibleFact[] = below(view.facts, sessionId);
+	if (!descendants.length) return view.complete ? "" : "tasks: coverage unavailable";
+	const counts: Map<Outcome, number> = new Map();
+	const seen: Set<string> = new Set();
+	for (const fact of descendants) {
+		if (seen.has(fact.record.id)) continue;
+		seen.add(fact.record.id);
+		const state: Outcome = outcome(fact, windows);
+		counts.set(state, (counts.get(state) ?? 0) + 1);
+	}
+	const order: Outcome[] = ["failed", "stopped", "missing", "running", "unknown", "done"];
+	const labels: string[] = order.flatMap((state) => (counts.has(state) ? [`${counts.get(state)} ${state}`] : []));
+	return `${seen.size} task${seen.size === 1 ? "" : "s"}: ${labels.join(" · ")}${view.complete ? "" : " · partial coverage"}`;
+}

package/src/widget-title-file.ts

@@ -0,0 +1,127 @@
+// Read foreign native metadata without opening (and potentially migrating) a SessionManager.
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+
+type Title = { name: string | undefined; modified: number };
+type Cursor = {
+	ino: number;
+	size: number;
+	modified: number;
+	offset: number;
+	pending: Buffer;
+	skipLine: boolean;
+	header: boolean;
+	valid: boolean;
+	name: string | undefined;
+};
+const CHUNK_BYTES = 64 * 1024;
+const SCAN_BYTES = 1024 * 1024;
+
+/** Bounded incremental reader. Replacement, truncation and same-size edits restart the scan. */
+export class WidgetTitleFiles {
+	private readonly files = new Map<string, Cursor>();
+
+	clear(): void {
+		this.files.clear();
+	}
+
+	read(path: string | undefined, sessionId: string): Title | undefined {
+		if (!path) return undefined;
+		let fd: number;
+		try {
+			fd = openSync(path, "r");
+		} catch {
+			this.files.delete(path);
+			return undefined;
+		}
+		try {
+			if (!this.matchesHeader(fd, sessionId)) {
+				this.files.delete(path);
+				return undefined;
+			}
+			const stat = fstatSync(fd);
+			let cursor: Cursor | undefined = this.files.get(path);
+			if (
+				!cursor ||
+				cursor.ino !== stat.ino ||
+				stat.size < cursor.size ||
+				(stat.size === cursor.size && stat.mtimeMs !== cursor.modified)
+			) {
+				cursor = {
+					ino: stat.ino,
+					size: stat.size,
+					modified: stat.mtimeMs,
+					offset: 0,
+					pending: Buffer.alloc(0),
+					skipLine: false,
+					header: false,
+					valid: false,
+					name: undefined,
+				};
+				this.files.set(path, cursor);
+			}
+			cursor.size = stat.size;
+			cursor.modified = stat.mtimeMs;
+			this.scan(fd, cursor, sessionId);
+			return cursor.valid ? { name: cursor.name, modified: cursor.modified } : undefined;
+		} catch {
+			this.files.delete(path);
+			return undefined;
+		} finally {
+			closeSync(fd);
+		}
+	}
+
+	private matchesHeader(fd: number, sessionId: string): boolean {
+		const buffer: Buffer = Buffer.alloc(CHUNK_BYTES);
+		const count: number = readSync(fd, buffer, 0, buffer.length, 0);
+		const newline: number = buffer.subarray(0, count).indexOf(10);
+		if (newline < 0) return false;
+		const header: { type?: unknown; id?: unknown } = JSON.parse(buffer.subarray(0, newline).toString("utf8"));
+		return header?.type === "session" && header.id === sessionId;
+	}
+
+	private scan(fd: number, cursor: Cursor, sessionId: string): void {
+		let budget: number = SCAN_BYTES;
+		while (cursor.offset < cursor.size && budget > 0) {
+			const buffer: Buffer = Buffer.alloc(Math.min(CHUNK_BYTES, cursor.size - cursor.offset, budget));
+			const count: number = readSync(fd, buffer, 0, buffer.length, cursor.offset);
+			if (!count) return;
+			cursor.offset += count;
+			budget -= count;
+			this.consume(cursor, buffer.subarray(0, count), sessionId);
+		}
+	}
+
+	private consume(cursor: Cursor, bytes: Buffer, sessionId: string): void {
+		const combined: Buffer = Buffer.concat([cursor.pending, bytes]);
+		let start = 0;
+		for (let end: number = combined.indexOf(10); end !== -1; end = combined.indexOf(10, start)) {
+			if (!cursor.skipLine && end - start <= CHUNK_BYTES)
+				this.line(cursor, combined.subarray(start, end).toString("utf8"), sessionId);
+			cursor.skipLine = false;
+			start = end + 1;
+		}
+		cursor.pending = combined.subarray(start);
+		if (cursor.pending.length > CHUNK_BYTES) {
+			cursor.pending = Buffer.alloc(0);
+			cursor.skipLine = true;
+		}
+	}
+
+	private line(cursor: Cursor, text: string, sessionId: string): void {
+		if (cursor.header && !text.includes('"session_info"')) return;
+		let entry: { type?: unknown; id?: unknown; name?: unknown };
+		try {
+			entry = JSON.parse(text);
+		} catch {
+			return;
+		}
+		if (!entry || typeof entry !== "object") return;
+		if (!cursor.header) {
+			cursor.header = true;
+			cursor.valid = entry.type === "session" && entry.id === sessionId;
+		} else if (cursor.valid && entry.type === "session_info" && typeof entry.name === "string") {
+			cursor.name = entry.name;
+		}
+	}
+}

package/src/widget-title.ts

@@ -0,0 +1,118 @@
+// Disposable native-title mirror for unflushed / --no-session runtimes.
+// No membership, hierarchy, task state, ownership lock or activity lives here.
+import { execFileSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { writeState } from "./local-state.ts";
+
+type Mirror = { version: 1; sessionId: string; generation: string; pid: number; start: string; name: string };
+const MAX_BYTES = 16 * 1024;
+
+function processStart(pid: number): string | undefined {
+	try {
+		const value: string = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+			encoding: "utf8",
+			timeout: 1000,
+			// Compare identical formatting even across differently configured tmux environments.
+			env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+			stdio: ["ignore", "pipe", "ignore"],
+		}).trim();
+		return value || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function titleMirrorPath(sessionId: string): string {
+	const key: string = createHash("sha256").update(sessionId).digest("hex");
+	return join(getAgentDir(), "squire", "session-titles", `${key}.json`);
+}
+
+function readMirror(sessionId: string): Mirror | undefined {
+	try {
+		const file: string = titleMirrorPath(sessionId);
+		if (statSync(file).size > MAX_BYTES) return undefined;
+		const value: Partial<Mirror> = JSON.parse(readFileSync(file, "utf8"));
+		if (
+			value.version !== 1 ||
+			value.sessionId !== sessionId ||
+			typeof value.name !== "string" ||
+			typeof value.generation !== "string" ||
+			!Number.isSafeInteger(value.pid) ||
+			typeof value.start !== "string"
+		)
+			return undefined;
+		return value as Mirror;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Positive checks expire without sliding on reads; title edits themselves are never cached. */
+export const TITLE_LIVENESS_CACHE_MS = 5000;
+type Verdict = { matches: boolean; expires: number };
+type MirrorChecks = { now: () => number; start: (pid: number) => string | undefined };
+
+export class WidgetTitleMirrors {
+	private readonly checks: MirrorChecks;
+	private readonly verdicts = new Map<string, Verdict>();
+
+	constructor(checks: Partial<MirrorChecks> = {}) {
+		this.checks = { now: (): number => performance.now(), start: processStart, ...checks };
+	}
+
+	clear(): void {
+		this.verdicts.clear();
+	}
+
+	read(sessionId: string): string | undefined {
+		const value: Mirror | undefined = readMirror(sessionId);
+		// An empty mirror can only fall back to recorded identity; never spawn ps for it.
+		if (!value?.name) return undefined;
+		const key: string = JSON.stringify([value.pid, value.start]);
+		const now: number = this.checks.now();
+		let verdict: Verdict | undefined = this.verdicts.get(key);
+		if (!verdict || now >= verdict.expires) {
+			verdict = { matches: this.checks.start(value.pid) === value.start, expires: now + TITLE_LIVENESS_CACHE_MS };
+			this.verdicts.set(key, verdict);
+		}
+		return verdict.matches ? value.name : undefined;
+	}
+}
+
+const titleMirrors = new WidgetTitleMirrors();
+export function mirroredTitle(sessionId: string): string | undefined {
+	return titleMirrors.read(sessionId);
+}
+
+/** Best effort only. Runtime generations prevent old shutdown from removing a replacement. */
+export function titlePublisher(sessionId: string): { publish(name: string | undefined): void; stop(): void } {
+	const generation: string = randomUUID();
+	const start: string | undefined = processStart(process.pid);
+	return {
+		publish(name: string | undefined): void {
+			if (!start) return;
+			try {
+				writeState(titleMirrorPath(sessionId), {
+					version: 1,
+					sessionId,
+					generation,
+					pid: process.pid,
+					start,
+					name: (name ?? "").slice(0, 2048),
+				} satisfies Mirror);
+			} catch {
+				/* Title availability must never affect a delegated task. */
+			}
+		},
+		stop(): void {
+			try {
+				if (readMirror(sessionId)?.generation === generation) unlinkSync(titleMirrorPath(sessionId));
+			} catch {
+				/* Already absent or unavailable. */
+			}
+		},
+	};
+}