pi-ui-extension 1.1.0

package/README.md

@@ -0,0 +1,43 @@
+# pi-ui-extension
+
+A Pi package that extends the terminal UI with a footer, split-view sidebar, context/activity panels, session controls, resource views, and configurable tool transcript rendering.
+
+## Requirements
+
+- Node.js 24+
+- A compatible Pi Coding Agent installation
+
+## Development
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Run the full validation suite:
+
+```bash
+npm run check
+```
+
+Or run checks separately:
+
+```bash
+npm run typecheck
+npm test
+```
+
+## Package entry
+
+Pi loads the extension from:
+
+```text
+./extensions/index.ts
+```
+
+The package metadata is declared in `package.json` under the `pi.extensions` field.
+
+## Notes
+
+This repository contains only the extension source and development metadata. Local Pi runtime configuration, credentials, sessions, caches, and browser profiles are intentionally excluded.

package/extensions/ctx/README.md

@@ -0,0 +1,35 @@
+# CTX 第一版
+
+保留 model/thinking、pi usage/contextWindow 与进度条。context-mode 的 Events captured 和 Compactions 显示在进度条下方，Composition 内容直接展示，以横线与估算统计分隔，不再显示折叠标题或注册点击监听。内容超出分配高度可滚轮滚动，CTX 最大高度为终端的 35%（至少 10 行），沿用 sidebar 的滚动布局，不获取编辑器键盘焦点。
+
+## 估算口径
+
+- approx = 本地可观测文本 UTF-16 长度 / 4，逐消息向上取整；不是模型 tokenizer。已知消息先经公开 SDK `convertToLlm` 转换，再提取文本，因此包含摘要包装、bash 无输出/退出/取消/截断提示；仍按原始角色分类。未知角色安全降级为外层 content 文本，`excludeFromContext` 的 bash 不计入。
+- 六类为 System、Tools、Messages、Tool Results、Summary、Other。百分比分母是已覆盖分类的估算 token 合计，不是模型窗口；pi usage 单独展示，不校准分类。
+- System 使用 ctx.getSystemPrompt() 的可观测字符串；无法取得时 unknown。Tools 通过 pi.getActiveTools()/getAllTools() 仅选取当前启用的工具，逐工具序列化 `{name, description, parameters}`，按 UTF-16 长度 / 4 向上取整后合计，并纳入分类百分比分母。不计 sourceInfo、执行函数及已归入 System 的 promptGuidelines；Fabric 捕获但未直接启用的工具不重复计入。无启用工具为 0；API 不可用、启用工具缺少定义或 schema 无法序列化时保持 unknown，避免显示不完整合计。工具定义在每次现有快照事件刷新时重新读取（包括动态启用/禁用），不在 render 中读取；空闲时注册工具将在下一次快照事件反映。
+- Tools 在 `before_provider_request` 事件后优先统计 provider-specific payload 的 `tools` 字段序列化文本（仍按 UTF-16 长度 / 4 估算）；请求发出前未观察到 payload 时，回退到当前启用工具 schema 的本地估算。它仍不是模型 tokenizer、HTTP 字节数或计费 token，也不包含 headers；如果后续扩展继续改写 payload，面板值可能是本扩展处理时观察到的版本。Images 仅统计图片块数量，不序列化请求或计算未展示的字节数；在 `before_provider_request` 可取得最终 provider payload 时优先统计该 payload，否则统计当前 context 消息；未能观测时显示 `not observed`。
+- context 事件提供调用前的消息快照；session_start/tree/compact、turn_end、agent_settled 使用 buildContextEntries() 重建 compaction-applied active branch。后者显示 active branch，前者显示 context hook。事件之外只读取缓存，不在 render 中扫描历史。
+- Messages 包括 user/assistant 文本、thinking 和 tool call 名称/参数；Tool Results 仅计 content；Summary 包括 compaction/branch summary；Other 包括可发送 custom message 和非排除的用户 bash。
+- Tool Results 按当前快照工具结果文本估算。Fabric 外层 content 只计一次，不遍历内部操作；不读 details、全量 JSONL、沙箱、截断前原始输出或被压缩结果。已返回 content 内的截断提示本身仍属于可发送文本。
+
+Composition 的 token 估算使用 `~` 前缀及 K/M 紧凑缩写（四舍五入），百分比保留一位小数。宽度不足时标签与数值拆行；支持的最小侧栏宽 18 可完整显示如 `~100K 100.0%`。
+
+## 本次提问增量
+
+以一次提问（`before_agent_start` 到 `agent_settled`）为单位：基线是上一次提问结束后的分类估算总量，`turn_end` 只重算快照、不推进基线，因此增量在提问进行中实时增长，`agent_settled` 后定格。数值是净增长，压缩造成的下降显示为负。`session_start`、`session_tree`、`session_compact` 会把基线重置为当前总量，此时不显示增量。
+
+进度条最右侧的 accent 段是增量在窗口中的份额，宽度为 `round(内容宽 × 增量 / contextWindow)`，向上至少 1 格，且不会超出已用段，所以条的总长度不变。增量文字显示在 `已用%/窗口` 之后：正增量用 accent，负增量用 warning。增量为 0、基准未建立或窗口未知时，既不留文字也不画段。增量与分类估算同源（本地启发式），不含 `~` 前缀。
+
+## 活动指标（原 ACTIVITY 面板）
+
+独立 ACTIVITY 面板已移除，其内容移到进度条下方，以横线与分类统计分隔：状态 + 平均性能、最新 TTFT。
+
+- 第一行：`N turns · 时长 · AVG TTFT · AVG TPS`。运行中时长按秒刷新（CTX 面板每秒 requestRender 一次），settled 后显示 `done 时长`，空闲显示 `Ready`。窄屏依次回退为 `状态`、`NT done 时长`、仅平均值，保证窗口内可见。
+- 第二行：最新一次观测到的 TTFT（含 fast/normal/slow 标签），不是平均值——平均值只在第一行。进行中且尚无 TTFT 时显示 `pending`。
+- 追踪器（TTFT/TPS 采样、turn 与工具记录）位于 `ctx/activity.ts`，由 `ctx/panel.ts` 渲染时读取；活动快照只用于这两行，面板不再注册独立的 layout 条目。
+
+## 限制
+
+这是明确标记的本地估算，不宣称最终请求精确统计。后加载扩展仍可能改写 context 或 provider payload；不同 provider 的转换、剔除、包装开销未知。恢复/回合结束时 active branch 可能不同于上次请求经过 context 扩展裁剪后的快照；下一次 context 事件会替换它。模型生成过程中不逐 token 更新分类，最终回合/settled 时更新。只含图片的消息可见文本为零，不代表图片成本为零。
+
+未修改 pi core、Fabric 或全局配置。全屏鼠标/极短终端还应在用户真实终端手工确认。

