feat: add cache routing alignment and usage visibility for 2.5.0

apps/showcase_ui/src/app/utils/run-info.util.spec.ts

@@ -1,5 +1,6 @@
 import {
   contextPercent,
+  cachePercent,
   runMode,
   formatCompactTokens,
   formatElapsed,
@@ -9,6 +10,20 @@ import {
 } from './run-info.util';
 
 describe('run-info.util', () => {
+  describe('cachePercent', () => {
+    it('uses cumulative cached input divided by cumulative input, independent of output', () => {
+      // Calls: 90/100 and 0/900 -> 9%, rather than an average of 45%.
+      expect(cachePercent(90, 1000)).toBe(9);
+      expect(cachePercent(90000, 305000)).toBe(29.5);
+      expect(cachePercent(0, 100)).toBe(0);
+      expect(cachePercent(100, 100)).toBe(100);
+    });
+    it('keeps missing, empty and invalid usage distinct from a measured zero', () => {
+      for (const [cached, prompt] of [[0, 0], [null, 100], [undefined, 100], [0, null], [NaN, 100], [Infinity, 100], [1, Infinity], [-1, 100], [101, 100]]) {
+        expect(cachePercent(cached, prompt)).toBeNull();
+      }
+    });
+  });
   describe('formatElapsed', () => {
     it('formats seconds, minutes and hours with zero padding', () => {
       expect(formatElapsed(0)).toBe('0s');

apps/showcase_ui/src/app/utils/run-info.util.ts

@@ -80,6 +80,14 @@ export function contextPercent(
   return Math.min(100, Math.round(pct * 10) / 10);
 }
 
+/** Session-wide token-weighted cache share; cached input is part of total input. */
+export function cachePercent(cachedTokens: number | null | undefined, promptTokens: number | null | undefined): number | null {
+  if (typeof cachedTokens !== 'number' || typeof promptTokens !== 'number' ||
+      !Number.isFinite(cachedTokens) || !Number.isFinite(promptTokens) ||
+      promptTokens <= 0 || cachedTokens < 0 || cachedTokens > promptTokens) return null;
+  return Math.round(cachedTokens / promptTokens * 1000) / 10;
+}
+
 /**
  * Seconds a session has been (or was) running.
  *