@rexvane/piweb 0.3.1

package/src/lib/growth-tracker.ts

@@ -0,0 +1,328 @@
+/**
+ * growth-tracker：把 pi 会话事件接到项目生长快照引擎上。
+ *
+ * - agent_start：确保本会话有基线步，并启动工作区目录监听
+ * - 改盘类工具（bash / powershell / write / edit / 未知扩展工具）结束：去抖 200ms 拍一张快照（并行工具合并成一步）
+ * - agent_end：兜底再拍一次（tree 没变就不记步）
+ * - 目录监听：改盘类工具运行期间看到的新路径先以「生成中」推给浏览器；空闲时的改动去抖 1.5s 记成「外部修改」
+ * 快照失败不影响 pi，只向浏览器报一次错；项目过大 / 没有 git 时本会话停用。
+ */
+import fs from "node:fs";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { GrowthError, hasSessionSteps, isExcludedRelPath, snapshot } from "./growth-service";
+import type { GrowthStep, GrowthStepKind, WebEvent } from "./types";
+
+const READ_ONLY_TOOLS = new Set(["read", "grep", "find", "ls"]);
+const SNAPSHOT_DEBOUNCE_MS = 200;
+const PENDING_THROTTLE_MS = 300;
+const EXTERNAL_DEBOUNCE_MS = 1500;
+const MAX_PENDING = 500;
+const ERROR_THROTTLE_MS = 60_000;
+export const GROWTH_TRACKER_VERSION = 3;
+
+interface QueuedMeta {
+	kind: GrowthStepKind;
+	label: string;
+	toolCallId?: string;
+	toolName?: string;
+}
+
+export interface GrowthTracker {
+	version: number;
+	getError(): string | null;
+	/** 在首轮 prompt 前完成基线，避免快速写盘被误算进基线。 */
+	prepare(): Promise<void>;
+	onEvent(evt: AgentSessionEvent): void;
+	/** 手动快照（API 触发）；返回记下的步，tree 没变返回 null */
+	snapshotNow(label?: string): Promise<GrowthStep | null>;
+	dispose(): void;
+}
+
+export function isMutatingTool(name: string): boolean {
+	return !READ_ONLY_TOOLS.has(name.toLowerCase());
+}
+
+/** 「bash · mkdir -p src」：工具名 + 命令首行 / 相对路径，截到 60 字 */
+export function labelForTool(cwd: string, name: string, args: unknown): string {
+	const a = args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+	let detail = "";
+	if (typeof a.command === "string") detail = a.command;
+	else if (typeof a.path === "string") detail = relativeToCwd(cwd, a.path);
+	else if (typeof a.file_path === "string") detail = relativeToCwd(cwd, a.file_path);
+	detail = detail.split("\n").map((s) => s.trim()).find(Boolean) ?? "";
+	detail = detail.replace(/\s+/g, " ");
+	if (detail.length > 60) detail = `${detail.slice(0, 59)}…`;
+	return detail ? `${name} · ${detail}` : name;
+}
+
+function relativeToCwd(cwd: string, p: string): string {
+	if (!path.isAbsolute(p)) return p.replace(/\\/g, "/");
+	const rel = path.relative(cwd, p);
+	if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return p.replace(/\\/g, "/");
+	return rel.replace(/\\/g, "/");
+}
+
+/** 工具链自动生成/频繁改写的文件：进 pending 只会制造蓝点噪音，快照侧由 .gitignore 与影子仓库 exclude 兜底 */
+const WATCHER_FILE_NOISE = /(?:^|\/)(?:\.DS_Store|Thumbs\.db|[^/]*\.log|[^/]*\.tsbuildinfo|next-env\.d\.ts)$/;
+
+export function createGrowthTracker(opts: { cwd: string; sessionPath: string; publish: (evt: WebEvent) => void }): GrowthTracker {
+	const { cwd, sessionPath, publish } = opts;
+	const running = new Set<string>();
+	const argsById = new Map<string, unknown>();
+	const queue: QueuedMeta[] = [];
+	const pending = new Set<string>();
+	let pendingStats = 0;
+	let flushTimer: ReturnType<typeof setTimeout> | undefined;
+	let pendingTimer: ReturnType<typeof setTimeout> | undefined;
+	let externalTimer: ReturnType<typeof setTimeout> | undefined;
+	let watcher: fs.FSWatcher | null = null;
+	let watcherFailed = false;
+	let baselineChecked = false;
+	let baselinePending: Promise<void> | null = null;
+	let disabled = false;
+	let disabledFailure: GrowthError | null = null;
+	let disposed = false;
+	let lastErrorAt = 0;
+	let errorActive = false;
+	let lastErrorMessage: string | null = null;
+	let chain: Promise<void> = Promise.resolve();
+
+	// 快照失败不打扰用户（项目栏退化成普通文件树 + 查看器）：只在服务端日志记一次，没 git / 项目过大就停用本会话的跟踪
+	const reportError = (error: unknown) => {
+		const message = error instanceof Error ? error.message : String(error);
+		const terminal = error instanceof GrowthError && (error.code === "unavailable" || error.code === "too-large");
+		if (terminal) {
+			disabled = true;
+			disabledFailure = error;
+			try {
+				watcher?.close();
+			} catch {
+				/* ignore watcher close errors after a terminal snapshot failure */
+			}
+			watcher = null;
+			if (flushTimer) clearTimeout(flushTimer);
+			if (pendingTimer) clearTimeout(pendingTimer);
+			if (externalTimer) clearTimeout(externalTimer);
+			flushTimer = pendingTimer = externalTimer = undefined;
+			queue.length = 0;
+			running.clear();
+			argsById.clear();
+			if (pending.size) {
+				pending.clear();
+				publish({ type: "growth_pending", paths: [], ts: Date.now() });
+			}
+		}
+		errorActive = true;
+		lastErrorMessage = message;
+		const now = Date.now();
+		if (!terminal && now - lastErrorAt < ERROR_THROTTLE_MS) return;
+		lastErrorAt = now;
+		console.warn(`[piweb] growth snapshot failed for ${cwd}: ${message}`);
+		publish({ type: "growth_error", message, ts: now });
+	};
+
+	const publishPending = () => {
+		pendingTimer = undefined;
+		publish({ type: "growth_pending", paths: [...pending].slice(0, 200), ts: Date.now() });
+	};
+
+	const enqueue = (fn: () => Promise<void>) => {
+		chain = chain.then(fn, fn).catch(reportError);
+		return chain;
+	};
+
+	// 真正拍快照的函数不能再 enqueue（链上任务里嵌套排队会等自己，整条链永久卡死）
+	const doRecord = async (meta: QueuedMeta, force = false) => {
+		if (disabled || disposed) return;
+		const step = await snapshot(cwd, { ...meta, session: sessionPath, force });
+		if (errorActive) {
+			errorActive = false;
+			lastErrorMessage = null;
+			publish({ type: "growth_error", message: null, ts: Date.now() });
+		}
+		if (!step || disposed) return;
+		publish({ type: "growth", step, ts: Date.now() });
+		if (pending.size) {
+			pending.clear();
+			if (pendingTimer) clearTimeout(pendingTimer);
+			publishPending();
+		}
+	};
+	const record = (meta: QueuedMeta, force = false) => enqueue(() => doRecord(meta, force));
+
+	const ensureBaseline = (): Promise<void> => {
+		if (baselineChecked) return chain;
+		if (baselinePending) return baselinePending;
+		baselinePending = enqueue(async () => {
+			if (disabled || disposed) return;
+			if (!(await hasSessionSteps(cwd, sessionPath))) await doRecord({ kind: "baseline", label: "" }, true);
+			baselineChecked = true;
+		});
+		void baselinePending.finally(() => { baselinePending = null; });
+		return baselinePending;
+	};
+
+	const flush = () => {
+		flushTimer = undefined;
+		const metas = queue.splice(0);
+		if (!metas.length) return;
+		const tools = metas.filter((x) => x.kind === "tool");
+		const head = tools[0] ?? metas[0];
+		const extra = tools.length > 1 ? ` +${tools.length - 1}` : "";
+		void record({ kind: head.kind, label: `${head.label}${extra}`, toolCallId: head.toolCallId, toolName: head.toolName });
+	};
+
+	const schedule = (meta: QueuedMeta) => {
+		if (disabled) return;
+		if (externalTimer) {
+			clearTimeout(externalTimer);
+			externalTimer = undefined;
+		}
+		queue.push(meta);
+		if (flushTimer) clearTimeout(flushTimer);
+		flushTimer = setTimeout(flush, SNAPSHOT_DEBOUNCE_MS);
+	};
+
+	const onFsChange = (_type: string, filename: string | Buffer | null) => {
+		if (disabled || disposed) return;
+		const rel = filename == null ? "" : String(filename).replace(/\\/g, "/");
+		if (rel && (isExcludedRelPath(rel) || WATCHER_FILE_NOISE.test(rel))) return;
+		if (running.size > 0) {
+			if (!rel || pending.size + pendingStats >= MAX_PENDING) return;
+			pendingStats += 1;
+			// fs.watch 回调不能同步 stat；目录标记允许异步到达。
+			void fs.promises.stat(path.join(cwd, rel)).then(
+				(info) => info.isDirectory(),
+				() => false,
+			).then((isDir) => {
+				if (disposed || disabled) return;
+				const livePath = isDir ? `${rel}/` : rel;
+				if (pending.size >= MAX_PENDING || pending.has(livePath)) return;
+				pending.add(livePath);
+				if (!pendingTimer) pendingTimer = setTimeout(publishPending, PENDING_THROTTLE_MS);
+			}).finally(() => { pendingStats -= 1; });
+			return;
+		}
+		// 工具刚结束、快照还没拍：这次改动归它，不另记外部修改
+		if (queue.length || flushTimer) return;
+		if (externalTimer) clearTimeout(externalTimer);
+		externalTimer = setTimeout(() => {
+			externalTimer = undefined;
+			if (running.size > 0 || queue.length) return;
+			void record({ kind: "external", label: "" });
+		}, EXTERNAL_DEBOUNCE_MS);
+	};
+
+	const startWatcher = () => {
+		if (watcher || watcherFailed || disabled) return;
+		try {
+			// Watch the canonical path: on Windows an 8.3 short name (RUNNER~1) can make
+			// libuv's directory watcher compare mismatched spellings and crash the process.
+			let watchRoot = cwd;
+			try {
+				watchRoot = realpathSync.native(cwd);
+			} catch {
+				/* keep the given path when it cannot be resolved */
+			}
+			watcher = fs.watch(watchRoot, { recursive: true, persistent: false }, onFsChange);
+			watcher.on("error", () => {
+				watcherFailed = true;
+				try {
+					watcher?.close();
+				} catch {
+					/* ignore */
+				}
+				watcher = null;
+			});
+		} catch {
+			watcherFailed = true;
+			watcher = null;
+		}
+	};
+
+	return {
+		version: GROWTH_TRACKER_VERSION,
+		getError: () => lastErrorMessage,
+		async prepare() {
+			startWatcher();
+			await ensureBaseline();
+		},
+		onEvent(evt) {
+			if (disposed || disabled) return;
+			switch (evt.type) {
+				case "agent_start":
+					startWatcher();
+					void ensureBaseline();
+					break;
+				case "tool_execution_start": {
+					if (!isMutatingTool(evt.toolName)) break;
+					running.add(evt.toolCallId);
+					if (argsById.size > 64) argsById.delete(argsById.keys().next().value as string);
+					argsById.set(evt.toolCallId, (evt as { args?: unknown }).args);
+					if (externalTimer) {
+						clearTimeout(externalTimer);
+						externalTimer = undefined;
+					}
+					break;
+				}
+				case "tool_execution_end": {
+					if (!isMutatingTool(evt.toolName)) break;
+					running.delete(evt.toolCallId);
+					const args = argsById.get(evt.toolCallId);
+					argsById.delete(evt.toolCallId);
+					schedule({ kind: "tool", label: labelForTool(cwd, evt.toolName, args), toolCallId: evt.toolCallId, toolName: evt.toolName });
+					break;
+				}
+				case "agent_end":
+					running.clear();
+					// 先落下本轮最后一批工具快照，再写不依赖文件变化的轮次终点。
+					if (flushTimer) clearTimeout(flushTimer);
+					flush();
+					// 无文件变更的回合也持久化终点，轮数才能与真实用户轮次一致。
+					if (!evt.willRetry) void enqueue(() => doRecord({ kind: "turn", label: "" }, true));
+					break;
+				default:
+					break;
+			}
+		},
+		async snapshotNow(label = "") {
+			if (disabled) throw disabledFailure ?? new GrowthError("growth tracking is disabled for this workspace", "unavailable");
+			let result: GrowthStep | null = null;
+			let failure: unknown;
+			await enqueue(async () => {
+				try {
+					if (disabled) throw disabledFailure ?? new GrowthError("growth tracking is disabled for this workspace", "unavailable");
+					const step = await snapshot(cwd, { kind: "manual", label, session: sessionPath });
+					if (errorActive) {
+						errorActive = false;
+						lastErrorMessage = null;
+						publish({ type: "growth_error", message: null, ts: Date.now() });
+					}
+					if (step) {
+						result = step;
+						publish({ type: "growth", step, ts: Date.now() });
+					}
+				} catch (error) {
+					failure = error;
+					reportError(error);
+				}
+			});
+			if (failure) throw failure;
+			return result;
+		},
+		dispose() {
+			disposed = true;
+			if (flushTimer) clearTimeout(flushTimer);
+			if (pendingTimer) clearTimeout(pendingTimer);
+			if (externalTimer) clearTimeout(externalTimer);
+			try {
+				watcher?.close();
+			} catch {
+				/* ignore */
+			}
+			watcher = null;
+		},
+	};
+}