package/extensions/ctx/activity.ts

@@ -0,0 +1,226 @@
+import nodePath from "node:path";
+
+export type ToolActivityStatus = "running" | "done" | "failed";
+export type ToolActivity = {
+  readonly id: string;
+  readonly name: string;
+  readonly summary: string;
+  readonly status: ToolActivityStatus;
+  readonly startedAt: number;
+  readonly durationMs?: number;
+};
+export type ResponsePerformance = {
+  readonly ttftMs?: number;
+  readonly tokensPerSecond?: number;
+  readonly estimated?: boolean;
+};
+export type TurnActivity = {
+  readonly number: number;
+  readonly startedAt: number;
+  readonly durationMs?: number;
+  readonly performance?: ResponsePerformance;
+  readonly tools: readonly ToolActivity[];
+};
+export type RunActivitySnapshot = {
+  readonly phase: "idle" | "running" | "settled";
+  readonly turnNumber?: number;
+  readonly startedAt?: number;
+  readonly durationMs?: number;
+  readonly performance?: ResponsePerformance;
+  readonly averagePerformance?: ResponsePerformance;
+  readonly turns: readonly TurnActivity[];
+  readonly activeTools: readonly ToolActivity[];
+  readonly recentTools: readonly ToolActivity[];
+  readonly completedCount: number;
+  readonly failedCount: number;
+};
+export type ToolStart = { readonly toolCallId: string; readonly toolName: string; readonly args: unknown };
+export type ToolEnd = { readonly toolCallId: string; readonly isError: boolean };
+export type ActivityTracker = {
+  startRun(now?: number): void;
+  startTurn(turnIndex: number, now?: number): void;
+  finishTurn(turnIndex: number, now?: number): void;
+  startResponse(now?: number): void;
+  updateResponseEstimate(estimatedOutputTokens: number, now?: number): void;
+  finishResponse(outputTokens: number, now?: number): void;
+  startTool(event: ToolStart, now?: number): void;
+  finishTool(event: ToolEnd, now?: number): void;
+  settle(now?: number): void;
+  reset(): void;
+  getSnapshot(): RunActivitySnapshot;
+};
+
+const MAX_SUMMARY_LENGTH = 80;
+export const EMPTY_ACTIVITY: RunActivitySnapshot = Object.freeze({
+  phase: "idle", turns: Object.freeze([]), activeTools: Object.freeze([]), recentTools: Object.freeze([]), completedCount: 0, failedCount: 0,
+});
+type SpeedLabel = "fast" | "normal" | "slow";
+function ttftSpeed(ms: number): SpeedLabel { return ms < 2_000 ? "fast" : ms < 5_000 ? "normal" : "slow"; }
+function tpsSpeed(tps: number): SpeedLabel { return tps >= 50 ? "fast" : tps >= 20 ? "normal" : "slow"; }
+export function formatTtft(value: number | undefined): string {
+  return value === undefined || !Number.isFinite(value) ? "~"
+    : `${value < 1_000 ? "1s" : `${Math.max(0, value / 1_000).toFixed(1)}s`}[${ttftSpeed(value)}]`;
+}
+export function formatTps(value: number | undefined, estimated = false): string {
+  return value === undefined || !Number.isFinite(value) ? "~"
+    : `${estimated ? "~" : ""}${Math.max(0, value).toFixed(1)}[${tpsSpeed(value)}]`;
+}
+export function formatResponsePerformance(performance?: ResponsePerformance): string {
+  return `TTFT ${formatTtft(performance?.ttftMs)} · TPS ${formatTps(performance?.tokensPerSecond, performance?.estimated)}`;
+}
+export function formatAveragePerformance(performance?: ResponsePerformance): string {
+  return `TTFT avg ${formatTtft(performance?.ttftMs)} · TPS avg ${formatTps(performance?.tokensPerSecond)}`;
+}
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(Math.max(0, ms) / 1_000);
+  if (seconds < 1) return "<1s";
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+function clean(value: unknown): string {
+  return typeof value === "string" ? value.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "")
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").replace(/\s+/g, " ").trim() : "";
+}
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function shortenPath(value: unknown, cwd: string): string {
+  const input = clean(value); if (!input) return "";
+  const absolute = nodePath.isAbsolute(input) ? nodePath.normalize(input) : nodePath.resolve(cwd, input);
+  const relative = nodePath.relative(cwd, absolute);
+  if (relative === "") return ".";
+  if (relative !== ".." && !relative.startsWith(`..${nodePath.sep}`) && !nodePath.isAbsolute(relative)) return relative;
+  const home = clean(process.env.HOME);
+  if (home) {
+    const homeRelative = nodePath.relative(home, absolute);
+    if (homeRelative === "") return "~";
+    if (homeRelative !== ".." && !homeRelative.startsWith(`..${nodePath.sep}`) && !nodePath.isAbsolute(homeRelative)) return `~/${homeRelative}`;
+  }
+  return absolute;
+}
+function truncateSummary(value: string): string { return value.length > MAX_SUMMARY_LENGTH ? `${value.slice(0, MAX_SUMMARY_LENGTH - 1)}…` : value; }
+export function summarizeTool(toolName: string, args: unknown, cwd: string): string {
+  const input = asRecord(args); if (!input) return "";
+  const path = () => shortenPath(input.path, cwd);
+  switch (toolName) {
+    case "bash": return truncateSummary(clean(input.command));
+    case "read": case "edit": case "write": case "ls": return truncateSummary(path());
+    case "grep": case "find": {
+      const pattern = clean(input.pattern), target = path();
+      return truncateSummary(pattern && target ? `${pattern} in ${target}` : pattern || target);
+    }
+    default: return "";
+  }
+}
+
+export function createActivityTracker(cwd: string, onChange: () => void): ActivityTracker {
+  let phase: RunActivitySnapshot["phase"] = "idle";
+  let turnNumber: number | undefined, startedAt: number | undefined, durationMs: number | undefined;
+  let requestStartedAt: number | undefined, firstTokenAt: number | undefined, performance: ResponsePerformance | undefined;
+  let turns: TurnActivity[] = [];
+  let activeTools = new Map<string, ToolActivity>();
+  let recentTools: ToolActivity[] = [];
+  let completedCount = 0, failedCount = 0;
+  const notify = (): void => onChange();
+  const at = (now?: number): number => Math.max(0, Number.isFinite(now) ? Math.trunc(now as number) : Date.now());
+  const turnNo = (index: number): number => Math.max(0, Number.isFinite(index) ? Math.trunc(index) : 0) + 1;
+  const updateCurrentTurn = (update: (turn: TurnActivity) => TurnActivity): void => {
+    turns = turns.map((turn) => turn.number === turnNumber ? Object.freeze(update(turn)) : turn);
+  };
+  const snapshotPerformance = (): ResponsePerformance | undefined => performance ? Object.freeze({ ...performance }) : undefined;
+  const averagePerformance = (): ResponsePerformance | undefined => {
+    const samples = turns.map((turn) => turn.performance).filter((sample): sample is ResponsePerformance => Boolean(sample));
+    const ttftSamples = samples.map((sample) => sample.ttftMs).filter((value): value is number => value !== undefined && Number.isFinite(value));
+    const tpsSamples = samples.map((sample) => sample.tokensPerSecond).filter((value): value is number => value !== undefined && Number.isFinite(value));
+    if (ttftSamples.length === 0 && tpsSamples.length === 0) return undefined;
+    return Object.freeze({
+      ...(ttftSamples.length > 0 ? { ttftMs: ttftSamples.reduce((sum, value) => sum + value, 0) / ttftSamples.length } : {}),
+      ...(tpsSamples.length > 0 ? { tokensPerSecond: tpsSamples.reduce((sum, value) => sum + value, 0) / tpsSamples.length } : {}),
+    });
+  };
+
+  return {
+    startRun(now): void {
+      phase = "running"; turnNumber = undefined; startedAt = at(now); durationMs = undefined;
+      requestStartedAt = undefined; firstTokenAt = undefined; performance = undefined; turns = [];
+      activeTools = new Map(); recentTools = []; completedCount = 0; failedCount = 0; notify();
+    },
+    startTurn(index, now): void {
+      const number = turnNo(index);
+      if (turnNumber === number && phase === "running") return;
+      phase = "running"; turnNumber = number; durationMs = undefined; performance = undefined;
+      turns = [...turns, Object.freeze({ number, startedAt: at(now), tools: Object.freeze([]) })]; notify();
+    },
+    finishTurn(index, now): void {
+      const number = turnNo(index), endedAt = at(now);
+      turns = turns.map((turn) => turn.number === number && turn.durationMs === undefined
+        ? Object.freeze({ ...turn, durationMs: Math.max(0, endedAt - turn.startedAt), ...(snapshotPerformance() ? { performance: snapshotPerformance() } : {}) })
+        : turn);
+      notify();
+    },
+    startResponse(now): void {
+      requestStartedAt = at(now); firstTokenAt = undefined; performance = undefined; notify();
+    },
+    updateResponseEstimate(tokens, now): void {
+      if (requestStartedAt === undefined || !Number.isFinite(tokens) || tokens <= 0) return;
+      const observedAt = at(now);
+      if (firstTokenAt === undefined) {
+        firstTokenAt = observedAt; performance = Object.freeze({ ttftMs: Math.max(0, observedAt - requestStartedAt) }); notify(); return;
+      }
+      const generationMs = Math.max(0, observedAt - firstTokenAt);
+      if (generationMs <= 0 || !performance) return;
+      performance = Object.freeze({ ...performance, tokensPerSecond: tokens / (generationMs / 1_000), estimated: true }); notify();
+    },
+    finishResponse(tokens, now): void {
+      const first = firstTokenAt; requestStartedAt = undefined; firstTokenAt = undefined;
+      if (first === undefined || !performance) return;
+      const generationMs = Math.max(0, at(now) - first);
+      if (!Number.isFinite(tokens) || tokens <= 0 || generationMs <= 0) return;
+      performance = Object.freeze({ ttftMs: performance.ttftMs, tokensPerSecond: tokens / (generationMs / 1_000) });
+      updateCurrentTurn((turn) => ({ ...turn, performance: snapshotPerformance() })); notify();
+    },
+    startTool(event, now): void {
+      const id = clean(event.toolCallId); if (!id) return;
+      activeTools.set(id, Object.freeze({ id, name: clean(event.toolName) || "tool", summary: summarizeTool(event.toolName, event.args, cwd), status: "running", startedAt: at(now) }));
+      phase = "running"; durationMs = undefined; notify();
+    },
+    finishTool(event, now): void {
+      const id = clean(event.toolCallId), active = activeTools.get(id); if (!active) return;
+      activeTools.delete(id);
+      const status: ToolActivityStatus = event.isError ? "failed" : "done";
+      const completed = Object.freeze({ ...active, status, durationMs: Math.max(0, at(now) - active.startedAt) });
+      if (status === "failed") failedCount += 1; else completedCount += 1;
+      updateCurrentTurn((turn) => ({ ...turn, tools: Object.freeze([...turn.tools, completed]) }));
+      recentTools = [completed, ...recentTools].slice(0, 3); notify();
+    },
+    settle(now): void {
+      if ((phase === "idle" || phase === "settled") && activeTools.size === 0) return;
+      const endedAt = at(now);
+      for (const active of activeTools.values()) {
+        const failed = Object.freeze({ ...active, status: "failed" as const, durationMs: Math.max(0, endedAt - active.startedAt) });
+        updateCurrentTurn((turn) => ({ ...turn, tools: Object.freeze([...turn.tools, failed]) }));
+        recentTools.unshift(failed); failedCount += 1;
+      }
+      activeTools = new Map(); recentTools = recentTools.slice(0, 3);
+      if (turnNumber !== undefined) {
+        turns = turns.map((turn) => turn.number === turnNumber && turn.durationMs === undefined
+          ? Object.freeze({ ...turn, durationMs: Math.max(0, endedAt - turn.startedAt), ...(snapshotPerformance() ? { performance: snapshotPerformance() } : {}) }) : turn);
+      }
+      phase = "settled"; durationMs = Math.max(0, endedAt - (startedAt ?? endedAt)); notify();
+    },
+    reset(): void {
+      phase = "idle"; turnNumber = undefined; startedAt = undefined; durationMs = undefined;
+      requestStartedAt = undefined; firstTokenAt = undefined; performance = undefined; turns = [];
+      activeTools = new Map(); recentTools = []; completedCount = 0; failedCount = 0; notify();
+    },
+    getSnapshot(): RunActivitySnapshot {
+      return Object.freeze({ phase, ...(turnNumber === undefined ? {} : { turnNumber }), ...(startedAt === undefined ? {} : { startedAt }),
+        ...(durationMs === undefined ? {} : { durationMs }), ...(performance ? { performance: snapshotPerformance() } : {}),
+        ...(averagePerformance() ? { averagePerformance: averagePerformance() } : {}),
+        turns: Object.freeze(turns.map((turn) => Object.freeze({ ...turn, tools: Object.freeze([...turn.tools]) }))),
+        activeTools: Object.freeze([...activeTools.values()]), recentTools: Object.freeze([...recentTools]), completedCount, failedCount });
+    },
+  };
+}

