rinco-pi-hud 1.0.0

package/extensions/hud/index.ts

@@ -0,0 +1,466 @@
+import type { ExtensionAPI, ExtensionContext, Skill } from "@earendil-works/pi-coding-agent";
+import registerCodexUsage from "./telemetry/codex-usage/index.js";
+import { countConfigEntries } from "./config/config-counts.js";
+import {
+	type ColorSourcesConfig,
+	type ContextStyle,
+	type ExtensionStatusColorMode,
+	type ExtensionStatusPlacement,
+	ensureConfigExists,
+	type FooterSegmentsConfig,
+	type GitBranchConfig,
+	type IconMode,
+	loadConfig,
+	type PathDisplayConfig,
+	type PolishedTuiConfig,
+	type SeparatorStyle,
+	saveColorSourcesPatch,
+	saveContextStylePatch,
+	saveExtensionStatusColorMode,
+	saveExtensionStatusPlacement,
+	saveFooterFormatPatch,
+	saveFooterSegmentsPatch,
+	saveGitBranchPatch,
+	saveIconsModePatch,
+	savePathDisplayPatch,
+	saveSeparatorPatch,
+	saveUiFeaturesPatch,
+	type UiFeaturesConfig,
+} from "./config/config.js";
+import { installFooter } from "./footer/index.js";
+import { buildSessionDurationLabel, invalidateUsageTotalsCache } from "./telemetry/format.js";
+import { emptyGitStatus, readGitStatus } from "./segments/git.js";
+import { LiveContextController } from "./session/live-context.js";
+import { readPackageVersionResult } from "./segments/package-version.js";
+import {
+	createProjectRefreshScheduler,
+	type ScheduleProjectRefreshOptions,
+	type StopProjectRefreshInterval,
+	startProjectRefreshInterval,
+} from "./state/project-refresh.js";
+import { applyProjectRefreshToState } from "./segments/project-state.js";
+import { readRuntimeInfo } from "./segments/runtime.js";
+import { isLiveExtensionContext } from "./session/context.js";
+import { SessionLifecycle } from "./session/lifecycle.js";
+import { SkillActivityTracker, type SkillReference } from "./segments/skill-activity.js";
+import { registerZentuiSettingsCommand } from "./commands/settings.js";
+import { createInitialState, type FooterState, syncState } from "./state/index.js";
+import { findToolTarget, resetTelemetryState, updateTelemetryState } from "./state/telemetry.js";
+
+function isTuiContext(ctx: ExtensionContext): boolean {
+	try {
+		const mode = (ctx as ExtensionContext & { mode?: string }).mode;
+		return ctx.hasUI && (mode === undefined || mode === "tui");
+	} catch {
+		return false;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	const state: FooterState = createInitialState(emptyGitStatus());
+	const sessionLifecycle = new SessionLifecycle();
+	const skillActivity = new SkillActivityTracker();
+
+	let currentConfig: PolishedTuiConfig = loadConfig();
+	let requestFooterRender: (() => void) | undefined;
+	let getActiveExtensionStatuses: () => ReadonlyMap<string, string> = () => new Map();
+	let stopRefreshInterval: StopProjectRefreshInterval = () => {};
+	let footerInstalled = false;
+	let stopSessionTimer: () => void = () => {};
+	let lastDurationLabel = "";
+	let lastProjectCwd: string | undefined;
+
+	const refresh = () => {
+		if (sessionLifecycle.isCurrent()) requestFooterRender?.();
+	};
+	// Pi hands every event handler a brand-new ctx object, so identity comparisons
+	// with the session_start ctx would silently drop later updates.
+	const isActiveSessionContext = (ctx: ExtensionContext): boolean => {
+		return sessionLifecycle.isCurrent() && isLiveExtensionContext(ctx);
+	};
+	const liveContext = new LiveContextController(sessionLifecycle, refresh);
+	const getCurrentConfig = () => currentConfig;
+	const syncFooterState = (ctx: ExtensionContext) =>
+		syncState(state, ctx, currentConfig.icons.cacheHit);
+	const availableSkillReferences = (promptSkills: readonly Skill[] = []): SkillReference[] => {
+		const byName = new Map<string, SkillReference>();
+		try {
+			for (const command of pi.getCommands()) {
+				if (command.source !== "skill" || !command.name.startsWith("skill:")) continue;
+				const name = command.name.slice("skill:".length);
+				if (name && command.sourceInfo.path) {
+					byName.set(name, { name, filePath: command.sourceInfo.path });
+				}
+			}
+		} catch {}
+		for (const skill of promptSkills) {
+			byName.set(skill.name, { name: skill.name, filePath: skill.filePath });
+		}
+		return [...byName.values()];
+	};
+	const updateSkillCounts = (ctx: ExtensionContext, promptSkills: readonly Skill[] = []) => {
+		skillActivity.syncAvailable(availableSkillReferences(promptSkills), ctx.cwd);
+		state.skillCounts = skillActivity.counts();
+	};
+	const restoreSkillActivity = (ctx: ExtensionContext) => {
+		updateSkillCounts(ctx);
+		skillActivity.restoreFromEntries(ctx.sessionManager.getBranch(), ctx.cwd);
+		state.skillCounts = skillActivity.counts();
+	};
+
+	type ProjectRefreshTarget = { cwd: string; generation: number };
+	const refreshProjectState = async ({ cwd, generation }: ProjectRefreshTarget) => {
+		if (!sessionLifecycle.isCurrent(generation)) return;
+		const gitCommitConfig = currentConfig.gitCommit;
+		const gitMetricsConfig = currentConfig.gitMetrics;
+		const segments = currentConfig.footerSegments;
+		const fmt = currentConfig.footerFormat;
+		const formatNeedsTag = /\$\{?(?:git_tag|tag)\b/.test(fmt);
+		const formatNeedsCommit = /\$\{?(?:git_commit|commit)\b/.test(fmt);
+		const formatNeedsMetrics = /\$\{?(?:git_metrics|git_added|git_deleted)\b/.test(fmt);
+		const formatNeedsPackage = /\$\{?(?:package|package_version)\b/.test(fmt);
+		const wantExactTag =
+			((segments.gitCommit || formatNeedsCommit) && gitCommitConfig.showTag) || formatNeedsTag;
+		const wantMetrics = segments.gitMetrics || formatNeedsMetrics;
+		const wantPackage = segments.packageVersion || formatNeedsPackage;
+		const [git, runtime, packageVersion, configCounts] = await Promise.all([
+			readGitStatus(cwd, {
+				readExactTag: wantExactTag,
+				readMetrics: wantMetrics,
+				ignoreSubmodules: gitMetricsConfig.ignoreSubmodules,
+			}),
+			readRuntimeInfo(cwd),
+			wantPackage ? readPackageVersionResult(cwd) : Promise.resolve(undefined),
+			Promise.resolve(countConfigEntries(cwd)),
+		]);
+		if (!sessionLifecycle.isCurrent(generation)) return;
+		state.configCounts = configCounts;
+		lastProjectCwd = applyProjectRefreshToState(state, {
+			cwd,
+			previousCwd: lastProjectCwd,
+			git,
+			runtime,
+			packageVersion,
+		});
+	};
+
+	const projectRefreshScheduler = createProjectRefreshScheduler(refreshProjectState, refresh);
+	const scheduleProjectRefresh = (
+		ctx: ExtensionContext,
+		options?: ScheduleProjectRefreshOptions,
+	) => {
+		const generation = sessionLifecycle.currentGeneration();
+		if (!sessionLifecycle.isCurrent(generation)) return;
+		projectRefreshScheduler.schedule({ cwd: ctx.cwd, generation }, options);
+	};
+
+	const refreshInteractiveState = (ctx: ExtensionContext, project = false) => {
+		if (!sessionLifecycle.isCurrent() || !ctx.hasUI) return;
+		syncFooterState(ctx);
+		if (project && currentConfig.features.statusLine) scheduleProjectRefresh(ctx);
+		refresh();
+	};
+
+	const stopProjectRefresh = () => {
+		stopRefreshInterval();
+		stopRefreshInterval = () => {};
+		projectRefreshScheduler.stop();
+	};
+
+	const startSessionTimer = () => {
+		stopSessionTimer();
+		lastDurationLabel = "";
+		const segments = currentConfig.footerSegments;
+		const format = currentConfig.footerFormat ?? "";
+		const needsWallClock = segments.time || /\$\{?time\b/.test(format);
+		const needsDuration =
+			segments.sessionDuration || /\$\{?(?:session_duration|duration)\b/.test(format);
+		const needsActivityClock =
+			segments.toolActivity ||
+			segments.agentActivity ||
+			/\$\{?(?:running_tools|active_agents|agents)\b/.test(format);
+		if (
+			!currentConfig.features.statusLine ||
+			!(needsWallClock || needsDuration || needsActivityClock)
+		) return;
+
+		const timer = setInterval(() => {
+			if (!sessionLifecycle.isCurrent()) return;
+			if (needsWallClock || needsActivityClock) {
+				refresh();
+				return;
+			}
+			const label = state.sessionStartEpoch
+				? buildSessionDurationLabel(state.sessionStartEpoch)
+				: "";
+			if (label === lastDurationLabel) return;
+			lastDurationLabel = label;
+			refresh();
+		}, 1000);
+		timer.unref?.();
+		stopSessionTimer = () => {
+			clearInterval(timer);
+			stopSessionTimer = () => {};
+		};
+	};
+
+	const installStatusLine = (ctx: ExtensionContext) => {
+		if (footerInstalled) return;
+		installFooter(ctx, state, getCurrentConfig, {
+			setRequestRender: (fn) => {
+				requestFooterRender = fn;
+			},
+			scheduleProjectRefresh,
+			setExtensionStatusesGetter(fn) {
+				getActiveExtensionStatuses = fn ?? (() => new Map());
+			},
+			getLiveContext: () => liveContext.get(),
+		});
+		footerInstalled = true;
+		stopProjectRefresh();
+		stopRefreshInterval = startProjectRefreshInterval(currentConfig.projectRefreshIntervalMs, () =>
+			scheduleProjectRefresh(ctx),
+		);
+		scheduleProjectRefresh(ctx, { force: true });
+		refresh();
+		startSessionTimer();
+	};
+
+	const uninstallStatusLine = (ctx: ExtensionContext) => {
+		stopSessionTimer();
+		stopProjectRefresh();
+		ctx.ui.setFooter(undefined);
+		footerInstalled = false;
+		requestFooterRender = undefined;
+		getActiveExtensionStatuses = () => new Map();
+	};
+
+	const applyConfiguredUi = (ctx: ExtensionContext) => {
+		if (!isTuiContext(ctx)) return;
+		if (currentConfig.features.statusLine) installStatusLine(ctx);
+		else if (footerInstalled) uninstallStatusLine(ctx);
+	};
+
+	const installUi = (ctx: ExtensionContext) => {
+		if (!isTuiContext(ctx)) return;
+		footerInstalled = false;
+		ensureConfigExists();
+		currentConfig = loadConfig();
+		syncFooterState(ctx);
+		stopProjectRefresh();
+		applyConfiguredUi(ctx);
+		refresh();
+	};
+
+	const cleanupUi = (ctx?: ExtensionContext) => {
+		if (!ctx || !sessionLifecycle.isCurrent()) return;
+		sessionLifecycle.shutdown();
+		stopSessionTimer();
+		stopProjectRefresh();
+		requestFooterRender = undefined;
+		getActiveExtensionStatuses = () => new Map();
+		if (isTuiContext(ctx)) ctx.ui.setFooter(undefined);
+		footerInstalled = false;
+	};
+
+	const syncInteractiveState = (_event: unknown, ctx: ExtensionContext) => {
+		refreshInteractiveState(ctx);
+	};
+	const syncInteractiveAndProjectState = (_event: unknown, ctx: ExtensionContext) => {
+		refreshInteractiveState(ctx, true);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		sessionLifecycle.start();
+		liveContext.clear();
+		skillActivity.reset();
+		restoreSkillActivity(ctx);
+		state.sessionStartEpoch = Date.now();
+		state.codexUsageStatus = undefined;
+		state.telemetry = resetTelemetryState(state.telemetry, {
+			sessionName: ctx.sessionManager.getSessionName?.(),
+			thinkingLevel: pi.getThinkingLevel(),
+			modelSupportsReasoning: Boolean(ctx.model?.reasoning),
+		});
+		invalidateUsageTotalsCache();
+		lastProjectCwd = undefined;
+		installUi(ctx);
+	});
+
+	pi.on("resources_discover", (_event, ctx) => {
+		sessionLifecycle.defer(() => {
+			if (!isActiveSessionContext(ctx)) return;
+			updateSkillCounts(ctx);
+			refresh();
+		});
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		updateSkillCounts(ctx, event.systemPromptOptions.skills ?? []);
+		skillActivity.activateFromPrompt(event.prompt, ctx.cwd);
+		state.skillCounts = skillActivity.counts();
+		refreshInteractiveState(ctx);
+	});
+
+	registerZentuiSettingsCommand(pi, {
+		getConfig: getCurrentConfig,
+		setColorSources(patch: Partial<ColorSourcesConfig>) {
+			currentConfig = saveColorSourcesPatch(patch);
+		},
+		setUiFeatures(patch: Partial<UiFeaturesConfig>, ctx: ExtensionContext) {
+			currentConfig = saveUiFeaturesPatch(patch);
+			applyConfiguredUi(ctx);
+		},
+		setFooterSegments(patch: Partial<FooterSegmentsConfig>) {
+			currentConfig = saveFooterSegmentsPatch(patch);
+			startSessionTimer();
+		},
+		setFooterFormat(value: string) {
+			currentConfig = saveFooterFormatPatch(value);
+			startSessionTimer();
+		},
+		setIconMode(mode: IconMode) {
+			currentConfig = saveIconsModePatch(mode);
+		},
+		setContextStyle(style: ContextStyle) {
+			currentConfig = saveContextStylePatch(style);
+		},
+		setSeparator(separator: SeparatorStyle) {
+			currentConfig = saveSeparatorPatch(separator);
+		},
+		setPathDisplay(patch: Partial<PathDisplayConfig>) {
+			currentConfig = savePathDisplayPatch(patch);
+		},
+		setGitBranch(patch: Partial<GitBranchConfig>) {
+			currentConfig = saveGitBranchPatch(patch);
+		},
+		getActiveExtensionStatuses() {
+			return getActiveExtensionStatuses();
+		},
+		setExtensionStatusPlacement(key: string, placement: ExtensionStatusPlacement) {
+			currentConfig = saveExtensionStatusPlacement(key, placement);
+		},
+		setExtensionStatusColorMode(key: string, colorMode: ExtensionStatusColorMode) {
+			currentConfig = saveExtensionStatusColorMode(key, colorMode);
+		},
+		requestRender() {
+			refresh();
+		},
+	});
+
+	registerCodexUsage(pi, (ctx, value) => {
+		if (!isActiveSessionContext(ctx)) return;
+		state.codexUsageStatus = value;
+		refresh();
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		liveContext.clear();
+		state.codexUsageStatus = undefined;
+		cleanupUi(ctx);
+	});
+
+	const syncInteractiveAndProjectStateWithUsage = (_event: unknown, ctx: ExtensionContext) => {
+		invalidateUsageTotalsCache();
+		refreshInteractiveState(ctx, true);
+	};
+
+	pi.on("agent_start", (event, ctx) => {
+		liveContext.clear();
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "agent-start",
+			at: Date.now(),
+		});
+		syncInteractiveState(event, ctx);
+	});
+	pi.on("agent_end", (event, ctx) => {
+		liveContext.clear();
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "agent-end",
+			at: Date.now(),
+		});
+		syncInteractiveAndProjectState(event, ctx);
+	});
+	pi.on("model_select", (event, ctx) => {
+		liveContext.clear();
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "metadata",
+			modelSupportsReasoning: Boolean(event.model?.reasoning),
+		});
+		syncInteractiveState(event, ctx);
+	});
+	pi.on("thinking_level_select", (event, ctx) => {
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "metadata",
+			thinkingLevel: event.level,
+		});
+		syncInteractiveState(event, ctx);
+	});
+	pi.on("session_info_changed", (event, ctx) => {
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "metadata",
+			sessionName: event.name,
+		});
+		syncInteractiveState(event, ctx);
+	});
+	pi.on("turn_start", (event, ctx) => {
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "turn-start",
+			turnIndex: event.turnIndex,
+		});
+		syncInteractiveState(event, ctx);
+	});
+	pi.on("message_update", (event) => {
+		liveContext.update(event.message);
+	});
+	pi.on("message_end", (event, ctx) => {
+		if (
+			event.message.role === "assistant" &&
+			(event.message.stopReason === "error" || event.message.stopReason === "aborted")
+		) {
+			liveContext.clear();
+		}
+		syncInteractiveAndProjectStateWithUsage(event, ctx);
+	});
+	pi.on("tool_execution_start", (event, ctx) => {
+		liveContext.clear();
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "tool-call",
+			toolCallId: event.toolCallId,
+			name: event.toolName,
+			args:
+				event.args && typeof event.args === "object"
+					? (event.args as Record<string, unknown>)
+					: undefined,
+			at: Date.now(),
+		});
+		syncInteractiveState(event, ctx);
+	});
+	pi.on("tool_execution_end", (event, ctx) => {
+		// `ToolExecutionEndEvent` does not carry `args`; recover the original
+		// `read` target recorded at `tool_execution_start` from telemetry state.
+		if (!event.isError && event.toolName === "read") {
+			const path = findToolTarget(state.telemetry, event.toolCallId);
+			if (typeof path === "string") {
+				skillActivity.activateFromRead(path, ctx.cwd);
+				state.skillCounts = skillActivity.counts();
+			}
+		}
+		state.telemetry = updateTelemetryState(state.telemetry, {
+			type: "tool-result",
+			toolCallId: event.toolCallId,
+			isError: event.isError,
+			at: Date.now(),
+		});
+		syncInteractiveAndProjectState(event, ctx);
+	});
+	pi.on("session_compact", (event, ctx) => {
+		liveContext.clear();
+		syncInteractiveAndProjectStateWithUsage(event, ctx);
+	});
+	pi.on("session_tree", (event, ctx) => {
+		liveContext.clear();
+		restoreSkillActivity(ctx);
+		syncInteractiveAndProjectStateWithUsage(event, ctx);
+	});
+}