package/src/lib/growth-tree.ts

@@ -0,0 +1,245 @@
+/**
+ * growth-tree：项目树的纯函数（服务端 / 浏览器 / 测试共用）。
+ * 文件清单 + 变更清单 → 目录树；目录树 + 展开集合 → 可见行列表。
+ */
+import type { GrowthChange } from "./types";
+
+/** 不进快照的目录（影子仓库 info/exclude 与项目树的懒加载目录共用；浏览器可导入） */
+export const GROWTH_EXCLUDE_DIRS = [
+	"node_modules", ".git", ".next", ".next-dev", ".next-dev-webpack", ".next-dev-clean", "dist", "build", "out",
+	".venv", "venv", "__pycache__", ".cache", "target", ".turbo", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".idea",
+	".pnpm", ".pnpm-store", ".npm", ".yarn", ".gradle", ".tox", ".nox", ".uv", ".pixi", ".conda",
+	".svelte-kit", ".nuxt", ".output", ".parcel-cache", ".angular", ".expo", ".dart_tool", ".terraform", ".serverless", ".aws-sam", "coverage", "htmlcov",
+];
+
+export type NodeStatus = "A" | "M" | "D" | "R";
+
+export interface TreeNode {
+	/** 相对工作区的路径（"/" 分隔），根为 "" */
+	path: string;
+	name: string;
+	kind: "dir" | "file";
+	size?: number;
+	/** 文件：相对所选范围的状态 */
+	status?: NodeStatus;
+	from?: string;
+	add?: number;
+	del?: number;
+	binary?: boolean;
+	/** 改盘类工具运行期间目录监听刚看到、还没进快照的路径 */
+	pending?: boolean;
+	/** 快照之外的目录（node_modules 等）：展开时才通过文件接口临时列出 */
+	lazy?: boolean;
+	children?: TreeNode[];
+	/** 目录：子树里各状态的文件数 */
+	counts?: { added: number; modified: number; deleted: number; renamed: number; pending: number };
+}
+
+export interface FlatRow {
+	node: TreeNode;
+	depth: number;
+	expanded: boolean;
+}
+
+/** 目录与历史文件可以同路径共存（如 p → p/child）；状态变化不改变节点身份。 */
+export function treeNodeKey(node: Pick<TreeNode, "kind" | "path">): string {
+	return `${node.kind}:${node.path}`;
+}
+
+export function parentOf(path: string): string {
+	const i = path.lastIndexOf("/");
+	return i < 0 ? "" : path.slice(0, i);
+}
+
+/** 一条路径的全部祖先目录（不含自身、不含根） */
+export function ancestorsOf(path: string): string[] {
+	const out: string[] = [];
+	let p = parentOf(path);
+	while (p) {
+		out.push(p);
+		p = parentOf(p);
+	}
+	return out.reverse();
+}
+
+function compareNodes(a: TreeNode, b: TreeNode): number {
+	if (a.kind !== b.kind) return a.kind === "dir" ? -1 : 1;
+	return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+}
+
+function emptyCounts(): NonNullable<TreeNode["counts"]> {
+	return { added: 0, modified: 0, deleted: 0, renamed: 0, pending: 0 };
+}
+
+/**
+ * 文件清单（所选步的 tree）+ 变更（相对上一步或会话基线）+ 生成中路径 + 懒加载目录名 → 目录树。
+ * 被删的文件不在清单里，从变更里补成 D 节点。
+ */
+export function buildTree(
+	files: { path: string; size?: number }[],
+	changes: GrowthChange[],
+	pending: string[] = [],
+	lazyDirs: string[] = [],
+): TreeNode {
+	const root: TreeNode = { path: "", name: "", kind: "dir", children: [], counts: emptyCounts() };
+	const dirs = new Map<string, TreeNode>([["", root]]);
+	const ensureDir = (path: string): TreeNode => {
+		const found = dirs.get(path);
+		if (found) return found;
+		const parent = ensureDir(parentOf(path));
+		const node: TreeNode = { path, name: path.slice(path.lastIndexOf("/") + 1), kind: "dir", children: [], counts: emptyCounts() };
+		parent.children!.push(node);
+		dirs.set(path, node);
+		return node;
+	};
+	const fileNodes = new Map<string, TreeNode>();
+	const addFile = (path: string, size?: number): TreeNode => {
+		const existing = fileNodes.get(path);
+		if (existing) return existing;
+		const parent = ensureDir(parentOf(path));
+		const node: TreeNode = { path, name: path.slice(path.lastIndexOf("/") + 1), kind: "file", size };
+		parent.children!.push(node);
+		fileNodes.set(path, node);
+		return node;
+	};
+	for (const f of files) addFile(f.path, f.size);
+	for (const c of changes) {
+		const node = addFile(c.path);
+		node.status = c.status;
+		if (c.from) node.from = c.from;
+		if (c.add !== undefined) node.add = c.add;
+		if (c.del !== undefined) node.del = c.del;
+		if (c.binary) node.binary = true;
+	}
+	for (const p of pending) {
+		const isDir = /[/\\]$/.test(p);
+		const rel = p.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+		if (!rel) continue;
+		// 目录事件保留尾斜杠；被删路径无法 stat 时暂按文件处理，下一张快照会修正。
+			const existing = isDir ? dirs.get(rel) : fileNodes.get(rel) ?? dirs.get(rel);
+		if (existing) existing.pending = true;
+		else if (isDir) ensureDir(rel).pending = true;
+		else addFile(rel).pending = true;
+	}
+	for (const d of lazyDirs) {
+		if (dirs.has(d)) continue;
+		const node = ensureDir(d);
+		node.lazy = true;
+	}
+	const finalize = (node: TreeNode): NonNullable<TreeNode["counts"]> => {
+		const counts = emptyCounts();
+		for (const child of node.children ?? []) {
+			if (child.kind === "dir") {
+				const c = finalize(child);
+				if (child.pending && !c.pending) counts.pending += 1;
+				counts.added += c.added;
+				counts.modified += c.modified;
+				counts.deleted += c.deleted;
+				counts.renamed += c.renamed;
+				counts.pending += c.pending;
+			} else {
+				if (child.status === "A") counts.added += 1;
+				else if (child.status === "M") counts.modified += 1;
+				else if (child.status === "D") counts.deleted += 1;
+				else if (child.status === "R") counts.renamed += 1;
+				if (child.pending) counts.pending += 1;
+			}
+		}
+		node.children!.sort(compareNodes);
+		node.counts = counts;
+		return counts;
+	};
+	finalize(root);
+	return root;
+}
+
+export function hasChanges(node: TreeNode): boolean {
+	if (node.kind === "file") return Boolean(node.status || node.pending);
+	const c = node.counts;
+	return Boolean(node.pending || (c && (c.added || c.modified || c.deleted || c.renamed || c.pending)));
+}
+
+/**
+ * 可见行：按展开集合深度优先展开；filter 非空时按名字子串匹配并把命中路径上的目录全部展开；
+ * onlyChanges 只保留有变化的文件与包含变化的目录。
+ */
+export function flattenTree(root: TreeNode, expanded: Set<string>, opts: { onlyChanges?: boolean; filter?: string } = {}): FlatRow[] {
+	const needle = (opts.filter ?? "").trim().toLowerCase();
+	const out: FlatRow[] = [];
+	const matches = (node: TreeNode): boolean => {
+		if (opts.onlyChanges && !hasChanges(node)) return false;
+		if (!needle) return true;
+		if (node.kind === "file") return node.name.toLowerCase().includes(needle);
+		return (node.children ?? []).some(matches);
+	};
+	const walk = (node: TreeNode, depth: number) => {
+		for (const child of node.children ?? []) {
+			if (!matches(child)) continue;
+			const isOpen = child.kind === "dir" && (needle ? true : expanded.has(child.path));
+			out.push({ node: child, depth, expanded: isOpen });
+			if (isOpen) walk(child, depth + 1);
+		}
+	};
+	walk(root, 0);
+	return out;
+}
+
+/** 全部目录路径（展开全部用） */
+export function allDirPaths(root: TreeNode): string[] {
+	const out: string[] = [];
+	const walk = (node: TreeNode) => {
+		for (const child of node.children ?? []) {
+			if (child.kind !== "dir") continue;
+			out.push(child.path);
+			walk(child);
+		}
+	};
+	walk(root);
+	return out;
+}
+
+/** 变更路径的祖先目录集合（新步到来时自动展开用） */
+export function dirsToReveal(changes: GrowthChange[], pending: string[] = []): string[] {
+	const set = new Set<string>();
+	for (const c of changes) for (const d of ancestorsOf(c.path)) set.add(d);
+	for (const p of pending) for (const d of ancestorsOf(p.replace(/\\/g, "/"))) set.add(d);
+	return [...set];
+}
+
+/** 简易模糊匹配：按顺序命中每个字符，返回打分（越大越好）；不匹配返回 -1 */
+export function fuzzyScore(query: string, candidate: string): number {
+	const q = query.toLowerCase();
+	const c = candidate.toLowerCase();
+	if (!q) return 0;
+	const idx = c.indexOf(q);
+	if (idx >= 0) return 1000 - idx - (c.length - q.length) * 0.01;
+	let score = 0;
+	let pos = 0;
+	let last = -2;
+	for (const ch of q) {
+		const i = c.indexOf(ch, pos);
+		if (i < 0) return -1;
+		score += i === last + 1 ? 5 : 1;
+		if (i === 0 || c[i - 1] === "/" || c[i - 1] === "." || c[i - 1] === "-" || c[i - 1] === "_") score += 3;
+		last = i;
+		pos = i + 1;
+	}
+	return score - c.length * 0.01;
+}
+
+/** 把当前磁盘目录的懒加载结果并入快照树，保留快照里的状态和已删除文件。 */
+export function graftLazy(root: TreeNode, lazyChildren: Map<string, TreeNode[]>): TreeNode {
+	if (!lazyChildren.size) return root;
+	const graft = (node: TreeNode): TreeNode => {
+		if (node.kind !== "dir") return node;
+		const children = new Map((node.children ?? []).map((child) => [treeNodeKey(child), graft(child)]));
+		for (const live of lazyChildren.get(node.path) ?? []) {
+			const key = treeNodeKey(live);
+			const existing = children.get(key);
+			if (!existing) children.set(key, graft(live));
+			else if (existing.kind === "dir") children.set(key, { ...existing, lazy: true });
+		}
+		return { ...node, children: [...children.values()].sort(compareNodes) };
+	};
+	return graft(root);
+}