package/extensions/ctx/data.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createReadTool, SessionManager } from "@earendil-works/pi-coding-agent";
+import { estimateContext, installContextEstimates, messagesFromContextEntries } from "./data.ts";
+
+const result = (n: number) => ({ role: "toolResult", toolName: "fabric_exec", toolCallId: String(n), content: [{ type: "text", text: "x".repeat(n * 4) }], details: { fullOutput: "x".repeat(100000), operations: [{ toolName: "read" }] } });
+const tool = { name: "fabric_exec", description: "Execute TypeScript", parameters: createReadTool(process.cwd()).parameters };
+
+test("context estimate keeps tool schemas, summaries, images and active branch semantics", () => {
+  const snapshot = estimateContext([{role:"user",content:"abcd"}, result(4), {role:"compactionSummary",summary:"abcd"}], "abcd", "context hook", [tool]);
+  assert.equal(snapshot.categories.find(c => c.name === "Tools")?.tokens, Math.ceil(JSON.stringify(tool).length / 4));
+  assert.equal(snapshot.categories.find(c => c.name === "Summary")?.tokens, 28);
+  assert.ok(snapshot.total > 0);
+  assert.equal(estimateContext([{role:"user",content:[{type:"image",data:"x".repeat(10000)}]}]).total, 0);
+});
+
+test("tracker filters active tools, refreshes schemas, caches snapshots and resets", () => {
+  const handlers = new Map<string, Function>();
+  let active = ["fabric_exec"];
+  let all = [tool];
+  const tracker = installContextEstimates({
+    on: (name: string, fn: Function) => handlers.set(name, fn),
+    getActiveTools: () => active,
+    getAllTools: () => all,
+  } as any, () => {});
+  const ctx = {sessionManager: SessionManager.inMemory(), getSystemPrompt: () => ""};
+  handlers.get("session_start")!({}, ctx);
+  assert.equal(tracker.getSnapshot().source, "active branch");
+  const cached = tracker.getSnapshot();
+  assert.strictEqual(tracker.getSnapshot(), cached);
+  active = [];
+  handlers.get("agent_settled")!({}, ctx);
+  assert.equal(tracker.getSnapshot().categories.find(c => c.name === "Tools")?.tokens, 0);
+  handlers.get("session_shutdown")!();
+  assert.equal(tracker.getSnapshot().source, "unavailable");
+});
+
+test("delta tracks the previous settled run and resets", () => {
+  const handlers = new Map<string, Function>();
+  const tracker = installContextEstimates({
+    on: (name: string, fn: Function) => handlers.set(name, fn),
+    getActiveTools: () => [],
+    getAllTools: () => [],
+  } as any, () => {});
+  const session = SessionManager.inMemory();
+  const ctx = { sessionManager: session, getSystemPrompt: () => "" };
+  handlers.get("session_start")!({}, ctx);
+  assert.equal(tracker.getSnapshot().total, 0);
+  session.appendMessage({ role: "user", content: [{ type: "text", text: "x".repeat(4000) }] } as any);
+  handlers.get("turn_end")!({}, ctx);
+  assert.equal(tracker.getDelta(), 1000);
+  handlers.get("agent_settled")!({}, ctx);
+  assert.equal(tracker.getDelta(), 1000);
+  handlers.get("turn_end")!({}, ctx);
+  assert.equal(tracker.getDelta(), 0);
+  session.appendMessage({ role: "user", content: [{ type: "text", text: "x".repeat(400) }] } as any);
+  handlers.get("agent_settled")!({}, ctx);
+  assert.equal(tracker.getDelta(), 100);
+  handlers.get("session_compact")!({}, ctx);
+  assert.equal(tracker.getDelta(), undefined);
+  assert.equal(tracker.getSnapshot().total, 1100);
+});
+test("converts custom context entries", () => {
+  assert.equal(messagesFromContextEntries([{type:"custom_message",content:"ok"}]).length, 1);
+});

