pi-trace-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZKiteLM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# Pi Trace Viewer
+
+> Live local observability for Pi sessions, branches, compaction, and LLM context.
+
+[中文 README](./README.zh.md)
+
+Pi Trace Viewer answers a practical debugging question: **what did the model actually see?**
+
+It runs as a Pi extension and opens a local browser UI where you can inspect the live session tree, model calls, tool activity, compaction inputs, and provider payloads without modifying Pi's native session files.
+
+## Install
+
+```bash
+pi install npm:pi-trace-viewer
+```
+
+Start a new Pi session and open the viewer:
+
+```bash
+/trace-view
+```
+
+The viewer starts at `http://127.0.0.1:7890` by default. If that port is busy, it automatically uses the next available port, such as `7891` or `7892`.
+
+To try the extension for one Pi run without changing your settings:
+
+```bash
+pi -e npm:pi-trace-viewer
+```
+
+To choose a custom starting port:
+
+```bash
+pi --pi-trace-port 8890
+```
+
+## What You Can Inspect
+
+- The live Pi session tree, including branches and active turns
+- The normalized Pi context passed into `pi-ai`
+- The provider-specific payload sent to the backend
+- Streaming model output, tool calls, and tool results
+- Compaction source messages, cut points, summaries, token metadata, and provider requests
+- Custom messages and custom state created by other extensions
+
+## Screenshots
+
+### Realtime Session Viewer
+
+![Realtime Session Viewer](./assets/images/realtime-session-viewport.png)
+
+### Session Viewer vs Pi Export
+
+| Pi Trace Viewer | Pi `/export` |
+| --- | --- |
+| ![Realtime Session Viewer](./assets/images/realtime-session-viewport.png) | ![Pi export page](./assets/images/pi-export-viewport.png) |
+
+### Compaction Context
+
+![Compaction Context](./assets/images/compaction-context-viewport.png)
+
+## Why Use It?
+
+### Live Observation
+
+Pi `/export` is useful after a conversation. Pi Trace Viewer updates while the session is running, so you can watch branches, tool calls, model output, and context changes as they happen.
+
+### Pi Context vs Provider Payload
+
+Every captured LLM call separates two views:
+
+| View | What it shows |
+| --- | --- |
+| Pi Context | Normalized system prompt, messages, and tools handed to `pi-ai` |
+| Provider Payload | Backend-specific request after provider mapping and templates |
+
+Each message can be expanded independently, with rendered Markdown, raw Markdown, and full JSON available when you need them.
+
+### Inspectable Compaction
+
+Compaction events show the messages selected for summarization, split-turn prefixes, cut points, token counts, recent-message policy, previous summaries, extracted file operations, and the provider request used to generate the summary.
+
+That makes context loss after compaction easier to trace.
+
+### Long Sessions Stay Navigable
+
+The session sidebar keeps single-child chains flat and only indents real branches. LLM calls are numbered chronologically and include call kind, turn, model, API, prompt excerpt, tool names, status, request count, and duration.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A[Pi session] --> B[Pi extension hooks]
+    B --> C[In-memory viewer state]
+    C --> D[localhost browser UI]
+    B --> E[.pi-traces/session-id.jsonl]
+    D --> F[Session and LLM Calls]
+```
+
+The extension reads Pi's live snapshot and listens to public lifecycle events, including:
+
+- `context`
+- `before_provider_request`
+- `after_provider_response`
+- `message_update`
+- `message_end`
+- `session_before_compact`
+- `session_compact`
+- `session_tree`
+
+## Data and Privacy
+
+Pi Trace Viewer binds only to `127.0.0.1`.
+
+It does not write to Pi's native session JSONL and does not call `appendCustomEntry` or `appendCustomMessageEntry`. Pi's native session remains in:
+
+```text
+~/.pi/agent/sessions/<encoded-cwd>/<session-id>.jsonl
+```
+
+The extension writes sidecar traces to:
+
+```text
+<session-cwd>/.pi-traces/<session-id>.jsonl
+```
+
+Trace directories use `0700` permissions and trace files use `0600` permissions. Credential-shaped fields and sensitive response headers are redacted, but prompts, system instructions, tool results, and model output can still contain sensitive data. Treat `.pi-traces` as private local debugging data.
+
+To remove old traces:
+
+```bash
+rm -rf "/path/to/session-cwd/.pi-traces"
+```
+
+## Local Development
+
+```bash
+npm install
+npm run check
+pi -e /path/to/pi-trace-viewer
+```
+
+## Publishing Checklist
+
+Before publishing a new release:
+
+```bash
+npm run check
+npm pack --dry-run
+npm publish --access public
+```

package/README.zh.md

@@ -0,0 +1,151 @@
+# Pi Trace Viewer
+
+> 面向 Pi 会话、分支、压缩和 LLM Context 的本地实时可观测 UI。
+
+[English README](./README.md)
+
+Pi Trace Viewer 解决一个很具体的问题：**模型到底看到了什么？**
+
+它作为 Pi 扩展运行，并启动一个本地浏览器 UI。你可以在不修改 Pi 原生 session 文件的情况下，实时查看会话树、模型调用、工具活动、压缩输入，以及 provider 实际收到的 payload。
+
+## 安装
+
+```bash
+pi install npm:pi-trace-viewer
+```
+
+启动新的 Pi 会话后，打开 viewer：
+
+```bash
+/trace-view
+```
+
+Viewer 默认从 `http://127.0.0.1:7890` 启动。如果端口被占用，会自动递增寻找下一个可用端口，例如 `7891` 或 `7892`。
+
+如果只想在单次 Pi 运行中临时启用，不修改设置：
+
+```bash
+pi -e npm:pi-trace-viewer
+```
+
+如需指定自定义起始端口：
+
+```bash
+pi --pi-trace-port 8890
+```
+
+## 可以查看什么
+
+- 实时 Pi 会话树，包括分支和当前 turn
+- 传给 `pi-ai` 的规范化 Pi Context
+- 实际发送给后端的 provider-specific payload
+- 模型流式输出、工具调用和工具结果
+- Compaction 的源消息、截断点、summary、token 元数据和 provider 请求
+- 其他扩展写入的 custom message 与 custom state
+
+## 截图
+
+### 实时 Session Viewer
+
+![实时 Session Viewer](./assets/images/realtime-session-viewport.png)
+
+### Session Viewer vs Pi Export
+
+| Pi Trace Viewer | Pi `/export` |
+| --- | --- |
+| ![实时 Session Viewer](./assets/images/realtime-session-viewport.png) | ![Pi export 页面](./assets/images/pi-export-viewport.png) |
+
+### Compaction Context
+
+![Compaction Context](./assets/images/compaction-context-viewport.png)
+
+## 为什么使用它？
+
+### 实时观察
+
+Pi `/export` 适合在对话结束后阅读完整历史。Pi Trace Viewer 会在会话运行时持续更新，让你边运行 Pi，边观察分支、工具调用、模型输出和 Context 变化。
+
+### 区分 Pi Context 与 Provider Payload
+
+每一次捕获到的 LLM 调用都会拆成两个视图：
+
+| 视图 | 内容 |
+| --- | --- |
+| Pi Context | 传给 `pi-ai` 的规范化 system prompt、messages 和 tools |
+| Provider Payload | 经过 provider mapping 和 templates 之后，实际发送给后端的请求 |
+
+每条消息都可以独立展开，并支持渲染后的 Markdown、Markdown 原文和完整 JSON。
+
+### 可解释的 Compaction
+
+Compaction 事件会展示被选中用于总结的消息、split-turn prefix、截断点、token 数、最近消息保留策略、上一次 summary、提取到的文件操作信息，以及用于生成 summary 的 provider 请求。
+
+这让“为什么压缩后模型忘了某件事”变成一个可以追溯的问题。
+
+### 长会话也能保持可导航
+
+Session 侧栏会把单子节点链保持扁平，只有真正发生分支时才缩进。LLM calls 按时间编号，并显示调用类型、turn、model、API、prompt 摘要、工具名、状态、请求次数和耗时。
+
+## 工作方式
+
+```mermaid
+flowchart LR
+    A[Pi session] --> B[Pi extension hooks]
+    B --> C[In-memory viewer state]
+    C --> D[localhost browser UI]
+    B --> E[.pi-traces/session-id.jsonl]
+    D --> F[Session and LLM Calls]
+```
+
+扩展读取 Pi 提供的 live snapshot，并监听公开生命周期事件，包括：
+
+- `context`
+- `before_provider_request`
+- `after_provider_response`
+- `message_update`
+- `message_end`
+- `session_before_compact`
+- `session_compact`
+- `session_tree`
+
+## 数据与隐私
+
+Pi Trace Viewer 只绑定 `127.0.0.1`。
+
+它不会写入 Pi 原生 session JSONL，也不会调用 `appendCustomEntry` 或 `appendCustomMessageEntry`。Pi 原生 session 仍然位于：
+
+```text
+~/.pi/agent/sessions/<encoded-cwd>/<session-id>.jsonl
+```
+
+扩展会把旁车 trace 写入：
+
+```text
+<session-cwd>/.pi-traces/<session-id>.jsonl
+```
+
+Trace 目录使用 `0700` 权限，trace 文件使用 `0600` 权限。credential-shaped 字段和敏感响应头会被脱敏，但 prompt、system instruction、工具结果和模型输出仍可能包含敏感信息。请把 `.pi-traces` 当作私有的本地调试数据。
+
+清理旧 trace：
+
+```bash
+rm -rf "/path/to/session-cwd/.pi-traces"
+```
+
+## 本地开发
+
+```bash
+npm install
+npm run check
+pi -e /path/to/pi-trace-viewer
+```
+
+## 发布检查
+
+发布新版本前：
+
+```bash
+npm run check
+npm pack --dry-run
+npm publish --access public
+```

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-trace-viewer",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Live local session and LLM context viewer for pi",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "llm-observability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZKiteLM/pi-trace-viewer.git"
+  },
+  "homepage": "https://github.com/ZKiteLM/pi-trace-viewer#readme",
+  "bugs": {
+    "url": "https://github.com/ZKiteLM/pi-trace-viewer/issues"
+  },
+  "files": [
+    "assets/images/",
+    "src/",
+    "web/",
+    "README.zh.md",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "video": "https://github.com/ZKiteLM/pi-trace-viewer/releases/download/v0.1.0/pi-trace-viewer-demo.mp4",
+    "image": "https://raw.githubusercontent.com/ZKiteLM/pi-trace-viewer/main/assets/images/realtime-session-viewport.png"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && vitest run",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@highlightjs/cdn-assets": "11.11.1",
+    "marked": "16.2.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.84.3",
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@types/node": "24.3.0",
+    "typescript": "5.9.2",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/collector.ts

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import type {
+	BeforeProviderRequestEvent,
+	ContextEvent,
+	ExtensionContext,
+	MessageEndEvent,
+	MessageUpdateEvent,
+	SessionCompactEvent,
+	SessionBeforeCompactEvent,
+	SessionTreeEvent,
+	ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import type { AssistantMessageEvent, Tool } from "@earendil-works/pi-ai";
+import { redactHeaders, redactSensitive } from "./security.ts";
+import { TraceStore } from "./store.ts";
+import type { CallKind, CompactAssistantEvent, SessionSnapshot } from "./types.ts";
+import { toTraceModel } from "./types.ts";
+
+interface ActiveCall {
+	id: string;
+	kind: CallKind;
+	attempt: number;
+}
+
+interface AfterProviderResponseEvent {
+	type: "after_provider_response";
+	status: number;
+	headers: Record<string, string>;
+}
+
+export class TraceCollector {
+	private activeCall: ActiveCall | undefined;
+	private nextKind: CallKind = "agent";
+	private turnIndex: number | undefined;
+	private systemPrompt = "";
+	private tools: ToolInfo[] = [];
+
+	constructor(
+		private store: TraceStore,
+		private snapshot: () => SessionSnapshot,
+	) {}
+
+	setSystemPrompt(systemPrompt: string): void {
+		this.systemPrompt = systemPrompt;
+	}
+
+	setTools(tools: ToolInfo[]): void {
+		this.tools = structuredClone(tools);
+	}
+
+	startTurn(turnIndex: number): void {
+		this.turnIndex = turnIndex;
+		this.nextKind = "agent";
+	}
+
+	prepare(kind: Extract<CallKind, "compaction" | "branch_summary">, ctx?: ExtensionContext): void {
+		this.nextKind = kind;
+	}
+
+	beginCompaction(event: SessionBeforeCompactEvent, ctx: ExtensionContext): void {
+		this.nextKind = "compaction";
+		if (this.activeCall) this.failActive("Superseded by context compaction");
+		const call = this.startCall("compaction", ctx);
+		const preparation = event.preparation;
+		this.store.append({
+			type: "compaction_context",
+			callId: call.id,
+			context: {
+				reason: event.reason,
+				willRetry: event.willRetry,
+				customInstructions: event.customInstructions,
+				firstKeptEntryId: preparation.firstKeptEntryId,
+				isSplitTurn: preparation.isSplitTurn,
+				tokensBefore: preparation.tokensBefore,
+				previousSummary: preparation.previousSummary,
+				messagesToSummarize: structuredClone(preparation.messagesToSummarize),
+				turnPrefixMessages: structuredClone(preparation.turnPrefixMessages),
+				settings: structuredClone(preparation.settings),
+				fileOps: {
+					read: [...preparation.fileOps.read],
+					written: [...preparation.fileOps.written],
+					edited: [...preparation.fileOps.edited],
+				},
+			},
+		});
+	}
+
+	onContext(event: ContextEvent, ctx: ExtensionContext): void {
+		if (this.activeCall) this.failActive("Superseded by the next LLM context");
+		this.nextKind = "agent";
+		const call = this.startCall("agent", ctx);
+		const activeNames = new Set(this.tools.map((tool) => tool.name));
+		const tools: Tool[] = this.tools
+			.filter((tool) => activeNames.has(tool.name))
+			.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }));
+		this.store.append({
+			type: "generic_context",
+			callId: call.id,
+			context: {
+				systemPrompt: ctx.getSystemPrompt() || this.systemPrompt,
+				messages: structuredClone(event.messages),
+				tools,
+			},
+		});
+	}
+
+	onProviderRequest(event: BeforeProviderRequestEvent, ctx: ExtensionContext): void {
+		const call = this.activeCall ?? this.startCall(this.nextKind === "agent" ? "unknown" : this.nextKind, ctx);
+		call.attempt += 1;
+		this.store.append({
+			type: "provider_request",
+			callId: call.id,
+			attempt: call.attempt,
+			payload: redactSensitive(structuredClone(event.payload)),
+		});
+	}
+
+	onProviderResponse(event: AfterProviderResponseEvent, ctx: ExtensionContext): void {
+		const call = this.activeCall ?? this.startCall(this.nextKind === "agent" ? "unknown" : this.nextKind, ctx);
+		this.store.append({
+			type: "provider_response",
+			callId: call.id,
+			attempt: Math.max(call.attempt, 1),
+			status: event.status,
+			headers: redactHeaders(event.headers),
+		});
+	}
+
+	onMessageUpdate(event: MessageUpdateEvent): void {
+		if (!this.activeCall || this.activeCall.kind !== "agent") return;
+		this.store.append({
+			type: "output_event",
+			callId: this.activeCall.id,
+			event: compactEvent(event.assistantMessageEvent),
+		});
+	}
+
+	onMessageEnd(event: MessageEndEvent): void {
+		if (event.message.role !== "assistant" || !this.activeCall || this.activeCall.kind !== "agent") return;
+		const snapshot = this.snapshot();
+		if (event.message.stopReason === "error" || event.message.stopReason === "aborted") {
+			this.store.append({
+				type: "call_failed",
+				callId: this.activeCall.id,
+				error: event.message.errorMessage ?? event.message.stopReason,
+			});
+		} else {
+			this.store.append({
+				type: "call_completed",
+				callId: this.activeCall.id,
+				message: structuredClone(event.message),
+				leafId: snapshot.leafId,
+			});
+		}
+		this.activeCall = undefined;
+	}
+
+	onCompaction(event: SessionCompactEvent): void {
+		if (!this.activeCall || this.activeCall.kind !== "compaction") return;
+		this.store.append({
+			type: "compaction_completed",
+			callId: this.activeCall.id,
+			summary: event.compactionEntry.summary,
+			tokensBefore: event.compactionEntry.tokensBefore,
+			sourceEntryId: event.compactionEntry.id,
+		});
+		this.activeCall = undefined;
+		this.nextKind = "agent";
+	}
+
+	onTree(event: SessionTreeEvent): void {
+		this.nextKind = "agent";
+		if (!this.activeCall || this.activeCall.kind !== "branch_summary") return;
+		if (!event.summaryEntry) {
+			this.failActive("Tree navigation completed without a generated summary");
+			return;
+		}
+		this.store.append({
+			type: "branch_summary_completed",
+			callId: this.activeCall.id,
+			summary: event.summaryEntry.summary,
+			leafId: event.newLeafId,
+		});
+		this.activeCall = undefined;
+	}
+
+	onCompactionFailed(error: string): void {
+		this.nextKind = "agent";
+		if (this.activeCall?.kind === "compaction") this.failActive(error);
+	}
+
+	private startCall(kind: CallKind, ctx: ExtensionContext): ActiveCall {
+		const snapshot = this.snapshot();
+		const call: ActiveCall = { id: randomUUID(), kind, attempt: 0 };
+		this.activeCall = call;
+		this.store.append({
+			type: "call_started",
+			callId: call.id,
+			kind,
+			turnIndex: this.turnIndex,
+			leafId: snapshot.leafId,
+			model: toTraceModel(ctx.model),
+		});
+		return call;
+	}
+
+	private failActive(error: string): void {
+		if (!this.activeCall) return;
+		this.store.append({ type: "call_failed", callId: this.activeCall.id, error });
+		this.activeCall = undefined;
+	}
+}
+
+function compactEvent(event: AssistantMessageEvent): CompactAssistantEvent {
+	const copy = structuredClone(event) as AssistantMessageEvent & { partial?: unknown };
+	delete copy.partial;
+	return copy;
+}