package/src/lib/growth-turns.ts

@@ -0,0 +1,23 @@
+export interface SessionTurn {
+	id: string;
+	ts: number;
+}
+
+interface SessionEntry {
+	type?: string;
+	id?: string;
+	timestamp?: string | number;
+	message?: { role?: string; timestamp?: number };
+}
+
+/** 与会话统计一样遍历全部 JSONL 条目，不使用压缩后的渲染消息列表。 */
+export function userTurnsFromEntries(entries: readonly SessionEntry[]): SessionTurn[] {
+	const turns: SessionTurn[] = [];
+	for (const [index, entry] of entries.entries()) {
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const entryTime = typeof entry.timestamp === "number" ? entry.timestamp : Date.parse(entry.timestamp ?? "");
+		const ts = Number.isFinite(entryTime) ? entryTime : entry.message.timestamp;
+		turns.push({ id: entry.id ?? `entry:${index}`, ts: typeof ts === "number" && Number.isFinite(ts) ? ts : NaN });
+	}
+	return turns;
+}

package/src/lib/highlight.ts

@@ -0,0 +1,59 @@
+/**
+ * 代码高亮（highlight.js/lib/common，约 40 种常用语言）：文件面板预览、过程里的 diff、Git 面板共用。
+ * 按 VS Code 的 token 粒度着色（关键字/字符串/数字/函数/类型/属性/标签/正则/元信息/标点），
+ * 配色是 Pi 自己的：见 globals.css 的 --hl-* 变量（浅色 / 深色各一套）。
+ */
+import hljs from "highlight.js/lib/common";
+
+const EXT_LANG: Record<string, string> = {
+	ts: "typescript", tsx: "typescript", mts: "typescript", cts: "typescript",
+	js: "javascript", jsx: "javascript", mjs: "javascript", cjs: "javascript",
+	json: "json", jsonc: "json", css: "css", scss: "scss", less: "less",
+	html: "xml", htm: "xml", xml: "xml", svg: "xml", vue: "xml",
+	md: "markdown", mdx: "markdown", py: "python", rb: "ruby", go: "go", rs: "rust",
+	java: "java", kt: "kotlin", c: "c", h: "c", cpp: "cpp", cc: "cpp", hpp: "cpp", cs: "csharp",
+	sh: "bash", bash: "bash", zsh: "bash", ps1: "powershell", psm1: "powershell",
+	yml: "yaml", yaml: "yaml", toml: "ini", ini: "ini", cfg: "ini", env: "ini",
+	sql: "sql", php: "php", swift: "swift", lua: "lua", r: "r", pl: "perl", diff: "diff", patch: "diff", makefile: "makefile",
+};
+
+/** 超过这个大小不做整文件高亮（highlight.js 是同步的，会卡主线程） */
+export const HIGHLIGHT_MAX = 120 * 1024;
+
+export function extOf(name: string): string {
+	const base = name.replace(/\\/g, "/").split("/").pop() ?? name;
+	const lower = base.toLowerCase();
+	if (lower === "makefile") return "makefile";
+	if (lower === "dockerfile") return "dockerfile";
+	const i = lower.lastIndexOf(".");
+	return i >= 0 ? lower.slice(i + 1) : "";
+}
+
+/** 按文件名给 highlight.js 的语言 id；认不出或未打包的语言返回 undefined */
+export function languageForPath(path: string | undefined | null): string | undefined {
+	if (!path) return undefined;
+	const lang = EXT_LANG[extOf(path)];
+	return lang && hljs.getLanguage(lang) ? lang : undefined;
+}
+
+/** 整段高亮，返回 HTML（highlight.js 已转义）；失败或过大返回 null */
+export function highlightCode(content: string, language: string | undefined): string | null {
+	if (content.length > HIGHLIGHT_MAX) return null;
+	try {
+		if (language && hljs.getLanguage(language)) return hljs.highlight(content, { language, ignoreIllegals: true }).value;
+		if (content.length < 30 * 1024) return hljs.highlightAuto(content).value;
+	} catch {
+		/* fall through */
+	}
+	return null;
+}
+
+/** 单行高亮（diff 逐行用；跨行的注释/字符串会失去上下文，但足够看） */
+export function highlightLine(text: string, language: string): string | null {
+	if (!text || text.length > 2000) return null;
+	try {
+		return hljs.highlight(text, { language, ignoreIllegals: true }).value;
+	} catch {
+		return null;
+	}
+}