@rexvane/piweb 0.3.1

package/src/lib/trajectory.ts

@@ -0,0 +1,294 @@
+/**
+ * 轨迹账本：对齐 dsh ui-trajectory 的 cell 模型（system/user/message/tool/compacted）。
+ * 活跃会话由 pi 事件实时驱动；冷会话从 JSONL 条目离线重建。
+ * pi 无耗时字段——TTFT/decode 由服务端自测，仅活跃会话有值。
+ */
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { TrajEntry, TrajTokens } from "./types";
+import { sanitizeToolOutput } from "./text-sanitize";
+
+export function toTrajTokens(u: any): TrajTokens | undefined {
+	if (!u || typeof u !== "object") return undefined;
+	const t: TrajTokens = {};
+	if (typeof u.input === "number") t.input = u.input;
+	if (typeof u.output === "number") t.output = u.output;
+	if (typeof u.cacheRead === "number") t.cacheRead = u.cacheRead;
+	if (typeof u.cacheWrite === "number") t.cacheWrite = u.cacheWrite;
+	return Object.keys(t).length ? t : undefined;
+}
+
+function textOf(content: any): string {
+	if (content == null) return "";
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) return content.map(textOf).join("");
+	if (typeof content === "object") {
+		if (typeof content.text === "string") return content.text;
+		if (typeof content.thinking === "string") return content.thinking;
+	}
+	return "";
+}
+
+/** 活跃会话的账本：消费 pi 事件流，维护 cell 列表与计时 */
+export class TrajLedger {
+	entries: TrajEntry[];
+	private nextSeq: number;
+	private streamingStart: { seq: number; t0: number; firstToken?: number } | null = null;
+	/** turn_start 的时刻：请求发出前，LLM 时长与首 token 的真正起点 */
+	private turnStartedAt: number | null = null;
+	private toolIndex = new Map<string, number>(); // toolCallId -> entries 下标
+	private toolStart = new Map<string, number>();
+	private pendingToolArgs = new Map<string, unknown>();
+	/** 新增或更新的条目（本轮事件循环内），供广播增量 */
+	dirty: TrajEntry[] = [];
+
+	constructor(initialEntries: TrajEntry[] = []) {
+		this.entries = initialEntries.map((entry) => ({ ...entry }));
+		this.nextSeq = Math.max(0, ...this.entries.map((entry) => entry.seq)) + 1;
+	}
+
+	private push(entry: Omit<TrajEntry, "seq">): TrajEntry {
+		const full: TrajEntry = { ...entry, seq: this.nextSeq++ };
+		this.entries.push(full);
+		this.dirty.push(full);
+		return full;
+	}
+
+	private touch(entry: TrajEntry | undefined): void {
+		if (entry && !this.dirty.includes(entry)) this.dirty.push(entry);
+	}
+
+	drainDirty(): TrajEntry[] {
+		const out = this.dirty;
+		this.dirty = [];
+		return out;
+	}
+
+	/** 事件到达时间（服务端计时基准） */
+	onEvent(evt: AgentSessionEvent, now = Date.now()): void {
+		switch (evt.type) {
+			case "turn_start":
+				this.turnStartedAt = now;
+				break;
+			case "message_start": {
+				const m: any = evt.message;
+				if (m?.role === "user") {
+					this.push({ kind: "user", ts: m.timestamp ?? now, detail: textOf(m.content) });
+				} else if (m?.role === "assistant") {
+					// 供应商已经返回响应头才会有这条事件；起点用 turn_start（没有就退回现在）
+					const t0 = this.turnStartedAt ?? now;
+					this.turnStartedAt = null;
+					this.streamingStart = { seq: this.nextSeq, t0 };
+					this.push({ kind: "message", ts: t0, title: "assistant" });
+				} else if (m?.role === "toolResult") {
+					const idx = m.toolCallId ? this.toolIndex.get(m.toolCallId) : undefined;
+					if (idx !== undefined) {
+						const e = this.entries[idx];
+						const result = sanitizeToolOutput(textOf(m.content));
+						e.detail = result.text || e.detail;
+						e.encodingLoss = result.encodingLoss || e.encodingLoss;
+						e.isError = m.isError === true;
+						e.tokens = toTrajTokens(m.usage) ?? e.tokens;
+						this.touch(e);
+					}
+				}
+				break;
+			}
+			case "message_update": {
+				const e: any = evt.assistantMessageEvent;
+				if (!e) break;
+				if ((e.type === "text_delta" || e.type === "thinking_delta") && this.streamingStart) {
+					if (this.streamingStart.firstToken === undefined) {
+						this.streamingStart.firstToken = now;
+						const last = this.entries[this.entries.length - 1];
+						if (last?.kind === "message") {
+							last.timing = { ...(last.timing ?? {}), ttftMs: now - this.streamingStart.t0 };
+							this.touch(last);
+						}
+					}
+				}
+				if (e.type === "toolcall_end" && e.toolCall) {
+					this.pendingToolArgs.set(e.toolCall.id, e.toolCall.arguments);
+				}
+				break;
+			}
+			case "message_end": {
+				const m: any = evt.message;
+				if (m?.role === "assistant") {
+					const last = this.entries[this.entries.length - 1];
+					const e = last?.kind === "message" ? last : this.push({ kind: "message", ts: now });
+					if (this.streamingStart) {
+						e.timing = {
+							...(this.streamingStart.firstToken === undefined
+								? {}
+								: {
+									ttftMs: this.streamingStart.firstToken - this.streamingStart.t0,
+									decodeMs: now - this.streamingStart.firstToken,
+								}),
+							durationMs: now - this.streamingStart.t0,
+						};
+					}
+					e.tokens = toTrajTokens(m.usage);
+					e.thinking = textOf(
+						(m.content ?? []).filter((c: any) => c.type === "thinking").map((c: any) => c.thinking),
+					);
+					e.detail = textOf((m.content ?? []).filter((c: any) => c.type === "text"));
+					e.isError = m.stopReason === "error";
+					if (m.stopReason === "error") e.title = "error";
+					this.touch(e);
+					this.streamingStart = null;
+					// assistant 消息里的工具调用 → tool cell（结果随后由 tool_execution / toolResult 补全）
+					for (const c of m.content ?? []) {
+						if (c.type === "toolCall") {
+							this.toolIndex.set(c.id, this.entries.length);
+							this.push({
+								kind: "tool",
+								ts: now,
+								toolName: c.name,
+								toolCallId: c.id,
+								title: c.name,
+								detail: JSON.stringify(c.arguments ?? {}, null, 2),
+							});
+						}
+					}
+				}
+				break;
+			}
+			case "tool_execution_start": {
+				this.toolStart.set(evt.toolCallId, now);
+				let idx = this.toolIndex.get(evt.toolCallId);
+				if (idx === undefined) {
+					idx = this.entries.length;
+					this.toolIndex.set(evt.toolCallId, idx);
+					this.push({
+						kind: "tool",
+						ts: now,
+						toolName: evt.toolName,
+						toolCallId: evt.toolCallId,
+						title: evt.toolName,
+						detail: JSON.stringify(evt.args ?? {}, null, 2),
+					});
+				} else {
+					const e = this.entries[idx];
+					e.detail = JSON.stringify(evt.args ?? {}, null, 2);
+					this.touch(e);
+				}
+				break;
+			}
+			case "tool_execution_update": {
+				const idx = this.toolIndex.get(evt.toolCallId);
+				if (idx !== undefined) {
+					const e = this.entries[idx];
+					const result = sanitizeToolOutput(textOf(evt.partialResult));
+					if (result.text) e.preview = result.text.slice(-2000);
+					e.encodingLoss = result.encodingLoss || e.encodingLoss;
+					this.touch(e);
+				}
+				break;
+			}
+			case "tool_execution_end": {
+				const idx = this.toolIndex.get(evt.toolCallId);
+				if (idx !== undefined) {
+					const e = this.entries[idx];
+					const result = sanitizeToolOutput(textOf(evt.result));
+					e.detail = [e.detail, result.text].filter(Boolean).join("\n\n---\n\n");
+					e.encodingLoss = result.encodingLoss || e.encodingLoss;
+					e.isError = evt.isError === true;
+					const startedAt = this.toolStart.get(evt.toolCallId);
+					if (startedAt !== undefined) e.timing = { ...(e.timing ?? {}), durationMs: now - startedAt };
+					this.touch(e);
+				}
+				this.toolStart.delete(evt.toolCallId);
+				break;
+			}
+			case "compaction_start":
+				this.push({ kind: "compacted", ts: now, title: `compact (${evt.reason})` });
+				break;
+			case "compaction_end": {
+				const last = [...this.entries].reverse().find((e) => e.kind === "compacted");
+				if (last) {
+					if (evt.errorMessage) {
+						last.isError = true;
+						last.detail = evt.errorMessage;
+					}
+					if (evt.result?.tokensBefore != null) last.tokens = { input: evt.result.tokensBefore };
+					this.touch(last);
+				}
+				break;
+			}
+			default:
+				break;
+		}
+	}
+}
+
+/** 冷会话：从 JSONL 条目离线重建账本（无 TTFT/decode——pi 未存） */
+export function buildTrajectoryFromEntries(entries: any[]): TrajEntry[] {
+	const out: TrajEntry[] = [];
+	let seq = 1;
+	const tsOf = (e: any) => (typeof e?.timestamp === "number" ? e.timestamp : Date.now());
+
+	for (const raw of entries) {
+		if (raw.type === "message") {
+			const m = raw.message;
+			if (!m) continue;
+			if (m.role === "user") {
+				out.push({ seq: seq++, kind: "user", ts: tsOf(m), detail: textOf(m.content) });
+			} else if (m.role === "assistant") {
+				const thinking = textOf((m.content ?? []).filter((c: any) => c.type === "thinking"));
+				const text = textOf((m.content ?? []).filter((c: any) => c.type === "text"));
+				out.push({
+					seq: seq++,
+					kind: "message",
+					ts: tsOf(m),
+					title: m.stopReason === "error" ? "error" : "assistant",
+					detail: text,
+					thinking: thinking || undefined,
+					tokens: toTrajTokens(m.usage),
+					isError: m.stopReason === "error" || undefined,
+				});
+				for (const c of m.content ?? []) {
+					if (c.type === "toolCall") {
+						out.push({
+							seq: seq++,
+							kind: "tool",
+							ts: tsOf(m),
+							toolName: c.name,
+							toolCallId: c.id,
+							title: c.name,
+							detail: JSON.stringify(c.arguments ?? {}, null, 2),
+						});
+					}
+				}
+			} else if (m.role === "toolResult") {
+				const target = out.findLast?.(
+					(e) => e.kind === "tool" && (m.toolCallId ? e.toolCallId === m.toolCallId : e.toolName === m.toolName),
+				);
+				if (target) {
+					const result = sanitizeToolOutput(textOf(m.content));
+					target.detail = [target.detail, result.text].filter(Boolean).join("\n\n---\n\n");
+					target.encodingLoss = result.encodingLoss || target.encodingLoss;
+					target.isError = m.isError === true || undefined;
+					target.tokens = toTrajTokens(m.usage) ?? target.tokens;
+				}
+			}
+		} else if (raw.type === "compaction") {
+			out.push({
+				seq: seq++,
+				kind: "compacted",
+				ts: tsOf(raw),
+				title: "compact",
+				tokens: raw.tokensBefore != null ? { input: raw.tokensBefore } : toTrajTokens(raw.usage),
+			});
+		} else if (raw.type === "branch_summary") {
+			out.push({
+				seq: seq++,
+				kind: "compacted",
+				ts: tsOf(raw),
+				title: "branch summary",
+				tokens: toTrajTokens(raw.usage),
+				detail: raw.summary,
+			});
+		}
+	}
+	return out;
+}