package/extensions/ctx/data.ts

@@ -0,0 +1,230 @@
+import { convertToLlm, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+
+const knownRoles = new Set(["user", "assistant", "toolResult", "custom", "bashExecution", "compactionSummary", "branchSummary"]);
+
+export const CONTEXT_CATEGORIES = ["System", "Tools", "Messages", "Tool Results", "Summary", "Other"] as const;
+export type ContextCategory = typeof CONTEXT_CATEGORIES[number];
+export type ImagesWireEstimate = {
+  readonly images: number;
+  readonly source: "message" | "provider payload" | "unavailable";
+};
+export type ContextEstimate = {
+  readonly categories: readonly { name: ContextCategory; tokens: number | undefined; percent: number | undefined }[];
+  readonly total: number;
+  readonly imagesWire: ImagesWireEstimate;
+  readonly source: "context hook" | "active branch" | "unavailable";
+};
+type RecordValue = Record<string, unknown>;
+const record = (value: unknown): RecordValue => value !== null && typeof value === "object" ? value as RecordValue : {};
+const text = (value: unknown): string => typeof value === "string" ? value : "";
+
+function isImageNode(value: RecordValue): boolean {
+  return value.type === "image" || value.type === "image_url" || value.type === "input_image";
+}
+
+function countImages(value: unknown, source: "message" | "provider payload"): ImagesWireEstimate {
+  if (value === undefined || value === null) return { images: 0, source: "unavailable" };
+  let images = 0;
+  const seen = new WeakSet<object>();
+  const visit = (node: unknown): void => {
+    if (node === null || typeof node !== "object" || seen.has(node)) return;
+    seen.add(node);
+    if (isImageNode(record(node))) images++;
+    else for (const child of Object.values(node)) visit(child);
+    seen.delete(node);
+  };
+  visit(value);
+  return { images, source };
+}
+
+/** Local text heuristic, not a model tokenizer or provider usage measurement. */
+export const estimateTextTokens = (value: string): number => Math.ceil(value.length / 4);
+
+function contentText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value.map((item) => {
+    const block = record(item);
+    if (block.type === "text") return text(block.text);
+    if (block.type === "thinking") return text(block.thinking);
+    if (block.type === "toolCall") return text(block.name) + JSON.stringify(block.arguments ?? {});
+    // Images, signatures and provider-specific blocks have unknown cost.
+    return "";
+  }).join("");
+}
+
+type ToolDefinition = Pick<ReturnType<ExtensionAPI["getAllTools"]>[number], "name" | "description" | "parameters">;
+
+/** Estimate the active schema fallback when no provider payload has been observed. */
+function estimateToolTokens(tools: readonly ToolDefinition[] | undefined): number | undefined {
+  if (tools === undefined) return undefined;
+  try {
+    return tools.reduce((sum, { name, description, parameters }) => {
+      if (typeof name !== "string" || typeof description !== "string" || !parameters) {
+        throw new Error("Incomplete tool definition");
+      }
+      return sum + estimateTextTokens(JSON.stringify({ name, description, parameters }));
+    }, 0);
+  } catch {
+    // Unserializable schemas are unknown, never a misleading partial total or zero.
+    return undefined;
+  }
+}
+
+/** Estimate the serialized tools field from the provider-specific request payload. */
+export function estimateProviderToolsTokens(payload: unknown): number | undefined {
+  if (payload === null || typeof payload !== "object") return undefined;
+  const tools = (payload as Record<string, unknown>).tools;
+  if (tools === undefined) return 0;
+  try {
+    const serialized = JSON.stringify(tools);
+    return serialized === undefined ? undefined : estimateTextTokens(serialized);
+  } catch {
+    return undefined;
+  }
+}
+
+function activeToolDefinitions(pi: ExtensionAPI): readonly ToolDefinition[] | undefined {
+  try {
+    const active = [...new Set(pi.getActiveTools())];
+    if (active.length === 0) return [];
+    const all = new Map(pi.getAllTools().map(tool => [tool.name, tool]));
+    const tools = active.map(name => all.get(name));
+    if (tools.some(tool => tool === undefined)) return undefined;
+    return tools as ToolDefinition[];
+  } catch {
+    return undefined;
+  }
+}
+
+export function estimateContext(
+  messages: readonly unknown[] | undefined,
+  systemPrompt?: string,
+  source: ContextEstimate["source"] = "unavailable",
+  tools?: readonly ToolDefinition[],
+  imagesWire?: ImagesWireEstimate,
+): ContextEstimate {
+  const counts: Record<ContextCategory, number | undefined> = {
+    System: systemPrompt === undefined ? undefined : estimateTextTokens(systemPrompt),
+    Tools: estimateToolTokens(tools), Messages: messages ? 0 : undefined,
+    "Tool Results": messages ? 0 : undefined, Summary: messages ? 0 : undefined, Other: messages ? 0 : undefined,
+  };
+  for (const value of messages ?? []) {
+    const message = record(value);
+    if (message.role === "bashExecution" && message.excludeFromContext) continue;
+    const category: ContextCategory = message.role === "toolResult" ? "Tool Results"
+      : message.role === "compactionSummary" || message.role === "branchSummary" ? "Summary"
+      : message.role === "user" || message.role === "assistant" ? "Messages" : "Other";
+    // Let the public SDK supply summary/bash wrappers; retain the original role for attribution.
+    // Unknown extension roles safely fall back to observable outer content only.
+    const body = knownRoles.has(text(message.role))
+      ? convertToLlm([value as Parameters<typeof convertToLlm>[0][number]])
+        .map(converted => contentText(converted.content)).join("")
+      : contentText(message.content);
+    const tokens = estimateTextTokens(body);
+    counts[category] = (counts[category] ?? 0) + tokens;
+  }
+  const total = Object.values(counts).reduce<number>((sum, value) => sum + (value ?? 0), 0);
+  const percent = (tokens: number | undefined): number | undefined => tokens === undefined || total === 0 ? undefined : tokens / total * 100;
+  return {
+    total, source,
+    imagesWire: imagesWire ?? countImages(messages, "message"),
+    categories: CONTEXT_CATEGORIES.map(name => ({ name, tokens: counts[name], percent: percent(counts[name]) })),
+  };
+}
+
+/** Only compaction-applied active entries; never reads JSONL or tool details. */
+export function messagesFromContextEntries(entries: readonly unknown[]): unknown[] {
+  return entries.flatMap((value): unknown[] => {
+    const entry = record(value);
+    if (entry.type === "message") return [entry.message];
+    if (entry.type === "compaction") return [{ role: "compactionSummary", summary: entry.summary }];
+    if (entry.type === "branch_summary") return [{ role: "branchSummary", summary: entry.summary }];
+    if (entry.type === "custom_message") return [{ role: "custom", content: entry.content }];
+    return [];
+  });
+}
+
+export function installContextEstimates(pi: ExtensionAPI, onChange: () => void): {
+  getSnapshot(): ContextEstimate;
+  getDelta(): number | undefined;
+  resetDelta(): void;
+} {
+  let snapshot = estimateContext(undefined);
+  let settledTotal: number | undefined;
+  let delta: number | undefined;
+  let latestProviderImagesWire: ImagesWireEstimate | undefined;
+  let latestProviderToolsTokens: number | undefined;
+  const restore = (ctx: ExtensionContext, keepProviderMeasurement = false): void => {
+    if (!keepProviderMeasurement) {
+      latestProviderImagesWire = undefined;
+      latestProviderToolsTokens = undefined;
+    }
+    const messages = messagesFromContextEntries(ctx.sessionManager.buildContextEntries());
+    snapshot = estimateContext(messages, ctx.getSystemPrompt(), "active branch", activeToolDefinitions(pi), latestProviderImagesWire);
+    if (keepProviderMeasurement && latestProviderToolsTokens !== undefined) {
+      const categories = snapshot.categories.map((category) =>
+        category.name === "Tools" ? { ...category, tokens: latestProviderToolsTokens } : category,
+      );
+      const total = categories.reduce((sum, category) => sum + (category.tokens ?? 0), 0);
+      const percent = (tokens: number | undefined): number | undefined =>
+        tokens === undefined || total === 0 ? undefined : tokens / total * 100;
+      snapshot = {
+        ...snapshot,
+        total,
+        categories: categories.map((category) => ({ ...category, percent: percent(category.tokens) })),
+      };
+    }
+    onChange();
+  };
+  // A run is one user question, measured against the total left by the previous
+  // settled run, so compaction losses surface as a negative delta.
+  const measure = (ctx: ExtensionContext, settled: boolean): void => {
+    restore(ctx, true);
+    delta = settledTotal === undefined ? undefined : snapshot.total - settledTotal;
+    if (settled) settledTotal = snapshot.total;
+  };
+  const resetDelta = (ctx: ExtensionContext): void => {
+    restore(ctx);
+    settledTotal = snapshot.total;
+    delta = undefined;
+  };
+  pi.on("context", (event, ctx) => {
+    latestProviderImagesWire = undefined;
+    latestProviderToolsTokens = undefined;
+    snapshot = estimateContext(event.messages, ctx.getSystemPrompt(), "context hook", activeToolDefinitions(pi));
+    onChange();
+  });
+  pi.on("before_provider_request", (event) => {
+    latestProviderImagesWire = countImages(event.payload, "provider payload");
+    const tools = estimateProviderToolsTokens(event.payload);
+    latestProviderToolsTokens = tools;
+    const categories = snapshot.categories.map((category) =>
+      category.name === "Tools" ? { ...category, tokens: tools } : category,
+    );
+    const total = categories.reduce((sum, category) => sum + (category.tokens ?? 0), 0);
+    const percent = (tokens: number | undefined): number | undefined =>
+      tokens === undefined || total === 0 ? undefined : tokens / total * 100;
+    snapshot = {
+      ...snapshot,
+      total,
+      categories: categories.map((category) => ({ ...category, percent: percent(category.tokens) })),
+      imagesWire: latestProviderImagesWire,
+    };
+    onChange();
+  });
+  pi.on("session_start", (_event, ctx) => resetDelta(ctx));
+  pi.on("session_tree", (_event, ctx) => resetDelta(ctx));
+  pi.on("session_compact", (_event, ctx) => resetDelta(ctx));
+  pi.on("agent_settled", (_event, ctx) => measure(ctx, true));
+  pi.on("turn_end", (_event, ctx) => measure(ctx, false));
+  pi.on("session_shutdown", () => {
+    latestProviderImagesWire = undefined;
+    latestProviderToolsTokens = undefined;
+    snapshot = estimateContext(undefined);
+    settledTotal = undefined;
+    delta = undefined;
+  });
+  return { getSnapshot: () => snapshot, getDelta: () => delta, resetDelta: () => settledTotal = snapshot.total };
+}