feat(engine): add computeCacheHitRatio metric to token usage tracking

packages/engine/src/__tests__/token-usage-cache-ratio.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import { computeCacheHitRatio } from "../session-token-usage.js";
+
+describe("computeCacheHitRatio", () => {
+  it("returns 0 when no tokens used", () => {
+    expect(computeCacheHitRatio(0, 0)).toBe(0);
+  });
+
+  it("returns 0 when no cached tokens", () => {
+    expect(computeCacheHitRatio(1000, 0)).toBe(0);
+  });
+
+  it("returns ratio of cached to total input", () => {
+    expect(computeCacheHitRatio(500, 500)).toBeCloseTo(0.5);
+  });
+
+  it("returns close to 1 when mostly cached", () => {
+    expect(computeCacheHitRatio(100, 9900)).toBeCloseTo(0.99);
+  });
+});

packages/engine/src/session-token-usage.ts

@@ -90,3 +90,21 @@ export async function accumulateSessionTokenUsage(
     log.warn(`${taskId}: session token usage accumulate failed: ${message}`);
   }
 }
+
+/**
+ * Compute the cache hit ratio: the fraction of input tokens served from
+ * cache. Returns a number in [0, 1]. Useful for measuring the effectiveness
+ * of prompt caching optimizations.
+ *
+ * @param inputTokens - Non-cached input tokens (includes cache-write tokens)
+ * @param cachedTokens - Tokens read from cache
+ * @returns Cache hit ratio in [0, 1], or 0 if no tokens used
+ */
+export function computeCacheHitRatio(
+  inputTokens: number,
+  cachedTokens: number,
+): number {
+  const total = inputTokens + cachedTokens;
+  if (total === 0) return 0;
+  return cachedTokens / total;
+}