package/src/lib/types.ts

@@ -0,0 +1,300 @@
+/**
+ * 客户端 / 服务端共享类型：Web 事件协议、轨迹账本、会话视图模型。
+ * 服务端把 pi 的 AgentSessionEvent 翻译成这里的渲染级事件，浏览器只消费这些。
+ */
+
+// ---------- 会话元信息 ----------
+
+export interface SessionSummary {
+	/** 会话 JSONL 文件的绝对路径（Base64url 编码后作为 URL id） */
+	path: string;
+	name?: string;
+	cwd: string;
+	created: string;
+	modified: string;
+	messageCount: number;
+	firstMessage: string;
+}
+
+// ---------- 轨迹账本 ----------
+
+export type TrajKind = "system" | "context" | "user" | "message" | "tool" | "compacted";
+
+export interface TrajTokens {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+}
+
+export interface TrajEntry {
+	seq: number;
+	kind: TrajKind;
+	ts: number;
+	/** 标题行（工具名 / 摘要等） */
+	title?: string;
+	/** 预览文本（markdown） */
+	preview?: string;
+	/** 完整内容（记录 inspector 展开） */
+	detail?: string;
+	thinking?: string;
+	tokens?: TrajTokens;
+	isError?: boolean;
+	/** Historical shell output contained irreversible Unicode replacement characters. */
+	encodingLoss?: boolean;
+	toolName?: string;
+	toolCallId?: string;
+	timing?: { ttftMs?: number; decodeMs?: number; durationMs?: number };
+	/** UI-derived turn number; omitted in the persisted event ledger. */
+	turn?: number;
+}
+
+// ---------- 服务器 → 浏览器 事件 ----------
+
+/** 消息在客户端渲染时的统一形状（pi AgentMessage 的投影） */
+export interface WebMessage {
+	id?: string;
+	/** 热会话流的稳定身份；持久 entry id 尚未生成时也可关联 start/delta/end 与快照。 */
+	streamId?: string;
+	role: "user" | "assistant" | "toolResult" | "custom" | "other";
+	content: WebContent[];
+	timestamp?: number;
+	/** assistant：生成结束的时刻（热会话由 message_end 打点；冷会话没有，回落到 timestamp） */
+	endedAt?: number;
+	stopReason?: string;
+	errorMessage?: string;
+	/** assistant：模型/用量/思考级别等元信息 */
+	usage?: TrajTokens & { cost?: { total?: number } };
+	model?: string;
+	provider?: string;
+	thinkingLevel?: string;
+}
+
+export type WebContent =
+	| { type: "text"; text: string }
+	| { type: "image"; data: string; mimeType: string }
+	| { type: "thinking"; thinking: string }
+	| { type: "toolCall"; id: string; name: string; arguments: unknown }
+	| { type: "toolResult"; toolCallId?: string; text: string; isError?: boolean; title?: string; encodingLoss?: boolean; patch?: string };
+
+export type WebEvent =
+	| { type: "delta"; kind: "text" | "thinking"; contentIndex: number; delta: string; messageId?: string; ts: number }
+	| { type: "message"; message: WebMessage; phase: "start" | "end"; ts: number }
+	| {
+			type: "tool";
+			id: string;
+			name: string;
+			args: unknown;
+			state: "running" | "done";
+			partialResult?: string;
+			result?: string;
+			isError?: boolean;
+			encodingLoss?: boolean;
+			/** edit/write 工具附带的 unified patch（pi 的 details.patch），前端渲染红绿 diff */
+			patch?: string;
+			ts: number;
+	  }
+	| { type: "status"; isStreaming: boolean; state: string; ts: number }
+	| { type: "queue"; steering: string[]; followUp: string[]; ts: number }
+	| {
+			type: "model";
+			provider?: string;
+			model?: string;
+			thinkingLevel?: string;
+			/** 当前模型支持的档位；切模型后随之更新，否则前端菜单停留在旧模型的档位 */
+			thinkingLevels?: string[];
+			ts: number;
+	  }
+	| {
+			type: "usage";
+			stats: WebStats | null;
+			contextUsage: { tokens: number | null; contextWindow: number; percent: number | null } | null;
+			ts: number;
+	  }
+	| { type: "compaction"; phase: "start" | "end"; reason?: string; errorMessage?: string; ts: number }
+	| { type: "traj"; entry: TrajEntry; ts: number }
+	| { type: "name"; name: string; ts: number }
+	| { type: "tools"; active: string[]; all: string[]; toolPreset?: ToolPreset; customActiveTools?: string[] | null; ts: number }
+	| {
+			/** 资源（扩展/技能/模板/命令）重载后的新清单；前端据此刷新 / 菜单与设置面板 */
+			type: "resources";
+			skills: WebSnapshot["skills"];
+			promptTemplates: WebSnapshot["promptTemplates"];
+			extensionCommands: WebSnapshot["extensionCommands"];
+			projectTrust: WebSnapshot["projectTrust"];
+			resourceDiagnostics: WebSnapshot["resourceDiagnostics"];
+			ts: number;
+	  }
+	| {
+			/** 扩展请求界面交互（对应 pi RPC 模式的 extension_ui_request）：select/confirm/input 需要浏览器应答 */
+			type: "extension_ui";
+			id: string;
+			method: "select" | "confirm" | "input" | "notify" | "setStatus" | "setWorkingMessage";
+			title?: string;
+			message?: string;
+			options?: string[];
+			placeholder?: string;
+			notifyType?: "info" | "warning" | "error";
+			statusKey?: string;
+			statusText?: string;
+			timeout?: number;
+			ts: number;
+	  }
+	| { type: "extension_ui_resolved"; id: string; ts: number }
+	| { type: "error"; message: string; ts: number }
+	/** 项目生长：记录了一步（工具结束 / 回合结束 / 外部修改 / 会话基线） */
+	| { type: "growth"; step: GrowthStep; ts: number }
+	/** 项目生长：改盘类工具运行期间目录监听看到的新路径（累计；空数组 = 清空） */
+	| { type: "growth_pending"; paths: string[]; ts: number }
+	| { type: "growth_error"; message: string | null; ts: number };
+
+export interface WebStats {
+	userMessages: number;
+	assistantMessages: number;
+	toolCalls: number;
+	totalMessages: number;
+	tokens: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number };
+	cost: number;
+	llmMs: number;
+	toolMs: number;
+	ttftMs: number;
+	ttftSteps: number;
+	decodeMs: number;
+	decodeTokens: number;
+}
+
+// ---------- 项目生长（影子仓库快照） ----------
+
+export type GrowthStepKind = "baseline" | "tool" | "turn" | "external" | "manual";
+
+export interface GrowthChange {
+	status: "A" | "M" | "D" | "R";
+	/** 相对工作区的路径（"/" 分隔） */
+	path: string;
+	/** 重命名前的路径 */
+	from?: string;
+	add?: number;
+	del?: number;
+	binary?: boolean;
+}
+
+export interface GrowthStep {
+	/** 工作区内单调递增 */
+	seq: number;
+	ts: number;
+	/** 触发这一步的会话（JSONL 绝对路径） */
+	session: string;
+	kind: GrowthStepKind;
+	/** 「bash · mkdir -p src」这样的一句标签 */
+	label: string;
+	/** 这一步之后的 tree 哈希 */
+	tree: string;
+	/** 这一步之前的 tree 哈希（工作区首张快照为 empty tree） */
+	parent: string;
+	commit?: string;
+	toolCallId?: string;
+	toolName?: string;
+	/** 相对上一步的变更（超过上限时截断，truncated=true） */
+	changes: GrowthChange[];
+	truncated?: boolean;
+	/** 工作区的第一张快照：全部文件都是新增，账本里不存清单 */
+	initial?: boolean;
+	stats: { added: number; modified: number; deleted: number; renamed: number; add: number; del: number };
+}
+
+export interface ContextResource {
+	/** Human-readable producer path reported by Pi's resource loader. */
+	path: string;
+	/** Exact text appended to the model context. */
+	content: string;
+	/** Whether Pi discovered the file directly or an extension appended it. */
+	source: "project" | "extension";
+}
+
+/** SSE 连接建立时先发的完整快照 */
+export interface WebSnapshot {
+	seq: number;
+	sessionPath: string;
+	cwd: string;
+	name: string;
+	/** 兼容旧版 Web 客户端的上下文路径列表。 */
+	contextFiles: string[];
+	/** 注入的上下文资源（AGENTS.md 与扩展附加 prompt，来自 Pi 资源加载器）。 */
+	contextResources: ContextResource[];
+	/** 斜杠命令数据源：技能 */
+	skills: { name: string; description: string }[];
+	/** 斜杠命令数据源：提示模板（~/.pi/agent/prompts、<cwd>/.pi/prompts 里的 .md） */
+	promptTemplates: { name: string; description: string; argumentHint?: string }[];
+	/** 斜杠命令数据源：扩展注册的命令（只有热会话才有） */
+	extensionCommands: { name: string; description: string; source: string }[];
+	/** 项目信任：目录含 .pi/extensions 等需要信任的资源时，pi 只在受信任时才加载它们 */
+	projectTrust: { required: boolean; trusted: boolean; source: string };
+	/** 资源诊断：扩展加载失败、技能/模板解析警告（来自 pi 资源加载器） */
+	resourceDiagnostics: { kind: "extension" | "skill" | "prompt" | "command"; path?: string; message: string }[];
+	messages: WebMessage[];
+	/** 全部持久用户消息的轮次（含上下文压缩后不再渲染的消息）。 */
+	userTurns: { id: string; ts: number }[];
+	growthError: string | null;
+	model?: { provider: string; id: string; name: string };
+	thinkingLevel?: string;
+	thinkingLevels: string[];
+	toolPreset: ToolPreset;
+	/** custom 白名单优先于 preset；null 表示使用 preset，省略兼容旧服务端。 */
+	customActiveTools?: string[] | null;
+	/** 当前待应答的扩展请求；快照是权威集合，不重放已答请求。 */
+	extensionUiRequests?: Extract<WebEvent, { type: "extension_ui" }>[];
+	tools: { active: string[]; all: { name: string; description?: string }[] };
+	stats: WebStats | null;
+	contextUsage: { tokens: number | null; contextWindow: number; percent: number | null } | null;
+	queue: { steering: string[]; followUp: string[] };
+	trajectory: TrajEntry[];
+	isStreaming: boolean;
+}
+
+// ---------- 浏览器 → 服务器 命令 ----------
+
+export type ToolPreset = "readonly" | "standard" | "full";
+
+export interface ImageAttachment {
+	type: "image";
+	data: string;
+	mimeType: string;
+}
+
+export interface AgentCommand {
+	cmd:
+		| "prepare"
+		| "prompt"
+		| "steer"
+		| "followUp"
+		| "abort"
+		| "compact"
+		| "setModel"
+		| "setThinkingLevel"
+		| "setToolPreset"
+		| "rename"
+		| "fork"
+		| "cycleModel"
+		| "navigate"
+		| "clearQueue"
+		| "setActiveTools"
+		| "extensionUiResponse"
+		| "reload";
+	text?: string;
+	images?: ImageAttachment[];
+	instructions?: string;
+	provider?: string;
+	modelId?: string;
+	level?: string;
+	preset?: ToolPreset;
+	entryId?: string;
+	behavior?: "steer" | "followUp";
+	direction?: "forward" | "backward";
+	/** setActiveTools：目标激活的工具名列表（与可用集求交集） */
+	names?: string[];
+	/** extensionUiResponse：对应 extension_ui 事件的 id 与应答 */
+	requestId?: string;
+	value?: string;
+	confirmed?: boolean;
+	cancelled?: boolean;
+}