@narumitw/pi-cache-hit-monitor 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 narumiruna
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,110 @@
1
+ # 📈 pi-cache-hit-monitor — Inspect Prompt Cache Reuse in Pi
2
+
3
+ [![npm](https://img.shields.io/npm/v/@narumitw/pi-cache-hit-monitor)](https://www.npmjs.com/package/@narumitw/pi-cache-hit-monitor) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
+
5
+ Show live prompt-cache reuse, token, and estimated cost diagnostics above Pi's editor without changing model-visible context.
6
+ The widget starts hidden in every session.
7
+
8
+ ## ✨ Features
9
+
10
+ - Previews provider-reported cache usage while an assistant response streams.
11
+ - Compares each request with the previous request in the current cache prefix epoch.
12
+ - Reports weighted active-branch totals, including compaction and branch-summary usage.
13
+ - Restores metrics after session start, compaction, and tree navigation.
14
+ - Keeps provider and model labels terminal-safe and every widget line within the available width.
15
+ - Adds no tools, messages, system instructions, or provider payload changes.
16
+
17
+ ## 📦 Install
18
+
19
+ Install the extension permanently:
20
+
21
+ ```bash
22
+ pi install npm:@narumitw/pi-cache-hit-monitor
23
+ ```
24
+
25
+ Try it without installing permanently:
26
+
27
+ ```bash
28
+ pi -e npm:@narumitw/pi-cache-hit-monitor
29
+ ```
30
+
31
+ Try this package locally from the repository root:
32
+
33
+ ```bash
34
+ pi -e ./packages/pi-cache-hit-monitor
35
+ ```
36
+
37
+ Pi extensions run with the Pi process's user permissions, so install only trusted packages.
38
+ This extension reads usage and model metadata already present in the active Pi session and performs no network or file operations of its own.
39
+
40
+ ## 🚀 Quick start
41
+
42
+ Run `/cache-hit-monitor` in TUI or RPC mode to show the widget.
43
+ Run the same command again to hide it.
44
+ The widget updates when the provider reports usage and is removed when the session shuts down.
45
+
46
+ ## 💬 Commands
47
+
48
+ `/cache-hit-monitor` shows or hides live prompt-cache diagnostics.
49
+ It accepts no arguments, supports TUI and RPC modes, and rejects print and JSON modes.
50
+
51
+ ## 📊 Displayed metrics
52
+
53
+ - `hit` is `cacheRead / (input + cacheRead + cacheWrite)` for the latest provider response.
54
+ - `Δ` is the signed percentage-point change from the previous comparable request.
55
+ - `loss` is only the downward part of that hit-rate change.
56
+ - `uncached` is the latest `input` share and token count.
57
+ - `eligible` is the smaller prompt-token count between the previous and current request.
58
+ - `re-billed` estimates reusable-prefix tokens not covered by the current `cacheRead` count.
59
+ - `cache saved` estimates the price difference between uncached input and cache-read pricing.
60
+ - `miss premium` estimates the extra price of re-billed tokens compared with cache-read pricing.
61
+ - `start gap` is the elapsed time between the previous and current provider request start timestamps.
62
+ - `Session` reports weighted active-branch totals and does not average request percentages.
63
+ - `Trend` shows the latest eight request hit rates from oldest to newest.
64
+
65
+ Session totals include provider usage reported by compaction and branch-summary calls.
66
+ When summary usage omits cache accounting, the request count, tokens, and prompt cost remain included while hit rate and savings stay unavailable.
67
+
68
+ ## 🔄 Runtime behavior
69
+
70
+ While visible, the widget updates from `message_update` as soon as the provider reports usage and finalizes on `message_end`.
71
+ Cache comparisons reset across compaction and branch-summary boundaries because those events create a new cache prefix epoch, while session totals continue to include usage records visible on the active branch.
72
+ The extension rebuilds state after session start, compaction, and tree navigation, clears its widget during session replacement and shutdown, and ignores events from stale sessions.
73
+
74
+ ## 🔒 Security and privacy
75
+
76
+ The extension does not make network requests, read files, write files, or persist separate state.
77
+ It reads assistant usage, provider and model IDs, model pricing, and active-branch summary usage from Pi's in-memory session APIs.
78
+ No collected metric is sent to the model by this extension.
79
+
80
+ ## 🚧 Limitations
81
+
82
+ - Values depend on provider-reported Pi usage fields and can remain unavailable when a provider omits cache accounting.
83
+ - The monitor does not interpret normalized all-zero cache fields as a complete miss until that provider reports cache-read or cache-write activity.
84
+ - `re-billed` compares token counts and cannot prove which exact serialized prefix bytes the provider cached.
85
+ - Cost values use reported usage costs with Pi's effective model tiers and cache-write retention pricing as component fallbacks; subscription billing can differ.
86
+ - Cache writes are included in the hit-rate denominator but are not labeled as uncached input.
87
+
88
+ ## 🗂️ Package layout
89
+
90
+ ```text
91
+ packages/pi-cache-hit-monitor/
92
+ ├── src/
93
+ │ ├── index.ts # Thin Pi entrypoint
94
+ │ ├── cache-hit-monitor.ts # Command, lifecycle, and widget rendering
95
+ │ └── metrics.ts # Cache calculations and report formatting
96
+ ├── test/ # Metrics, modes, lifecycle, and rendering coverage
97
+ ├── package.json
98
+ ├── README.md
99
+ └── LICENSE
100
+ ```
101
+
102
+ The package publishes its TypeScript source entrypoint for Pi's Jiti runtime and needs no build step.
103
+
104
+ ## 🔎 Keywords
105
+
106
+ Pi extension, Pi coding agent, prompt cache, cache hit rate, token reuse, cache cost, observability, TypeScript widget.
107
+
108
+ ## 📄 License
109
+
110
+ MIT. See [`LICENSE`](./LICENSE).
package/package.json ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "@narumitw/pi-cache-hit-monitor",
3
+ "version": "0.0.0",
4
+ "description": "Pi extension that shows live prompt-cache reuse and cost diagnostics above the editor.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "private": false,
8
+ "keywords": [
9
+ "pi-package",
10
+ "pi-extension",
11
+ "pi",
12
+ "prompt-cache",
13
+ "cache-hit-rate",
14
+ "observability",
15
+ "widget",
16
+ "tui"
17
+ ],
18
+ "files": [
19
+ "src",
20
+ "README.md",
21
+ "LICENSE"
22
+ ],
23
+ "pi": {
24
+ "extensions": [
25
+ "./src/index.ts"
26
+ ]
27
+ },
28
+ "scripts": {
29
+ "check": "biome check . && npm run typecheck",
30
+ "format": "biome check --write .",
31
+ "typecheck": "tsc --noEmit"
32
+ },
33
+ "peerDependencies": {
34
+ "@earendil-works/pi-ai": "*",
35
+ "@earendil-works/pi-coding-agent": "*",
36
+ "@earendil-works/pi-tui": "*"
37
+ },
38
+ "devDependencies": {
39
+ "@earendil-works/pi-ai": "0.85.0",
40
+ "@earendil-works/pi-coding-agent": "0.85.0",
41
+ "@earendil-works/pi-tui": "0.85.0",
42
+ "@types/node": "26.4.1",
43
+ "typescript": "7.0.2"
44
+ },
45
+ "repository": {
46
+ "type": "git",
47
+ "url": "https://github.com/narumiruna/pi-extensions",
48
+ "directory": "packages/pi-cache-hit-monitor"
49
+ }
50
+ }
@@ -0,0 +1,209 @@
1
+ import type { AssistantMessage } from "@earendil-works/pi-ai";
2
+ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
3
+ import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
4
+ import {
5
+ type CacheMonitorView,
6
+ type CacheSample,
7
+ type CacheUsageRecord,
8
+ cacheSamplesEqual,
9
+ collectCacheSamples,
10
+ createCacheMonitorView,
11
+ createCacheSample,
12
+ formatMonitorLines,
13
+ type MonitorLine,
14
+ } from "./metrics.js";
15
+
16
+ export const COMMAND_NAME = "cache-hit-monitor";
17
+ export const WIDGET_KEY = "cache-hit-monitor";
18
+
19
+ export default function cacheHitMonitor(pi: ExtensionAPI): void {
20
+ let activeSession: ExtensionContext["sessionManager"] | undefined;
21
+ let finalizedSamples: CacheSample[] = [];
22
+ let summaryRecords: CacheUsageRecord[] = [];
23
+ const cacheReportingProviders = new Set<string>();
24
+ let currentEpoch = 0;
25
+ let streamingSample: CacheSample | undefined;
26
+ let publishedSignature: string | undefined;
27
+ let visible = false;
28
+
29
+ const ownsSession = (ctx: ExtensionContext): boolean => ctx.sessionManager === activeSession;
30
+
31
+ const resolveCostModel = (ctx: ExtensionContext, provider: string, model: string) =>
32
+ ctx.modelRegistry.find(provider, model);
33
+
34
+ const restore = (ctx: ExtensionContext): void => {
35
+ const restored = collectCacheSamples(ctx.sessionManager.getBranch(), (provider, model) =>
36
+ resolveCostModel(ctx, provider, model),
37
+ );
38
+ finalizedSamples = restored.samples;
39
+ summaryRecords = restored.summaryRecords;
40
+ cacheReportingProviders.clear();
41
+ for (const sample of finalizedSamples) {
42
+ if (sample.cacheRead > 0 || sample.cacheWrite > 0) {
43
+ cacheReportingProviders.add(sample.provider);
44
+ }
45
+ }
46
+ currentEpoch = restored.currentEpoch;
47
+ streamingSample = undefined;
48
+ };
49
+
50
+ const sampleMessage = (message: AssistantMessage, ctx: ExtensionContext): CacheSample | null =>
51
+ createCacheSample(
52
+ message,
53
+ currentEpoch,
54
+ resolveCostModel(ctx, message.provider, message.model),
55
+ cacheReportingProviders.has(message.provider),
56
+ );
57
+
58
+ const clearWidget = (ctx: ExtensionContext): void => {
59
+ if (ctx.hasUI && ownsSession(ctx)) ctx.ui.setWidget(WIDGET_KEY, undefined);
60
+ publishedSignature = undefined;
61
+ };
62
+
63
+ const publish = (ctx: ExtensionContext): void => {
64
+ if (!visible || !ctx.hasUI || !ownsSession(ctx)) return;
65
+ const view = createCacheMonitorView(finalizedSamples, streamingSample, {
66
+ activeEpoch: currentEpoch,
67
+ summaryRecords,
68
+ });
69
+ const lines = formatMonitorLines(view);
70
+ const signature = JSON.stringify(lines);
71
+ if (signature === publishedSignature) return;
72
+ if (ctx.mode === "tui") {
73
+ ctx.ui.setWidget(
74
+ WIDGET_KEY,
75
+ (_tui, theme) => ({
76
+ render: (width: number) => renderCacheMonitor(view, theme, width),
77
+ invalidate: () => {},
78
+ }),
79
+ { placement: "aboveEditor" },
80
+ );
81
+ } else {
82
+ ctx.ui.setWidget(
83
+ WIDGET_KEY,
84
+ lines.map(({ text }) => text),
85
+ { placement: "aboveEditor" },
86
+ );
87
+ }
88
+ publishedSignature = signature;
89
+ };
90
+
91
+ pi.registerCommand(COMMAND_NAME, {
92
+ description: "Show or hide live prompt-cache diagnostics",
93
+ handler: async (args, ctx) => {
94
+ if (args.trim()) {
95
+ throw new Error(`Usage: /${COMMAND_NAME}`);
96
+ }
97
+ if (!ctx.hasUI) {
98
+ throw new Error(`/${COMMAND_NAME} requires TUI or RPC mode.`);
99
+ }
100
+ if (!ownsSession(ctx)) {
101
+ throw new Error(`/${COMMAND_NAME} is unavailable for a stale session.`);
102
+ }
103
+
104
+ visible = !visible;
105
+ if (visible) publish(ctx);
106
+ else clearWidget(ctx);
107
+ ctx.ui.notify(`Cache hit monitor ${visible ? "shown" : "hidden"}.`, "info");
108
+ },
109
+ });
110
+
111
+ pi.on("session_start", (_event, ctx) => {
112
+ if (visible && activeSession !== ctx.sessionManager && ctx.hasUI) {
113
+ ctx.ui.setWidget(WIDGET_KEY, undefined);
114
+ }
115
+ activeSession = ctx.sessionManager;
116
+ visible = false;
117
+ publishedSignature = undefined;
118
+ restore(ctx);
119
+ });
120
+
121
+ pi.on("message_start", (event, ctx) => {
122
+ if (!ownsSession(ctx) || event.message.role !== "assistant") return;
123
+ streamingSample = undefined;
124
+ publish(ctx);
125
+ });
126
+
127
+ pi.on("message_update", (event, ctx) => {
128
+ if (!ownsSession(ctx) || event.message.role !== "assistant") return;
129
+ const sample = sampleMessage(event.message, ctx);
130
+ if (!sample || (streamingSample && cacheSamplesEqual(streamingSample, sample))) return;
131
+ if (sample.cacheRead > 0 || sample.cacheWrite > 0) {
132
+ cacheReportingProviders.add(sample.provider);
133
+ }
134
+ streamingSample = sample;
135
+ publish(ctx);
136
+ });
137
+
138
+ pi.on("message_end", (event, ctx) => {
139
+ if (!ownsSession(ctx) || event.message.role !== "assistant") return;
140
+ const sample = sampleMessage(event.message, ctx);
141
+ streamingSample = undefined;
142
+ if (sample) {
143
+ if (sample.cacheRead > 0 || sample.cacheWrite > 0) {
144
+ cacheReportingProviders.add(sample.provider);
145
+ }
146
+ finalizedSamples.push(sample);
147
+ }
148
+ publish(ctx);
149
+ });
150
+
151
+ pi.on("agent_end", (_event, ctx) => {
152
+ if (!ownsSession(ctx) || !streamingSample) return;
153
+ streamingSample = undefined;
154
+ publish(ctx);
155
+ });
156
+
157
+ pi.on("session_compact", (_event, ctx) => {
158
+ if (!ownsSession(ctx)) return;
159
+ restore(ctx);
160
+ publish(ctx);
161
+ });
162
+
163
+ pi.on("session_tree", (_event, ctx) => {
164
+ if (!ownsSession(ctx)) return;
165
+ restore(ctx);
166
+ publish(ctx);
167
+ });
168
+
169
+ pi.on("session_shutdown", (_event, ctx) => {
170
+ if (!ownsSession(ctx)) return;
171
+ clearWidget(ctx);
172
+ activeSession = undefined;
173
+ finalizedSamples = [];
174
+ summaryRecords = [];
175
+ cacheReportingProviders.clear();
176
+ streamingSample = undefined;
177
+ visible = false;
178
+ });
179
+ }
180
+
181
+ export function renderCacheMonitor(view: CacheMonitorView, theme: Theme, width: number): string[] {
182
+ const renderWidth = Math.max(0, width);
183
+ if (renderWidth === 0) return ["", ...formatMonitorLines(view).map(() => "")];
184
+ const divider = theme.fg("borderMuted", "─".repeat(renderWidth));
185
+ const rendered = formatMonitorLines(view).flatMap((line) => {
186
+ const styled = styleLine(line, theme);
187
+ return wrapTextWithAnsi(styled, renderWidth);
188
+ });
189
+ return [divider, ...rendered].map((line) =>
190
+ visibleWidth(line) <= renderWidth ? line : truncateToWidth(line, renderWidth, ""),
191
+ );
192
+ }
193
+
194
+ function styleLine(line: MonitorLine, theme: Theme): string {
195
+ switch (line.role) {
196
+ case "title":
197
+ return theme.fg("accent", theme.bold(line.text));
198
+ case "good":
199
+ return theme.fg("success", line.text);
200
+ case "warning":
201
+ return theme.fg("warning", line.text);
202
+ case "bad":
203
+ return theme.fg("error", line.text);
204
+ case "muted":
205
+ return theme.fg("muted", line.text);
206
+ case "dim":
207
+ return theme.fg("dim", line.text);
208
+ }
209
+ }
package/src/index.ts ADDED
@@ -0,0 +1 @@
1
+ export { COMMAND_NAME, default, renderCacheMonitor, WIDGET_KEY } from "./cache-hit-monitor.js";
package/src/metrics.ts ADDED
@@ -0,0 +1,585 @@
1
+ import { type Api, type AssistantMessage, calculateCost, type Model, type Usage } from "@earendil-works/pi-ai";
2
+ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
3
+ import { stripTerminalSequences } from "@earendil-works/pi-tui";
4
+
5
+ const TREND_SAMPLE_COUNT = 8;
6
+ const MAX_LABEL_LENGTH = 60;
7
+
8
+ export interface CacheUsageRecord {
9
+ input: number;
10
+ cacheRead: number;
11
+ cacheWrite: number;
12
+ promptTokens: number;
13
+ hitRatePercent: number | null;
14
+ uncachedRatePercent: number | null;
15
+ promptCost: number | null;
16
+ estimatedSavings: number | null;
17
+ }
18
+
19
+ export interface CacheSample extends CacheUsageRecord {
20
+ hitRatePercent: number;
21
+ uncachedRatePercent: number;
22
+ epoch: number;
23
+ timestamp: number;
24
+ provider: string;
25
+ model: string;
26
+ inputUnitCost: number | null;
27
+ cacheReadUnitCost: number | null;
28
+ paidPromptUnitCost: number | null;
29
+ }
30
+
31
+ export interface CacheComparison {
32
+ previousRequestNumber: number;
33
+ hitRateDeltaPercent: number;
34
+ hitRateLossPercent: number;
35
+ promptTokenDelta: number;
36
+ cacheReadDelta: number;
37
+ reusablePrefixTokens: number;
38
+ rebilledTokens: number;
39
+ rebilledPercent: number | null;
40
+ estimatedMissPremium: number | null;
41
+ modelChanged: boolean;
42
+ requestStartGapMs: number;
43
+ }
44
+
45
+ export interface CacheAggregate {
46
+ requestCount: number;
47
+ input: number;
48
+ cacheRead: number;
49
+ cacheWrite: number;
50
+ promptTokens: number;
51
+ hitRatePercent: number | null;
52
+ promptCost: number | null;
53
+ estimatedSavings: number | null;
54
+ rebilledTokens: number;
55
+ estimatedMissPremium: number | null;
56
+ bestHitRatePercent: number | null;
57
+ worstHitRatePercent: number | null;
58
+ }
59
+
60
+ export interface CacheMonitorView {
61
+ streaming: boolean;
62
+ requestNumber: number;
63
+ latest: CacheSample | null;
64
+ comparison: CacheComparison | null;
65
+ session: CacheAggregate;
66
+ trend: number[];
67
+ }
68
+
69
+ export interface MonitorLine {
70
+ role: "title" | "good" | "warning" | "bad" | "muted" | "dim";
71
+ text: string;
72
+ }
73
+
74
+ export interface CollectedCacheSamples {
75
+ samples: CacheSample[];
76
+ summaryRecords: CacheUsageRecord[];
77
+ currentEpoch: number;
78
+ }
79
+
80
+ export interface CacheMonitorViewOptions {
81
+ activeEpoch?: number;
82
+ summaryRecords?: readonly CacheUsageRecord[];
83
+ }
84
+
85
+ type CostModelResolver = (provider: string, model: string) => Model<Api> | undefined;
86
+
87
+ export function collectCacheSamples(
88
+ entries: readonly SessionEntry[],
89
+ resolveCostModel: CostModelResolver = () => undefined,
90
+ ): CollectedCacheSamples {
91
+ const samples: CacheSample[] = [];
92
+ const summaryRecords: CacheUsageRecord[] = [];
93
+ const cacheReportingProviders = new Set<string>();
94
+ let currentEpoch = 0;
95
+ for (const entry of entries) {
96
+ if (entry.type === "compaction" || entry.type === "branch_summary") {
97
+ const summaryCalculation = entry.usage
98
+ ? calculateCacheUsage(entry.usage, { retainUnknownCacheAccounting: true })
99
+ : null;
100
+ if (summaryCalculation) summaryRecords.push(summaryCalculation.record);
101
+ currentEpoch += 1;
102
+ continue;
103
+ }
104
+ if (entry.type !== "message" || entry.message.role !== "assistant") continue;
105
+ const sample = createCacheSample(
106
+ entry.message,
107
+ currentEpoch,
108
+ resolveCostModel(entry.message.provider, entry.message.model),
109
+ cacheReportingProviders.has(entry.message.provider),
110
+ );
111
+ if (sample) {
112
+ if (sample.cacheRead > 0 || sample.cacheWrite > 0) {
113
+ cacheReportingProviders.add(sample.provider);
114
+ }
115
+ samples.push(sample);
116
+ }
117
+ }
118
+ return { samples, summaryRecords, currentEpoch };
119
+ }
120
+
121
+ export function createCacheSample(
122
+ message: AssistantMessage,
123
+ epoch: number,
124
+ costModel?: Model<Api>,
125
+ cacheAccountingKnown = false,
126
+ ): CacheSample | null {
127
+ const calculation = calculateCacheUsage(message.usage, {
128
+ costModel,
129
+ cacheAccountingKnown,
130
+ });
131
+ if (!calculation || calculation.record.hitRatePercent === null || calculation.record.uncachedRatePercent === null) {
132
+ return null;
133
+ }
134
+
135
+ return {
136
+ ...calculation.record,
137
+ hitRatePercent: calculation.record.hitRatePercent,
138
+ uncachedRatePercent: calculation.record.uncachedRatePercent,
139
+ epoch,
140
+ timestamp: finiteNumber(message.timestamp),
141
+ provider: message.provider,
142
+ model: message.model,
143
+ inputUnitCost: calculation.inputUnitCost,
144
+ cacheReadUnitCost: calculation.cacheReadUnitCost,
145
+ paidPromptUnitCost: calculation.paidPromptUnitCost,
146
+ };
147
+ }
148
+
149
+ export function cacheSamplesEqual(left: CacheSample, right: CacheSample): boolean {
150
+ return (
151
+ left.epoch === right.epoch &&
152
+ left.timestamp === right.timestamp &&
153
+ left.provider === right.provider &&
154
+ left.model === right.model &&
155
+ left.input === right.input &&
156
+ left.cacheRead === right.cacheRead &&
157
+ left.cacheWrite === right.cacheWrite &&
158
+ left.promptCost === right.promptCost &&
159
+ left.estimatedSavings === right.estimatedSavings &&
160
+ left.inputUnitCost === right.inputUnitCost &&
161
+ left.cacheReadUnitCost === right.cacheReadUnitCost &&
162
+ left.paidPromptUnitCost === right.paidPromptUnitCost
163
+ );
164
+ }
165
+
166
+ export function createCacheMonitorView(
167
+ finalizedSamples: readonly CacheSample[],
168
+ streamingSample?: CacheSample,
169
+ options: CacheMonitorViewOptions = {},
170
+ ): CacheMonitorView {
171
+ const samples = streamingSample ? [...finalizedSamples, streamingSample] : [...finalizedSamples];
172
+ const latest = samples.at(-1) ?? null;
173
+ const activeEpoch = options.activeEpoch ?? latest?.epoch;
174
+ const previousIndex =
175
+ latest && latest.epoch === activeEpoch
176
+ ? findPreviousComparableIndex(samples, samples.length - 1, latest.epoch)
177
+ : -1;
178
+ const previous = previousIndex >= 0 ? samples[previousIndex] : undefined;
179
+
180
+ return {
181
+ streaming: streamingSample !== undefined,
182
+ requestNumber: samples.length,
183
+ latest,
184
+ comparison: latest && previous ? compareCacheSamples(previous, latest, previousIndex + 1) : null,
185
+ session: aggregateCacheSamples(samples, options.summaryRecords),
186
+ trend: samples.slice(-TREND_SAMPLE_COUNT).map((sample) => sample.hitRatePercent),
187
+ };
188
+ }
189
+
190
+ export function compareCacheSamples(
191
+ previous: CacheSample,
192
+ current: CacheSample,
193
+ previousRequestNumber: number,
194
+ ): CacheComparison | null {
195
+ if (previous.epoch !== current.epoch) return null;
196
+ const reusablePrefixTokens = Math.min(previous.promptTokens, current.promptTokens);
197
+ const reusedTokens = Math.min(current.cacheRead, reusablePrefixTokens);
198
+ const rebilledTokens = Math.max(0, reusablePrefixTokens - reusedTokens);
199
+ const hitRateDeltaPercent = current.hitRatePercent - previous.hitRatePercent;
200
+ const unitPremium =
201
+ current.paidPromptUnitCost !== null && current.cacheReadUnitCost !== null
202
+ ? Math.max(0, current.paidPromptUnitCost - current.cacheReadUnitCost)
203
+ : null;
204
+
205
+ return {
206
+ previousRequestNumber,
207
+ hitRateDeltaPercent,
208
+ hitRateLossPercent: Math.max(0, -hitRateDeltaPercent),
209
+ promptTokenDelta: current.promptTokens - previous.promptTokens,
210
+ cacheReadDelta: current.cacheRead - previous.cacheRead,
211
+ reusablePrefixTokens,
212
+ rebilledTokens,
213
+ rebilledPercent: reusablePrefixTokens > 0 ? (rebilledTokens / reusablePrefixTokens) * 100 : null,
214
+ estimatedMissPremium: unitPremium === null ? null : rebilledTokens * unitPremium,
215
+ modelChanged: previous.provider !== current.provider || previous.model !== current.model,
216
+ requestStartGapMs: Math.max(0, current.timestamp - previous.timestamp),
217
+ };
218
+ }
219
+
220
+ export function aggregateCacheSamples(
221
+ samples: readonly CacheSample[],
222
+ additionalRecords: readonly CacheUsageRecord[] = [],
223
+ ): CacheAggregate {
224
+ let input = 0;
225
+ let cacheRead = 0;
226
+ let cacheWrite = 0;
227
+ let promptCost = 0;
228
+ let promptCostKnown = true;
229
+ let estimatedSavings = 0;
230
+ let savingsKnown = true;
231
+ let rebilledTokens = 0;
232
+ let estimatedMissPremium = 0;
233
+ let hasRebilledTokens = false;
234
+ let missPremiumComplete = true;
235
+ let cacheAccountingComplete = true;
236
+ let bestHitRatePercent: number | null = null;
237
+ let worstHitRatePercent: number | null = null;
238
+
239
+ const addUsage = (record: CacheUsageRecord): void => {
240
+ input += record.input;
241
+ cacheRead += record.cacheRead;
242
+ cacheWrite += record.cacheWrite;
243
+ if (record.promptCost === null) promptCostKnown = false;
244
+ else promptCost += record.promptCost;
245
+ if (record.estimatedSavings === null) savingsKnown = false;
246
+ else estimatedSavings += record.estimatedSavings;
247
+ if (record.hitRatePercent === null) {
248
+ cacheAccountingComplete = false;
249
+ } else {
250
+ bestHitRatePercent = Math.max(bestHitRatePercent ?? record.hitRatePercent, record.hitRatePercent);
251
+ worstHitRatePercent = Math.min(worstHitRatePercent ?? record.hitRatePercent, record.hitRatePercent);
252
+ }
253
+ };
254
+
255
+ for (const sample of samples) addUsage(sample);
256
+ for (const record of additionalRecords) addUsage(record);
257
+
258
+ for (let index = 0; index < samples.length; index += 1) {
259
+ const sample = samples[index];
260
+ if (!sample) continue;
261
+ const previousIndex = findPreviousComparableIndex(samples, index, sample.epoch);
262
+ if (previousIndex < 0) continue;
263
+ const previous = samples[previousIndex];
264
+ if (!previous) continue;
265
+ const comparison = compareCacheSamples(previous, sample, previousIndex + 1);
266
+ if (!comparison) continue;
267
+ rebilledTokens += comparison.rebilledTokens;
268
+ if (comparison.rebilledTokens <= 0) continue;
269
+ hasRebilledTokens = true;
270
+ if (comparison.estimatedMissPremium === null) missPremiumComplete = false;
271
+ else estimatedMissPremium += comparison.estimatedMissPremium;
272
+ }
273
+
274
+ const requestCount = samples.length + additionalRecords.length;
275
+ const promptTokens = input + cacheRead + cacheWrite;
276
+ return {
277
+ requestCount,
278
+ input,
279
+ cacheRead,
280
+ cacheWrite,
281
+ promptTokens,
282
+ hitRatePercent: promptTokens > 0 && cacheAccountingComplete ? (cacheRead / promptTokens) * 100 : null,
283
+ promptCost: promptCostKnown ? promptCost : null,
284
+ estimatedSavings: requestCount > 0 && savingsKnown ? estimatedSavings : null,
285
+ rebilledTokens,
286
+ estimatedMissPremium: hasRebilledTokens && missPremiumComplete ? estimatedMissPremium : null,
287
+ bestHitRatePercent,
288
+ worstHitRatePercent,
289
+ };
290
+ }
291
+
292
+ export function formatMonitorLines(view: CacheMonitorView): MonitorLine[] {
293
+ if (!view.latest) {
294
+ if (view.session.requestCount > 0) {
295
+ return [
296
+ { role: "title", text: "Prompt cache · summary usage only" },
297
+ formatSessionLine(view.session),
298
+ {
299
+ role: "dim",
300
+ text: "Latest request metrics are unavailable on this branch.",
301
+ },
302
+ ];
303
+ }
304
+ return [
305
+ { role: "title", text: "Prompt cache · waiting for provider cache usage" },
306
+ {
307
+ role: "dim",
308
+ text: "Hit = cacheRead / (input + cacheRead + cacheWrite). All-zero cache fields remain unknown until this provider reports cache activity.",
309
+ },
310
+ ];
311
+ }
312
+
313
+ const latest = view.latest;
314
+ const comparison = view.comparison;
315
+ const session = view.session;
316
+ const live = view.streaming ? " · LIVE" : "";
317
+ const lines: MonitorLine[] = [
318
+ {
319
+ role: "title",
320
+ text: `Prompt cache${live} · request #${view.requestNumber} · ${sanitizeDisplayLabel(latest.provider)}/${sanitizeDisplayLabel(latest.model)}`,
321
+ },
322
+ {
323
+ role: latest.hitRatePercent >= 80 ? "good" : latest.hitRatePercent >= 50 ? "warning" : "bad",
324
+ text: [
325
+ `Latest hit ${formatPercent(latest.hitRatePercent)}`,
326
+ comparison ? `Δ ${formatSignedPercent(comparison.hitRateDeltaPercent)}` : "Δ n/a",
327
+ comparison ? `loss ${formatPercentagePoints(comparison.hitRateLossPercent)}` : "loss n/a",
328
+ `uncached ${formatPercent(latest.uncachedRatePercent)}`,
329
+ ].join(" · "),
330
+ },
331
+ {
332
+ role: "muted",
333
+ text: [
334
+ `Tokens prompt ${formatTokens(latest.promptTokens)}`,
335
+ `read ${formatTokens(latest.cacheRead)}`,
336
+ `write ${formatTokens(latest.cacheWrite)}`,
337
+ `uncached ${formatTokens(latest.input)}`,
338
+ comparison ? `prompt Δ ${formatSignedTokens(comparison.promptTokenDelta)}` : "prompt Δ n/a",
339
+ ].join(" · "),
340
+ },
341
+ ];
342
+
343
+ if (comparison) {
344
+ lines.push({
345
+ role: comparison.rebilledTokens > 0 ? "warning" : "good",
346
+ text: [
347
+ `Reuse vs #${comparison.previousRequestNumber}`,
348
+ `eligible ${formatTokens(comparison.reusablePrefixTokens)}`,
349
+ `re-billed ${formatTokens(comparison.rebilledTokens)} (${formatNullablePercent(comparison.rebilledPercent)})`,
350
+ `read Δ ${formatSignedTokens(comparison.cacheReadDelta)}`,
351
+ comparison.modelChanged ? "model changed" : "same model",
352
+ `start gap ${formatDuration(comparison.requestStartGapMs)}`,
353
+ ].join(" · "),
354
+ });
355
+ } else {
356
+ lines.push({
357
+ role: "dim",
358
+ text: "Reuse no comparable request in the current cache epoch (session start or compaction boundary).",
359
+ });
360
+ }
361
+
362
+ lines.push(
363
+ {
364
+ role: "muted",
365
+ text: [
366
+ `Cost prompt ${formatNullableMoney(latest.promptCost)}`,
367
+ `cache saved ~${formatNullableMoney(latest.estimatedSavings)}`,
368
+ `miss premium ~${formatNullableMoney(comparison?.estimatedMissPremium ?? null)}`,
369
+ ].join(" · "),
370
+ },
371
+ formatSessionLine(session),
372
+ {
373
+ role: "dim",
374
+ text: `Trend old→new ${view.trend.map(formatPercent).join(" → ")}`,
375
+ },
376
+ {
377
+ role: "dim",
378
+ text: "Formula hit=read/prompt · re-billed=max(0, min(previous prompt, current prompt) - current read); costs are estimates from reported/model rates.",
379
+ },
380
+ );
381
+ return lines;
382
+ }
383
+
384
+ function formatSessionLine(session: CacheAggregate): MonitorLine {
385
+ return {
386
+ role: "muted",
387
+ text: [
388
+ `Session ${session.requestCount} req`,
389
+ `hit ${formatNullablePercent(session.hitRatePercent)}`,
390
+ `read ${formatTokens(session.cacheRead)}`,
391
+ `uncached ${formatTokens(session.input)}`,
392
+ `write ${formatTokens(session.cacheWrite)}`,
393
+ `cost ${formatNullableMoney(session.promptCost)}`,
394
+ `saved ~${formatNullableMoney(session.estimatedSavings)}`,
395
+ `re-billed ${formatTokens(session.rebilledTokens)} (~${formatNullableMoney(session.estimatedMissPremium)})`,
396
+ ].join(" · "),
397
+ };
398
+ }
399
+
400
+ export function sanitizeDisplayLabel(value: string): string {
401
+ const stripped = stripTerminalSequences(value)
402
+ .replace(/[^\p{L}\p{N}_.:/@+\- ]+/gu, " ")
403
+ .replace(/\s+/g, " ")
404
+ .trim();
405
+ if (!stripped) return "unknown";
406
+ const characters = [...stripped];
407
+ return characters.length > MAX_LABEL_LENGTH ? `${characters.slice(0, MAX_LABEL_LENGTH).join("")}…` : stripped;
408
+ }
409
+
410
+ interface CacheUsageCalculation {
411
+ record: CacheUsageRecord;
412
+ inputUnitCost: number | null;
413
+ cacheReadUnitCost: number | null;
414
+ paidPromptUnitCost: number | null;
415
+ }
416
+
417
+ interface CacheUsageCalculationOptions {
418
+ costModel?: Model<Api>;
419
+ cacheAccountingKnown?: boolean;
420
+ retainUnknownCacheAccounting?: boolean;
421
+ }
422
+
423
+ function calculateCacheUsage(usage: Usage, options: CacheUsageCalculationOptions = {}): CacheUsageCalculation | null {
424
+ const input = finiteNumber(usage.input);
425
+ const cacheRead = finiteNumber(usage.cacheRead);
426
+ const cacheWrite = finiteNumber(usage.cacheWrite);
427
+ const promptTokens = input + cacheRead + cacheWrite;
428
+ const cacheAccountingKnown = cacheRead > 0 || cacheWrite > 0 || options.cacheAccountingKnown === true;
429
+ if (promptTokens <= 0 || (!cacheAccountingKnown && options.retainUnknownCacheAccounting !== true)) {
430
+ return null;
431
+ }
432
+
433
+ const fallbackCosts = options.costModel
434
+ ? calculateCost(options.costModel, normalizedUsageCopy(usage, input, cacheRead, cacheWrite))
435
+ : undefined;
436
+ const inputCost = componentCost(input, finiteNumber(usage.cost?.input), fallbackCosts?.input);
437
+ const cacheReadCost = componentCost(cacheRead, finiteNumber(usage.cost?.cacheRead), fallbackCosts?.cacheRead);
438
+ const cacheWriteCost = componentCost(cacheWrite, finiteNumber(usage.cost?.cacheWrite), fallbackCosts?.cacheWrite);
439
+ const inputUnitCost =
440
+ input > 0 ? unitCost(input, inputCost) : effectiveInputUnitCost(options.costModel, usage, cacheRead, cacheWrite);
441
+ const cacheReadUnitCost =
442
+ cacheRead > 0
443
+ ? unitCost(cacheRead, cacheReadCost)
444
+ : effectiveCacheReadUnitCost(options.costModel, usage, input, cacheWrite);
445
+ const paidPromptUnitCost = unitCost(input + cacheWrite, sumKnownCosts([inputCost, cacheWriteCost]));
446
+
447
+ return {
448
+ record: {
449
+ input,
450
+ cacheRead,
451
+ cacheWrite,
452
+ promptTokens,
453
+ hitRatePercent: cacheAccountingKnown ? (cacheRead / promptTokens) * 100 : null,
454
+ uncachedRatePercent: cacheAccountingKnown ? (input / promptTokens) * 100 : null,
455
+ promptCost: sumKnownCosts([inputCost, cacheReadCost, cacheWriteCost]),
456
+ estimatedSavings: cacheAccountingKnown
457
+ ? cacheRead === 0
458
+ ? 0
459
+ : inputUnitCost !== null && cacheReadUnitCost !== null
460
+ ? cacheRead * Math.max(0, inputUnitCost - cacheReadUnitCost)
461
+ : null
462
+ : null,
463
+ },
464
+ inputUnitCost,
465
+ cacheReadUnitCost,
466
+ paidPromptUnitCost,
467
+ };
468
+ }
469
+
470
+ function effectiveInputUnitCost(
471
+ costModel: Model<Api> | undefined,
472
+ usage: Usage,
473
+ cacheRead: number,
474
+ cacheWrite: number,
475
+ ): number | null {
476
+ if (!costModel || cacheRead <= 0) return null;
477
+ const probeTokens = Math.min(1, cacheRead);
478
+ const probeUsage = normalizedUsageCopy(usage, probeTokens, cacheRead - probeTokens, cacheWrite);
479
+ return calculateCost(costModel, probeUsage).input / probeTokens;
480
+ }
481
+
482
+ function effectiveCacheReadUnitCost(
483
+ costModel: Model<Api> | undefined,
484
+ usage: Usage,
485
+ input: number,
486
+ cacheWrite: number,
487
+ ): number | null {
488
+ if (!costModel) return null;
489
+ const probeTokens = Math.min(1, input + cacheWrite);
490
+ if (probeTokens <= 0) return null;
491
+ const probeInput = Math.max(0, input - probeTokens);
492
+ const shiftedFromInput = input - probeInput;
493
+ const probeCacheWrite = Math.max(0, cacheWrite - (probeTokens - shiftedFromInput));
494
+ const probeUsage = normalizedUsageCopy(usage, probeInput, probeTokens, probeCacheWrite);
495
+ return calculateCost(costModel, probeUsage).cacheRead / probeTokens;
496
+ }
497
+
498
+ function normalizedUsageCopy(usage: Usage, input: number, cacheRead: number, cacheWrite: number): Usage {
499
+ return {
500
+ ...usage,
501
+ input,
502
+ output: finiteNumber(usage.output),
503
+ cacheRead,
504
+ cacheWrite,
505
+ cacheWrite1h: usage.cacheWrite1h === undefined ? undefined : Math.min(cacheWrite, finiteNumber(usage.cacheWrite1h)),
506
+ totalTokens: finiteNumber(usage.totalTokens),
507
+ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
508
+ };
509
+ }
510
+
511
+ function findPreviousComparableIndex(samples: readonly CacheSample[], currentIndex: number, epoch: number): number {
512
+ for (let index = currentIndex - 1; index >= 0; index -= 1) {
513
+ const candidate = samples[index];
514
+ if (!candidate) continue;
515
+ if (candidate.epoch === epoch) return index;
516
+ if (candidate.epoch < epoch) return -1;
517
+ }
518
+ return -1;
519
+ }
520
+
521
+ function componentCost(tokens: number, reportedCost: number, fallbackCost?: number): number | null {
522
+ if (tokens <= 0) return 0;
523
+ if (reportedCost > 0) return reportedCost;
524
+ return fallbackCost === undefined ? null : fallbackCost;
525
+ }
526
+
527
+ function sumKnownCosts(costs: readonly (number | null)[]): number | null {
528
+ return costs.every((cost) => cost !== null) ? costs.reduce<number>((total, cost) => total + (cost ?? 0), 0) : null;
529
+ }
530
+
531
+ function unitCost(tokens: number, cost: number | null): number | null {
532
+ return tokens > 0 && cost !== null ? cost / tokens : null;
533
+ }
534
+
535
+ function formatPercent(value: number): string {
536
+ return `${value.toFixed(1)}%`;
537
+ }
538
+
539
+ function formatNullablePercent(value: number | null): string {
540
+ return value === null ? "n/a" : formatPercent(value);
541
+ }
542
+
543
+ function formatSignedPercent(value: number): string {
544
+ const sign = value > 0 ? "+" : "";
545
+ return `${sign}${formatPercentagePoints(value)}`;
546
+ }
547
+
548
+ function formatPercentagePoints(value: number): string {
549
+ return `${value.toFixed(1)} pp`;
550
+ }
551
+
552
+ function formatTokens(value: number): string {
553
+ const absolute = Math.abs(value);
554
+ if (absolute < 1_000) return Math.round(value).toLocaleString("en-US");
555
+ if (absolute < 1_000_000) return `${trimFixed(value / 1_000)}k`;
556
+ return `${trimFixed(value / 1_000_000)}m`;
557
+ }
558
+
559
+ function formatSignedTokens(value: number): string {
560
+ return `${value > 0 ? "+" : ""}${formatTokens(value)}`;
561
+ }
562
+
563
+ function trimFixed(value: number): string {
564
+ return value.toFixed(Math.abs(value) >= 100 ? 0 : 1).replace(/\.0$/, "");
565
+ }
566
+
567
+ function formatMoney(value: number): string {
568
+ if (value === 0) return "$0.0000";
569
+ if (value < 0.0001) return "<$0.0001";
570
+ return `$${value.toFixed(value < 0.01 ? 4 : 3)}`;
571
+ }
572
+
573
+ function formatNullableMoney(value: number | null): string {
574
+ return value === null ? "n/a" : formatMoney(value);
575
+ }
576
+
577
+ function formatDuration(milliseconds: number): string {
578
+ if (milliseconds < 1_000) return `${Math.round(milliseconds)}ms`;
579
+ if (milliseconds < 60_000) return `${trimFixed(milliseconds / 1_000)}s`;
580
+ return `${trimFixed(milliseconds / 60_000)}m`;
581
+ }
582
+
583
+ function finiteNumber(value: unknown): number {
584
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
585
+ }