package/extensions/hud/segments/extension-status.ts

@@ -0,0 +1,88 @@
+import { stripVTControlCharacters } from "node:util";
+import type {
+	ExtensionStatusColorMode,
+	ExtensionStatusPlacement,
+	PolishedTuiConfig,
+} from "../config/config.js";
+import { getExtensionStatusColorMode, getExtensionStatusPlacement } from "../config/config.js";
+
+export type ExtensionStatusSegment = {
+	key: string;
+	text: string;
+	placement: ExtensionStatusPlacement;
+	colorMode: ExtensionStatusColorMode;
+};
+
+export type ExtensionStatusSegmentsByPlacement = {
+	left: ExtensionStatusSegment[];
+	middle: ExtensionStatusSegment[];
+	right: ExtensionStatusSegment[];
+};
+
+const safeSgrPattern = /\x1b\[[0-9;:]*m/g;
+const sgrPlaceholderPattern = /__ZENTUI_SGR_(\d+)__/g;
+
+function compareKeys(a: ExtensionStatusSegment, b: ExtensionStatusSegment): number {
+	return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+}
+
+function normalizeStatusWhitespace(value: string): string {
+	return value
+		.replace(/[\r\n\t\f\v]+/g, " ")
+		.replace(/[\u0000-\u001f\u007f-\u009f]/g, "")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function sanitizeExtensionStatusText(value: string): string {
+	return normalizeStatusWhitespace(stripVTControlCharacters(value));
+}
+
+function hasVisibleStatusText(value: string): boolean {
+	return sanitizeExtensionStatusText(value).length > 0;
+}
+
+export function sanitizeExtensionStatusOriginalText(value: string): string {
+	const safeSequences: string[] = [];
+	const protectedValue = value.replace(safeSgrPattern, (sequence) => {
+		const index = safeSequences.push(sequence) - 1;
+		return `__ZENTUI_SGR_${index}__`;
+	});
+	const cleaned = normalizeStatusWhitespace(stripVTControlCharacters(protectedValue));
+	const restored = cleaned.replace(sgrPlaceholderPattern, (_match, indexText: string) => {
+		const index = Number.parseInt(indexText, 10);
+		return safeSequences[index] ?? "";
+	});
+
+	return hasVisibleStatusText(restored) ? restored : "";
+}
+
+export function collectExtensionStatusSegments(
+	statuses: ReadonlyMap<string, string>,
+	config: PolishedTuiConfig,
+): ExtensionStatusSegmentsByPlacement {
+	const segments: ExtensionStatusSegmentsByPlacement = {
+		left: [],
+		middle: [],
+		right: [],
+	};
+
+	for (const [key, value] of statuses.entries()) {
+		const placement = getExtensionStatusPlacement(config, key);
+		if (placement === "off") continue;
+
+		const colorMode = getExtensionStatusColorMode(config, key);
+		const text =
+			colorMode === "original"
+				? sanitizeExtensionStatusOriginalText(value)
+				: sanitizeExtensionStatusText(value);
+		if (!text) continue;
+
+		segments[placement].push({ key, text, placement, colorMode });
+	}
+
+	segments.left.sort(compareKeys);
+	segments.middle.sort(compareKeys);
+	segments.right.sort(compareKeys);
+	return segments;
+}