@caph42/pi-ccline 0.1.1 → 0.2.0

package/README.md

@@ -18,12 +18,14 @@ pi session state → buildCclineInput() → JSON → ccline (spawn, COLUMNS=curr
 | Reasoning effort | `ctx.thinkingLevel` → `effort.level` |
 | Working directory | `ctx.cwd` → `cwd` / `workspace.current_dir` |
 | Context percentage / token count | `ctx.getContextUsage()` → current context (the aggregate estimate); **no lifetime session tokens are sent** |
+| Prompt-cache hit share | assistant messages' `usage.cacheRead` over `input + cacheRead + cacheWrite`, summed over the branch → `prompt_cache.hit_ratio`; sent from the second request on |
+| Output speed (`tok/s`) | measured from `message_start` → first `message_update` → `message_end`, written to ccline's `bridge/<session>.json` for its `timing.tps` metric |
 | Cost, session duration | assistant messages' `usage.cost.total` summed; duration = now − earliest entry on the branch |
 | Session id / name | `ctx.sessionManager` |
 | git branch and anything else ccline probes itself | ccline reads the disk itself |
 | Status lines from other extensions | `footerData.getExtensionStatuses()`, sorted by key into one line below the ccline frame |
 
-Not shown, and never fabricated: the 5h / 7d quota segment (pi has no `rate_limits` source, the field is omitted, and the segment disappears by itself).
+Not shown, and never fabricated: the 5h / 7d quota segment (pi has no `rate_limits` source, the field is omitted, and the segment disappears by itself), and the cache warmth / TTL / miss-cause fields (pi knows neither the provider's cache expiry nor why a cache was rebuilt, so only the hit share is sent and ccline is left to hide the rest).
 
 ## Installation
 
@@ -102,6 +104,8 @@ Binary resolution order: `config.binary` → `~/.claude/ccline/ccline` → `ccli
 - Because there is only one footer slot globally, other extensions' custom footers (e.g. pi-cursor-provider's fast badge) get displaced once this extension is installed; their status lines still show. Conversely, when they take over, the ccline frame disappears and `/pi-ccline on` takes it back.
 - **The provider can only be folded into the model segment.** ccline 2.0.1's input schema has no provider field and the `model` segment renders only `display_name`, so the provider is appended after the model name as `name (provider)`; it isn't appended twice when the name already carries the same suffix. `showProvider: false` turns it off. **At narrow widths the provider may be invisible**: ccline wraps/truncates by `COLUMNS` itself, and in practice at width 40 the model segment is left with just `GPT-5.6` — that's upstream layout behaviour, and this extension only guarantees the provider is written into `display_name`.
 - The input JSON **omits the `version` field**: ccline 2.0.1 validates it as a Claude Code version and rejects pi's version outright.
+- **Cache hit share:** `prompt_cache` is sent only from the second assistant message on. That is ccline's own display gate (`requests > 1`), whose rationale is that a single request usually only writes the cache — an initial request can still hit a prefix cached by an earlier session, so the gate is display behaviour, not a claim about request #1. Sending `hit_ratio` before that gate would also make ccline fall back to its "cold" wording, which pi cannot assert. `current_usage` deliberately still carries only `input_tokens`: pi's context estimate already includes the cached tokens, and ccline sums the `current_usage` fields when `total_input_tokens` is absent, so adding the cache counts there would double-count them in the context bar.
+- **Output speed goes through ccline's bridge, not stdin.** ccline's `timing.tps` / `timing.ttft` metrics read `bridge/<session>.json` under its data dir (`$CCLINE_HOME` or `~/.claude/ccline`), the file its companion mod writes inside Claude Code. The statusline payload has no per-request timing, so this extension measures it from `message_start` / `message_update` / `message_end` and writes the same documented `v: 1` shape, atomically, once per finished answer. ttft is stream start → first content block; pi emits `message_start` when the provider starts responding, so that number excludes the connect wait. tps divides the answer's output tokens by the time from the first content block to `message_end`, so the wait for the first token is not counted as generation. Durations use a monotonic clock (`performance.now()`); only the bridge's freshness stamp is wall-clock. The file is removed on `session_shutdown`, and ccline ignores bridges older than 6h.
 - No runtime dependencies: only `node:child_process` / `node:fs` / `node:os` / `node:path` plus the pi peer package `@earendil-works/pi-tui`.
 - Non-TUI modes (`-p`, json, rpc) install no footer and spawn nothing.
 - The extension's own config lives at `~/.pi/agent/pi-ccline/config.json`; pi's `settings.json` is never touched.
@@ -129,7 +133,9 @@ node --experimental-strip-types scripts/render-once.ts --home "$(mktemp -d)" --b
 ## Known limitations
 
 - **The 5h / 7d quota segment is always empty.** pi provides no `rate_limits`, the field is omitted entirely, and ccline shows nothing.
-- **ccline writes `~/.claude/ccline/state/`** (session state, model cache, update.lock). That's upstream behaviour and cannot be disabled here.
+- **ccline writes `~/.claude/ccline/state/`** (session state, model cache, update.lock). That's upstream behaviour and cannot be disabled here. The extension additionally writes `~/.claude/ccline/bridge/<session>.json` for the `timing.tps` segment, and deletes it when the session shuts down.
+- **The cache segment shows only the hit share.** Warmth, TTL countdown, miss counts and miss causes need data pi does not have (the provider's cache expiry and rebuild reasons), so those fields are omitted — with a config `format` of `{hit}% hit` the segment reduces to that one number, and before the second request it disappears entirely rather than claiming "cold".
+- **`tok/s` describes the last finished answer, not a running average.** It is measured per request and only updates when an answer ends (a non-streaming provider, or a streamed answer of a few tokens, produces no sample and leaves the previous value on screen until the next one arrives). `duration` and `tok/s` are unrelated numbers: duration is session wall-clock, tps is streaming speed.
 - **External binary required.** Without `ccline` the footer is a single install hint; upgrading `ccline` needs no extension restart, but the binary path stays cached until the next resolution (`/pi-ccline on` or a new session recomputes it).
 - **Upstream compatibility only covers tested versions.** Every field in ccline 2.0.1's `input.rs` is `Option` with lenient deserialization, so a field changing shape within the same major version usually just makes that segment disappear; but required fields have changed across majors before (1.1.x → 2.0.x), so re-run `scripts/render-once.ts` after upgrading ccline.
 - **Nerd Font v3+ required.** Missing icon fonts render as boxes; Windows is untested.
@@ -150,6 +156,7 @@ extensions/pi-ccline/
   binary.ts   path resolution/caching, spawn with timeout and abort, --version probing
   render.ts   output normalization: line splitting, truncation by visible width, stale marker
   refresh.ts  single-flight + throttle + latest-wins scheduler, and the timer that drives `duration`
+  turn.ts     per-request timing from the stream, plus the ccline bridge file for `timing.tps`
   config.ts   config read/write
   *.test.ts   node --test
 scripts/render-once.ts   run the real ccline once against a fixture

package/README_zh.md

@@ -18,12 +18,14 @@ pi 会话状态 → buildCclineInput() → JSON → ccline（spawn，COLUMNS=当
 | 推理强度 | `ctx.thinkingLevel` → `effort.level` |
 | 工作目录 | `ctx.cwd` → `cwd` / `workspace.current_dir` |
 | 上下文百分比 / token 数 | `ctx.getContextUsage()` → 当前上下文（聚合估计值）；**不发会话累计 token** |
+| 缓存命中率 | assistant 消息的 `usage.cacheRead` 除以 `input + cacheRead + cacheWrite`，在分支上累加 → `prompt_cache.hit_ratio`；从第二次请求起才发送 |
+| 输出速度（`tok/s`） | 由 `message_start` → 首个 `message_update` → `message_end` 实测，写入 ccline 的 `bridge/<session>.json` 供 `timing.tps` 读取 |
 | 成本、会话时长 | assistant 消息 `usage.cost.total` 累加；时长 = 当前时间 − 分支最早 entry |
 | 会话 id / 名称 | `ctx.sessionManager` |
 | git 分支等 ccline 自行探测的信息 | ccline 自己读磁盘 |
 | 其他扩展的 status | `footerData.getExtensionStatuses()`，按 key 排序拼成一行放在 ccline 帧下方 |
 
-不显示、也不会伪造的：5h / 7d 配额段（pi 没有 `rate_limits` 数据源，字段不传，该段自动消失）。
+不显示、也不会伪造的：5h / 7d 配额段（pi 没有 `rate_limits` 数据源，字段不传，该段自动消失）；缓存冷热 / TTL 倒计时 / miss 次数与原因（pi 既不知道 provider 的缓存过期时间，也不知道缓存为何重建，所以只发命中率，其余字段交给 ccline 自己隐藏）。
 
 ## 安装
 
@@ -102,6 +104,8 @@ pi install .
 - 因为 footer 槽位全局只有一个，本扩展装上后其他扩展的自定义 footer（例如 pi-cursor-provider 的 fast 徽标）会被顶掉；它们的 status 行仍会显示。反过来它们抢占时 ccline 帧会消失，需要 `/pi-ccline on` 取回。
 - **provider 只能拼进模型段。** ccline 2.0.1 的输入 schema 没有 provider 字段，`model` 段只渲染 `display_name`，所以 provider 以 `名称 (provider)` 的形式追加在模型名后；名字里已经带同样的后缀时不重复追加。`showProvider: false` 可关掉。**窄宽度下 provider 可能看不到**：ccline 按 `COLUMNS` 自己折行/截断，实测宽度 40 时模型段只剩 `GPT-5.6`，这是上游布局行为，本扩展只保证把 provider 写进 `display_name`。
 - 输入 JSON **省略 `version` 字段**：ccline 2.0.1 会把它当 Claude Code 版本校验，传 pi 的版本会被直接拒绝。
+- **缓存命中率：** `prompt_cache` 从第二条 assistant 消息起才发。这是 ccline 自己的显示门槛（`requests > 1`），它的理由是一次请求通常只是在写缓存——但首个请求确实可能命中之前会话已缓存的 prefix，所以这是显示行为，不是对「第一次请求」的事实断言。若在门槛前就发 `hit_ratio`，ccline 还会回退到 `cold` 文案，而那是 pi 无法断言的。`current_usage` 仍然只填 `input_tokens`：pi 的上下文估计值本就包含缓存 token，而缺少 `total_input_tokens` 时 ccline 会把 `current_usage` 各项相加，把 cache 数填进去会让它们被重复计入上下文进度条。
+- **输出速度走 ccline 的 bridge，不走 stdin。** ccline 的 `timing.tps` / `timing.ttft` 读的是其数据目录（`$CCLINE_HOME` 或 `~/.claude/ccline`）下的 `bridge/<session>.json`，也就是它家在 Claude Code 里的伴生 mod 写的文件。statusline 载荷里没有单次请求耗时，所以本扩展用 `message_start` / `message_update` / `message_end` 自己计时，并按同样的 `v: 1` 结构原子写入，每个答完的请求写一次。ttft = 流开始 → 首个内容块；pi 是在 provider 开始响应后才发 `message_start`，所以这个数不含建立连接的等待。tps = 该回答的 output token 除以「首个内容块 → `message_end`」的时长，所以等首字的耗时不算进生成速度。计时用单调时钟（`performance.now()`），只有 bridge 的新鲜度标记用墙钟。`session_shutdown` 时删除该文件；ccline 也会忽略超过 6 小时的 bridge。
 - 没有运行时依赖，只用 `node:child_process` / `node:fs` / `node:os` / `node:path` 和 pi 提供的 peer 包 `@earendil-works/pi-tui`。
 - 非 TUI 模式（`-p`、json、rpc）不安装 footer、不 spawn。
 - 扩展自己的配置写在 `~/.pi/agent/pi-ccline/config.json`，不碰 pi 的 `settings.json`。
@@ -129,7 +133,9 @@ node --experimental-strip-types scripts/render-once.ts --home "$(mktemp -d)" --b
 ## 已知限制
 
 - **5h / 7d 配额段永远为空。** pi 不提供 `rate_limits`，字段整段省略，ccline 自然不显示。
-- **ccline 会写 `~/.claude/ccline/state/`**（会话状态、模型缓存、update.lock）。这是上游行为，扩展无法关闭。
+- **ccline 会写 `~/.claude/ccline/state/`**（会话状态、模型缓存、update.lock）。这是上游行为，扩展无法关闭。另外本扩展会写 `~/.claude/ccline/bridge/<session>.json` 供 `timing.tps` 段使用，会话关闭时删掉。
+- **缓存段只显示命中率。** 冷热状态、TTL 倒计时、miss 次数与原因需要 pi 没有的数据（provider 的缓存过期时间、重建原因），这些字段一律不发；配置里用 `format = "{hit}% hit"` 就只剩这一个数字，而第二次请求之前整段直接消失，而不是谎称 `cold`。
+- **`tok/s` 描述的是最后一次答完的请求，不是滚动平均。** 它按请求实测，只在回答结束时更新（非流式 provider、或只有几个 token 的回答不会产生样本，上一轮的数值会继续显示到下一次更新）。`duration` 和 `tok/s` 没有关系：前者是会话墙钟时长，后者是流式速度。
 - **依赖外部二进制。** 没有 `ccline` 时 footer 只有一行安装提示；升级 `ccline` 后无需重启扩展，但二进制路径会被缓存到下一次解析（`/pi-ccline on` 或新会话会重算）。
 - **上游兼容性只覆盖已测版本。** ccline 2.0.1 的 `input.rs` 每个字段都是 `Option` + lenient 反序列化，同一大版本内字段换形状一般只会让对应段消失；但大版本之间已经发生过必填字段变化（1.1.x → 2.0.x），升级 ccline 后请用 `scripts/render-once.ts` 复跑一次。
 - **需要 Nerd Font v3+。** 图标字体缺失时会显示成方块；Windows 未测试。
@@ -150,6 +156,7 @@ extensions/pi-ccline/
   binary.ts   路径解析/缓存、带超时与中止的 spawn、--version 探测
   render.ts   输出归一化：分行、按可见宽度截断、stale 标记
   refresh.ts  单飞 + 节流 + latest-wins 调度器，以及驱动 `耗时` 的定时器
+  turn.ts     从流事件实测单次请求耗时，并写 ccline 的 bridge 文件供 `timing.tps`
   config.ts   配置读写
   *.test.ts   node --test
 scripts/render-once.ts   用 fixture 跑一次真实 ccline

package/extensions/pi-ccline/footer.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, test } from "node:test";
@@ -318,7 +318,7 @@ function fakePi() {
 		},
 		registerCommand: () => {},
 	};
-	const dispatch = (name: string, ctx: unknown) => handlers.get(name)?.({ type: name }, ctx);
+	const dispatch = (name: string, ctx: unknown, event: Record<string, unknown> = {}) => handlers.get(name)?.({ type: name, ...event }, ctx);
 	return { pi, handlers, dispatch };
 }
 
@@ -383,6 +383,70 @@ test("agent_start ticks the footer and agent_end leaves no periodic refresh behi
 	await dispatch("session_shutdown", ctx);
 });
 
+test("writes ccline's timing bridge from the streamed answer", async () => {
+	const cclineHome = tempDir("pi-ccline-bridge-");
+	const previousHome = process.env.CCLINE_HOME;
+	process.env.CCLINE_HOME = cclineHome;
+	try {
+		const binary = fakeBinary("cat > /dev/null; printf 'FAKE-CCLINE\\n'");
+		const { pi, handlers, dispatch } = fakePi();
+		piCcline(pi as never, { loadConfig: () => ({ ...DEFAULT_CONFIG, binary }) });
+		for (const event of ["message_start", "message_update", "message_end"]) {
+			assert.ok(handlers.has(event), `${event} is wired`);
+		}
+
+		const { ctx } = fakeSession({ idle: true, binary });
+		await dispatch("session_start", ctx);
+
+		const assistant = { role: "assistant", model: "claude-sonnet-4-5", usage: { output: 500 } };
+		await dispatch("message_start", ctx, { message: assistant });
+		await sleep(120);
+		await dispatch("message_update", ctx, { message: assistant });
+		await sleep(220);
+		await dispatch("message_end", ctx, { message: assistant });
+
+		const bridge = JSON.parse(readFileSync(join(cclineHome, "bridge", "sess-1.json"), "utf8"));
+		assert.equal(bridge.v, 1);
+		assert.equal(bridge.session, "sess-1");
+		assert.equal(bridge.turn.model, "claude-sonnet-4-5");
+		assert.equal(bridge.turn.output_tokens, 500);
+		assert.ok(bridge.turn.ttft_ms >= 100, "ttft covers the wait before the first token");
+		assert.ok(bridge.turn.tps > 0 && Number.isFinite(bridge.turn.tps));
+
+		await dispatch("session_shutdown", ctx);
+		assert.equal(existsSync(join(cclineHome, "bridge", "sess-1.json")), false, "a closed session leaves no bridge");
+	} finally {
+		if (previousHome === undefined) delete process.env.CCLINE_HOME;
+		else process.env.CCLINE_HOME = previousHome;
+	}
+});
+
+test("ignores message events that are not the assistant's answer", async () => {
+	const cclineHome = tempDir("pi-ccline-bridge-role-");
+	const previousHome = process.env.CCLINE_HOME;
+	process.env.CCLINE_HOME = cclineHome;
+	try {
+		const binary = fakeBinary("cat > /dev/null; printf 'FAKE-CCLINE\\n'");
+		const { pi, dispatch } = fakePi();
+		piCcline(pi as never, { loadConfig: () => ({ ...DEFAULT_CONFIG, binary }) });
+		const { ctx } = fakeSession({ idle: true, binary });
+		await dispatch("session_start", ctx);
+
+		// A user message or tool result carries no model timing.
+		for (const role of ["user", "toolResult"]) {
+			const message = { role, usage: { output: 500 } };
+			await dispatch("message_start", ctx, { message });
+			await dispatch("message_update", ctx, { message });
+			await dispatch("message_end", ctx, { message });
+		}
+		assert.equal(existsSync(join(cclineHome, "bridge")), false, "no timing is attributed to non-answers");
+		await dispatch("session_shutdown", ctx);
+	} finally {
+		if (previousHome === undefined) delete process.env.CCLINE_HOME;
+		else process.env.CCLINE_HOME = previousHome;
+	}
+});
+
 test("a footer installed mid-run ticks without waiting for the next turn", async () => {
 	const counter = join(tempDir("pi-ccline-lifecycle-midrun-"), "count");
 	const binary = fakeBinary(

package/extensions/pi-ccline/index.ts

@@ -6,6 +6,7 @@ import { loadConfig, saveConfig, type PiCclineConfig } from "./config.ts";
 import { buildCclineInput, collectSnapshot } from "./input.ts";
 import { RefreshScheduler, RefreshTicker } from "./refresh.ts";
 import { extensionStatusLine, loadingNotice, missingBinaryNotice, normalizeFrame, noticeFrame, withStaleMarker } from "./render.ts";
+import { removeTurnBridge, TurnMeter, writeTurnBridge } from "./turn.ts";
 
 /** Structural subsets so the footer does not depend on pi-tui internals. */
 type TuiLike = { requestRender(force?: boolean): void };
@@ -16,6 +17,11 @@ type FooterDataLike = {
 	getExtensionStatuses?(): ReadonlyMap<string, string>;
 };
 
+/** The slice of a pi message event this extension reads. */
+type MessageEventLike = {
+	message?: { role?: string | undefined; model?: string | undefined; usage?: { output?: number | undefined } | undefined } | undefined;
+};
+
 const DEFAULT_WIDTH = 120;
 
 /**
@@ -57,12 +63,16 @@ export class CclineFooter {
 	private footerData: FooterDataLike | null = null;
 	private requestRenderFn: (() => void) | null = null;
 	private branchUnsubscribe: (() => void) | null = null;
+	/** Session whose ccline bridge this footer wrote, removed again on dispose. */
+	private bridgeSessionId: string | null = null;
+	private readonly meter = new TurnMeter();
 	private disposed = false;
 
 	readonly stats = {
 		refreshes: 0,
 		lastRefreshAt: null as number | null,
 		lastDurationMs: null as number | null,
+		lastTps: null as number | null,
 	};
 	resolved: ResolvedBinary = { path: null, source: "missing" };
 
@@ -136,6 +146,56 @@ export class CclineFooter {
 		return this.lastError;
 	}
 
+	/** The session pi reports, or null when it cannot be read or is unusable. */
+	private sessionId(): string | null {
+		try {
+			const id = this.ctx.sessionManager.getSessionId?.();
+			return typeof id === "string" && id.trim() ? id.trim() : null;
+		} catch {
+			return null;
+		}
+	}
+
+	/** A model request went out: start timing until its answer finishes. */
+	onMessageStart(event: MessageEventLike): void {
+		const message = event.message;
+		if (!message || message.role !== "assistant") return;
+		// Stream start, not send time: pi begins the stream once the provider has
+		// answered, so this ttft stops short of the connect wait by design.
+		this.meter.start(message.model, performance.now());
+	}
+
+	/**
+	 * A content block of that answer arrived (`text_start` / `*_delta` /
+	 * `toolcall_*`; pi emits no metadata through this event), so the clock for
+	 * the streaming rate starts at the first sign of content.
+	 */
+	onMessageUpdate(event: MessageEventLike): void {
+		if (event.message?.role !== "assistant") return;
+		this.meter.firstDelta(performance.now());
+	}
+
+	/**
+	 * The answer finished: hand ccline its timing through the bridge file it
+	 * reads for `timing.tps`. No speed, no file.
+	 */
+	onMessageEnd(event: MessageEventLike): void {
+		const message = event.message;
+		if (!message || message.role !== "assistant") return;
+		// Measurement uses the monotonic clock; only the bridge's freshness
+		// stamp is wall-clock, and the two are never mixed.
+		const timing = this.meter.finish(message.usage?.output, performance.now());
+		if (!timing) return;
+		const sessionId = this.sessionId();
+		if (!sessionId) return;
+		if (!writeTurnBridge({ sessionId, timing, nowMs: Date.now() })) return;
+		if (this.bridgeSessionId && this.bridgeSessionId !== sessionId) removeTurnBridge(this.bridgeSessionId);
+		this.bridgeSessionId = sessionId;
+		this.stats.lastTps = timing.tps;
+		// The new speed only shows up in the next frame; let the throttle coalesce it.
+		this.requestRefresh();
+	}
+
 	get hasFrame(): boolean {
 		return this.frame !== null;
 	}
@@ -253,6 +313,8 @@ export class CclineFooter {
 		this.branchUnsubscribe = null;
 		this.footerData = null;
 		this.requestRenderFn = null;
+		if (this.bridgeSessionId) removeTurnBridge(this.bridgeSessionId);
+		this.bridgeSessionId = null;
 	}
 }
 
@@ -307,6 +369,11 @@ export default function piCcline(pi: ExtensionAPI, deps: PiCclineDeps = {}) {
 	pi.on("model_select", () => requestRefresh());
 	pi.on("thinking_level_select", () => requestRefresh());
 	pi.on("session_info_changed", () => requestRefresh());
+	// Per-request timing is not in the statusline payload, so it is measured
+	// from the stream and written to ccline's bridge file when an answer ends.
+	pi.on("message_start", (event) => footer?.onMessageStart(event as MessageEventLike));
+	pi.on("message_update", (event) => footer?.onMessageUpdate(event as MessageEventLike));
+	pi.on("message_end", (event) => footer?.onMessageEnd(event as MessageEventLike));
 	pi.on("session_shutdown", () => teardown());
 
 	pi.registerCommand("pi-ccline", {
@@ -364,6 +431,7 @@ export default function piCcline(pi: ExtensionAPI, deps: PiCclineDeps = {}) {
 				const { refreshes, lastRefreshAt, lastDurationMs } = footer.stats;
 				lines.push(`refreshes: ${refreshes} · last: ${lastRefreshAt === null ? "never" : `${Math.round((Date.now() - lastRefreshAt) / 1000)}s ago`}`);
 				lines.push(`duration: ${lastDurationMs === null ? "n/a" : `${lastDurationMs}ms`} · frame: ${footer.hasFrame ? "cached" : "none"}`);
+				lines.push(`last answer: ${footer.stats.lastTps === null ? "not measured yet" : `${footer.stats.lastTps.toFixed(1)} tok/s`}`);
 				lines.push(`state: ${footer.error ? `stale — ${footer.error}` : "ok"}`);
 			} else {
 				lines.push("state: footer not installed");

package/extensions/pi-ccline/input.test.ts

@@ -185,9 +185,31 @@ test("collectSnapshot sums only assistant usage on the branch", () => {
 test("collectSnapshot reports no totals for an empty branch", () => {
 	const snapshotValue = collectSnapshot(fakeContext([]), Date.now());
 	assert.equal(snapshotValue.totals, undefined);
+	assert.equal(snapshotValue.cache, undefined);
 	assert.equal(snapshotValue.session?.name, "named");
 });
 
+test("collectSnapshot sums prompt-cache reuse over the branch", () => {
+	const branch: BranchEntryLike[] = [
+		entry({ type: "message", message: { role: "user" } }),
+		entry({ type: "message", message: { role: "assistant", usage: { input: 100, cacheRead: 300, cacheWrite: 100 } } }),
+		entry({ type: "message", message: { role: "assistant", usage: { input: 100, cacheRead: 0, cacheWrite: 0 } } }),
+	];
+
+	// 300 of 600 billed input tokens came from the cache.
+	assert.deepEqual(collectSnapshot(fakeContext(branch), Date.now()).cache, { requests: 2, hitRatio: 0.5 });
+});
+
+test("sends the cache hit share only once it means something", () => {
+	// ccline shows the share from the second request on and falls back to a
+	// misleading "cold" label when hit_ratio is missing, so nothing is sent yet.
+	assert.equal("prompt_cache" in buildCclineInput(snapshot({ cache: { requests: 1, hitRatio: 0 } })), false);
+	assert.deepEqual(buildCclineInput(snapshot({ cache: { requests: 41, hitRatio: 0.94123 } })).prompt_cache, {
+		requests: 41,
+		hit_ratio: 0.9412,
+	});
+});
+
 test("collectSnapshot carries the provider from ctx.model", () => {
 	const ctx = fakeContext([], { model: { id: "m", name: "M", provider: "anthropic", contextWindow: 200_000 } });
 	const snapshotValue = collectSnapshot(ctx, Date.now());

package/extensions/pi-ccline/input.ts

@@ -28,6 +28,14 @@ export interface PiSnapshotTotals {
 	durationMs?: number | undefined;
 }
 
+/** Prompt-cache reuse summed over the visible branch. */
+export interface PiSnapshotCache {
+	/** Assistant messages seen, each one a model request. */
+	requests: number;
+	/** cacheRead / (input + cacheRead + cacheWrite); the share read from cache. */
+	hitRatio: number;
+}
+
 export interface PiSnapshotSession {
 	id?: string | undefined;
 	name?: string | undefined;
@@ -39,6 +47,7 @@ export interface PiSnapshot {
 	thinkingLevel?: string | undefined;
 	contextUsage?: PiSnapshotContextUsage | undefined;
 	totals?: PiSnapshotTotals | undefined;
+	cache?: PiSnapshotCache | undefined;
 	session?: PiSnapshotSession | undefined;
 }
 
@@ -95,6 +104,11 @@ function round1(value: number): number {
 	return Math.round(value * 10) / 10;
 }
 
+/** A ratio ccline renders as a whole percent, so four decimals are plenty. */
+function round4(value: number): number {
+	return Math.round(value * 10_000) / 10_000;
+}
+
 function trimmed(value: unknown): string | undefined {
 	if (typeof value !== "string") return undefined;
 	const text = value.trim();
@@ -120,6 +134,10 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 	let costUsd = 0;
 	let sawAssistantUsage = false;
 	let firstTimestamp: number | undefined;
+	let requests = 0;
+	let inputTokens = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteTokens = 0;
 
 	for (const entry of branch) {
 		const timestamp = entry.timestamp ? Date.parse(entry.timestamp) : Number.NaN;
@@ -131,6 +149,10 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 		if (!entryUsage) continue;
 		sawAssistantUsage = true;
 		costUsd += num(entryUsage.cost?.total);
+		requests += 1;
+		inputTokens += num(entryUsage.input);
+		cacheReadTokens += num(entryUsage.cacheRead);
+		cacheWriteTokens += num(entryUsage.cacheWrite);
 	}
 
 	const totals: PiSnapshotTotals | undefined = sawAssistantUsage
@@ -142,6 +164,9 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 
 	const sessionId = attempt(() => ctx.sessionManager.getSessionId?.());
 	const sessionName = attempt(() => ctx.sessionManager.getSessionName?.());
+	// The denominator is every input token the branch was billed for; without
+	// one there is no ratio to report (a session that never sent a prompt yet).
+	const seenInput = inputTokens + cacheReadTokens + cacheWriteTokens;
 
 	return {
 		cwd: ctx.cwd,
@@ -155,6 +180,7 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 				}
 			: undefined,
 		totals,
+		cache: requests > 0 && seenInput > 0 ? { requests, hitRatio: cacheReadTokens / seenInput } : undefined,
 		session: { id: trimmed(sessionId), name: trimmed(sessionName) },
 	};
 }
@@ -236,6 +262,14 @@ export function buildCclineInput(snapshot: PiSnapshot, options: BuildCclineInput
 	const sessionName = trimmed(snapshot.session?.name);
 	if (sessionName) input.session_name = sessionName;
 
+	// ccline only renders the hit share from the second request on, and falls
+	// back to its "cold" wording whenever `hit_ratio` is missing. So the block
+	// is sent only once it can say something pi actually measured.
+	const cache = snapshot.cache;
+	if (cache && cache.requests >= 2) {
+		input.prompt_cache = { requests: cache.requests, hit_ratio: round4(cache.hitRatio) };
+	}
+
 	// rate_limits has no pi data source; omitting it removes the quota segment.
 	return input;
 }

package/extensions/pi-ccline/turn.test.ts

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, test } from "node:test";
+
+import { bridgeDir, bridgeFileName, removeTurnBridge, TurnMeter, writeTurnBridge } from "./turn.ts";
+
+const createdDirs: string[] = [];
+afterEach(() => {
+	for (const dir of createdDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "pi-ccline-turn-"));
+	createdDirs.push(dir);
+	return dir;
+}
+
+test("measures streaming speed without counting the wait for the first token", () => {
+	const meter = new TurnMeter();
+	meter.start("claude-sonnet-4-5", 1_000);
+	meter.firstDelta(1_800);
+	assert.deepEqual(meter.finish(500, 6_800), {
+		model: "claude-sonnet-4-5",
+		ttftMs: 800,
+		tps: 100,
+		durationMs: 5_800,
+		outputTokens: 500,
+	});
+});
+
+test("keeps only the first delta of an answer", () => {
+	const meter = new TurnMeter();
+	meter.start("m", 0);
+	meter.firstDelta(500);
+	meter.firstDelta(900);
+	meter.firstDelta(1_200);
+	// 200 tokens over the 1500ms after the first token, not over 1000ms.
+	assert.equal(meter.finish(200, 2_000)?.tps, 200 / 1.5);
+});
+
+test("reports nothing without a first delta, output or a measurable span", () => {
+	const neverStreamed = new TurnMeter();
+	neverStreamed.start("m", 0);
+	assert.equal(neverStreamed.finish(100, 5_000), null, "a non-streaming answer has no speed");
+
+	const empty = new TurnMeter();
+	empty.start("m", 0);
+	empty.firstDelta(100);
+	assert.equal(empty.finish(0, 5_000), null, "no output tokens means no rate");
+
+	const tooShort = new TurnMeter();
+	tooShort.start("m", 0);
+	tooShort.firstDelta(100);
+	assert.equal(tooShort.finish(5, 150), null, "a sub-100ms span is jitter, not speed");
+
+	const unmeasured = new TurnMeter();
+	unmeasured.firstDelta(100);
+	assert.equal(unmeasured.finish(100, 5_000), null, "finish before start is ignored");
+});
+
+test("a finished sample does not leak into the next request", () => {
+	const meter = new TurnMeter();
+	meter.start("first", 0);
+	meter.firstDelta(100);
+	meter.finish(10, 1_100);
+
+	meter.start("second", 2_000);
+	meter.firstDelta(2_400);
+	const second = meter.finish(80, 3_400);
+	assert.equal(second?.model, "second");
+	assert.equal(second?.ttftMs, 400);
+	assert.equal(second?.tps, 80);
+});
+
+test("writes the bridge shape ccline reads", () => {
+	const dir = tempDir();
+	assert.equal(
+		writeTurnBridge({
+			sessionId: "sess-1",
+			timing: { model: "m", ttftMs: 820, tps: 74.234, durationMs: 41_000, outputTokens: 1_400 },
+			nowMs: 1_790_808_780_000,
+			dir,
+		}),
+		true,
+	);
+	assert.deepEqual(JSON.parse(readFileSync(join(dir, "sess-1.json"), "utf8")), {
+		v: 1,
+		session: "sess-1",
+		updated_at: 1_790_808_780_000,
+		turn: { model: "m", ttft_ms: 820, tps: 74.234, duration_ms: 41_000, output_tokens: 1_400 },
+	});
+});
+
+test("omits timing fields it did not measure", () => {
+	const dir = tempDir();
+	writeTurnBridge({ sessionId: "s2", timing: { tps: 12, durationMs: 1_000, outputTokens: 12 }, nowMs: 1, dir });
+	const bridge = JSON.parse(readFileSync(join(dir, "s2.json"), "utf8"));
+	assert.deepEqual(Object.keys(bridge.turn).sort(), ["duration_ms", "output_tokens", "tps"]);
+});
+
+test("refuses session ids that are not plain file names", () => {
+	const dir = tempDir();
+	assert.equal(bridgeFileName("../escape"), null);
+	assert.equal(bridgeFileName("a/b"), null);
+	assert.equal(bridgeFileName(""), null);
+	assert.equal(writeTurnBridge({ sessionId: "../escape", timing: { tps: 1, durationMs: 1, outputTokens: 1 }, nowMs: 1, dir }), false);
+	assert.deepEqual(readdirSync(dir), [], "nothing escaped or landed in the bridge dir");
+});
+
+test("a failed write leaves no temp file behind", () => {
+	const dir = tempDir();
+	// A directory in the target's place makes the rename fail after the temp
+	// file was already written.
+	mkdirSync(join(dir, "blocked.json"));
+	assert.equal(writeTurnBridge({ sessionId: "blocked", timing: { tps: 1, durationMs: 1, outputTokens: 1 }, nowMs: 1, dir }), false);
+	assert.deepEqual(readdirSync(dir), ["blocked.json"]);
+});
+
+test("removes a session bridge and tolerates a missing one", () => {
+	const dir = tempDir();
+	writeTurnBridge({ sessionId: "s3", timing: { tps: 1, durationMs: 1, outputTokens: 1 }, nowMs: 1, dir });
+	assert.equal(existsSync(join(dir, "s3.json")), true);
+	removeTurnBridge("s3", dir);
+	assert.equal(existsSync(join(dir, "s3.json")), false);
+	removeTurnBridge("s3", dir);
+	removeTurnBridge("../escape", dir);
+});
+
+test("follows ccline's own data directory resolution", () => {
+	assert.equal(bridgeDir({ CCLINE_HOME: "/tmp/ccline-home" }, "/home/u"), "/tmp/ccline-home/bridge");
+	assert.equal(bridgeDir({ CCLINE_HOME: "  " }, "/home/u"), "/home/u/.claude/ccline/bridge");
+	assert.equal(bridgeDir({}, "/home/u"), "/home/u/.claude/ccline/bridge");
+});

package/extensions/pi-ccline/turn.ts

@@ -0,0 +1,148 @@
+// Measures the main loop's last model request and hands it to ccline through
+// the bridge file its companion mod normally writes.
+//
+// ccline's `timing.ttft` / `timing.tps` metrics read `bridge/<session>.json`
+// under ccline's data dir, not the statusline JSON: per-request timing is the
+// one thing the Claude Code payload leaves out. pi has the same gap, so the
+// numbers are measured here from streaming events and written in the same
+// documented v1 shape (the file is rewritten on every finished request, which
+// also keeps it inside ccline's 6h freshness window).
+
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** One finished model request, in the units ccline's bridge expects. */
+export interface TurnTiming {
+	model?: string | undefined;
+	/** Stream start to the first text, thinking or tool-call delta. */
+	ttftMs?: number | undefined;
+	/** Output tokens per second while the answer streamed (ttft excluded). */
+	tps: number;
+	durationMs: number;
+	outputTokens: number;
+}
+
+/** Below this the sample says more about jitter than about speed. */
+const MIN_STREAM_MS = 100;
+
+/**
+ * ccline resolves its data dir from `CCLINE_HOME`, falling back to
+ * `~/.claude/ccline`; the bridge lives in a `bridge` subdirectory of either.
+ */
+export function bridgeDir(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+	const override = env.CCLINE_HOME?.trim();
+	return join(override ? override : join(home, ".claude", "ccline"), "bridge");
+}
+
+/**
+ * ccline's own name check rejects anything that could climb out of the bridge
+ * directory; pi session ids are UUIDs, so a strict allowlist costs nothing.
+ */
+export function bridgeFileName(sessionId: string): string | null {
+	return /^[A-Za-z0-9._-]+$/.test(sessionId) ? `${sessionId}.json` : null;
+}
+
+export interface TurnBridgeOptions {
+	sessionId: string;
+	timing: TurnTiming;
+	/** Unix epoch milliseconds of the write; ccline drops bridges older than 6h. */
+	nowMs: number;
+	dir?: string;
+}
+
+/** Write the bridge for one session. Returns false instead of throwing. */
+export function writeTurnBridge(options: TurnBridgeOptions): boolean {
+	const name = bridgeFileName(options.sessionId);
+	if (!name) return false;
+	const dir = options.dir ?? bridgeDir();
+	const path = join(dir, name);
+	const { model, ttftMs, tps, durationMs, outputTokens } = options.timing;
+	const turn: Record<string, unknown> = {
+		tps,
+		duration_ms: Math.round(durationMs),
+		output_tokens: Math.round(outputTokens),
+	};
+	if (model) turn.model = model;
+	if (ttftMs !== undefined) turn.ttft_ms = Math.round(ttftMs);
+	const payload = {
+		v: 1,
+		session: options.sessionId,
+		updated_at: Math.round(options.nowMs),
+		turn,
+	};
+
+	try {
+		mkdirSync(dir, { recursive: true });
+		// ccline tolerates a half-written bridge by retrying once, but an atomic
+		// rename means it never has to.
+		const temp = `${path}.${process.pid}.tmp`;
+		writeFileSync(temp, `${JSON.stringify(payload)}\n`, "utf8");
+		renameSync(temp, path);
+		return true;
+	} catch {
+		// A failed write must not leave a temp file behind next to the bridges
+		// ccline scans (and must never throw into the session).
+		try {
+			rmSync(`${path}.${process.pid}.tmp`, { force: true });
+		} catch {
+			// nothing left to do; ccline prunes the directory itself
+		}
+		return false;
+	}
+}
+
+/** Drop a session's bridge, so a closed session leaves no stale speed behind. */
+export function removeTurnBridge(sessionId: string, dir: string = bridgeDir()): void {
+	const name = bridgeFileName(sessionId);
+	if (!name) return;
+	try {
+		rmSync(join(dir, name), { force: true });
+	} catch {
+		// A bridge that cannot be removed is pruned by ccline after a week.
+	}
+}
+
+/**
+ * Times one request from three streaming events: `message_start` (the answer
+ * began), the first `message_update` (first token) and `message_end`.
+ * A request without a first delta (a non-streaming provider) yields no speed.
+ */
+export class TurnMeter {
+	private startedAt: number | null = null;
+	private firstDeltaAt: number | null = null;
+	private model: string | undefined;
+
+	start(model: string | undefined, nowMs: number): void {
+		this.startedAt = nowMs;
+		this.firstDeltaAt = null;
+		this.model = model;
+	}
+
+	firstDelta(nowMs: number): void {
+		if (this.startedAt === null || this.firstDeltaAt !== null) return;
+		this.firstDeltaAt = nowMs;
+	}
+
+	/** The answer finished; null when the sample cannot describe a speed. */
+	finish(outputTokens: unknown, nowMs: number): TurnTiming | null {
+		const startedAt = this.startedAt;
+		const firstDeltaAt = this.firstDeltaAt;
+		const model = this.model;
+		this.startedAt = null;
+		this.firstDeltaAt = null;
+		this.model = undefined;
+		if (startedAt === null || firstDeltaAt === null) return null;
+
+		const output = typeof outputTokens === "number" && Number.isFinite(outputTokens) ? outputTokens : 0;
+		const streamMs = nowMs - firstDeltaAt;
+		if (output <= 0 || streamMs < MIN_STREAM_MS) return null;
+
+		const tps = output / (streamMs / 1000);
+		if (!Number.isFinite(tps) || tps <= 0) return null;
+
+		const ttftMs = Math.max(0, firstDeltaAt - startedAt);
+		return { model, tps, durationMs: Math.max(0, nowMs - startedAt), outputTokens: output, ttftMs };
+	}
+}
+

package/fixtures/basic.json

@@ -18,9 +18,13 @@
     "used_percentage": 15.4
   },
   "cost": {
-    "total_cost_usd": 1.2345,
-    "total_duration_ms": 1830000
+    "total_cost_usd": 0.54,
+    "total_duration_ms": 1800000
   },
-  "session_id": "4f8f2c1a-0000-4000-8000-000000000000",
-  "session_name": "pi-ccline demo"
-}
+  "session_id": "sess-demo",
+  "session_name": "pi-ccline demo",
+  "prompt_cache": {
+    "requests": 2,
+    "hit_ratio": 0.9863
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@caph42/pi-ccline",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "Pi extension that renders the footer by delegating to the CCometixLine (ccline) statusline binary",
 	"keywords": [
 		"pi-package",