pi-mega-compact 0.11.2 → 0.11.3

package/dist/extensions/dashboard-server/api-contracts/endpoints.js

@@ -8,6 +8,7 @@
  * Sprint A1 — PREVENT-PI-004: zero network code (type definitions only).
  * PREVENT-011: no `any` type — all types are explicit.
  */
+// ─── Provider Cache Lifetime (A.2) — see provider-cache.ts ─────────────────
 // ─── Game Score & Achievement Types ─────────────────────────────────────────
 // (moved to game-types.ts; re-exported for backwards compatibility)
 // ─── Sessions Memory Graph (S39) ─────────────────────────────────────────
@@ -18,7 +19,7 @@
 // (moved to game-types.ts; re-exported for backwards compatibility)
 // ─── ENDPOINTS Registry ─────────────────────────────────────────────────────
 /**
- * Central registry of all 13 dashboard API endpoints. Each entry is an
+ * Central registry of all 14 dashboard API endpoints. Each entry is an
  * `EndpointDef` or `SseEndpointDef` instance serving as the single source of
  * truth for route paths, methods, descriptions, and typed request/response
  * contracts.
@@ -188,4 +189,11 @@ export const ENDPOINTS = {
         path: "/api/maintenance/action",
         description: "Run vacuum, checkpoint, reindex, fts5-rebuild, reconcile-dedup, prune, or integrity-check.",
     },
+    // ─── Provider Cache (Sprint A.2) ─────────────────────────────────
+    /** GET /api/provider-cache — Lifetime provider prompt cache aggregates + $ savings. */
+    providerCache: {
+        method: "GET",
+        path: "/api/provider-cache",
+        description: "Lifetime provider prompt cache hit-rate aggregates + dollar savings estimate.",
+    },
 };

package/dist/extensions/dashboard-server/api-contracts/provider-cache.js

@@ -0,0 +1,7 @@
+/**
+ * api-contracts/provider-cache.ts — Provider prompt cache contract (A.2).
+ *
+ * Response shape for GET /api/provider-cache: lifetime cache hit-rate
+ * aggregates plus optional $ savings estimate priced from model snapshots.
+ */
+export {};

package/dist/extensions/dashboard-server/api-contracts.test.js

@@ -76,7 +76,7 @@ void _c_achievements;
 // Verify the ENDPOINTS registry has exactly 15 entries with correct paths.
 // (Sprint 39 added /api/sessions + /api/sessions/timeseries.)
 const ENDPOINT_KEYS = Object.keys(ENDPOINTS);
-const EXPECTED_ENDPOINT_COUNT = 26; // 23 base + 3 S49B maintenance
+const EXPECTED_ENDPOINT_COUNT = 27; // 23 base + 3 S49B maintenance + 1 provider-cache
 /** All `/api/*` paths served by server.ts (extracted from the route handlers). */
 const SERVER_TS_PATHS = [
     "/api/snapshot",
@@ -94,10 +94,11 @@ const SERVER_TS_PATHS = [
     "/api/sessions",
     "/api/sessions/timeseries",
     "/api/topics",
+    "/api/provider-cache",
 ];
 // ─── Tests ───────────────────────────────────────────────────────────────────
 describe("ENDPOINTS registry", () => {
-    test("has exactly 16 endpoint entries", () => {
+    test("has exactly the expected endpoint count", () => {
         assert.equal(ENDPOINT_KEYS.length, EXPECTED_ENDPOINT_COUNT, `ENDPOINTS must have ${EXPECTED_ENDPOINT_COUNT} entries, got ${ENDPOINT_KEYS.length}`);
     });
     test("every server.ts /api/* path has a corresponding ENDPOINTS entry", () => {

package/dist/extensions/dashboard-server/index-reader.js

@@ -57,6 +57,9 @@ export function readIndex() {
             contextWindow: null,
             maxTokens: null,
             reasoning: null,
+            providerCachePct: null,
+            providerCacheRead: null,
+            providerCacheWrite: null,
         }));
         // Enrich each repo with per-store token + model detail read directly via
         // node:sqlite (same zero-dependency invariant as readIndex; no store graph
@@ -86,6 +89,25 @@ export function readIndex() {
                             repo.maxTokens = Number(mrow.max_tokens ?? 0) || null;
                             repo.reasoning = Number(mrow.reasoning ?? 0) === 1;
                         }
+                        // Provider prompt-cache stats (E.3)
+                        try {
+                            const pRow = sdb
+                                .prepare(`SELECT
+                    SUM(cache_read) AS totalRead,
+                    SUM(cache_write) AS totalWrite,
+                    SUM(cache_read + cache_write) * 1.0 / MAX(SUM(cache_read + cache_write + tokens_in), 1) AS hitPct
+                   FROM perf_samples
+                   WHERE cache_read > 0 OR cache_write > 0`)
+                                .get();
+                            if (pRow && pRow.totalRead > 0) {
+                                repo.providerCacheRead = Number(pRow.totalRead);
+                                repo.providerCacheWrite = Number(pRow.totalWrite);
+                                repo.providerCachePct = Number((pRow.hitPct * 100).toFixed(1));
+                            }
+                        }
+                        catch {
+                            /* best-effort — perf_samples may not exist */
+                        }
                     }
                     finally {
                         sdb.close();

package/dist/extensions/dashboard-server/routes-cache.js

@@ -0,0 +1,80 @@
+/**
+ * dashboard-server/routes-cache.ts — Provider prompt-cache stats route handler.
+ *
+ * GET /api/provider-cache — Lifetime provider prompt cache hit-rate aggregates
+ * plus dollar savings estimate (priced from latest model snapshot).
+ *
+ * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe JSON parse),
+ * PREVENT-002 (parameterized SQL). Loopback-only localhost dashboard endpoint.
+ */
+import { createRequire } from "node:module";
+import { computeCacheSavings } from "../../src/pricing.js";
+// ---------------------------------------------------------------------------
+// handleProviderCache — "/api/provider-cache"
+// ---------------------------------------------------------------------------
+export function handleProviderCache(req, res, ctx) {
+    if (!req.url?.startsWith("/api/provider-cache"))
+        return false;
+    const { stateDir } = ctx;
+    // /api/provider-cache — GET returns lifetime provider prompt cache aggregates
+    // from perf_samples (cache_hit_pct rows with meta JSON) plus an optional
+    // dollar savings estimate priced from the latest model snapshot. The dashboard
+    // server is a detached child with no MegaRuntime ref, so it reads via a
+    // require()'d sqlite helper (same pattern as /api/perf). Non-GET → 405.
+    // PREVENT-PI-004: loopback.
+    const pfReq = createRequire(import.meta.url);
+    const { readProviderCacheLifetime, latestModelSnapshot } = pfReq("../../src/store/sqlite.js");
+    if (req.method !== "GET") {
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "method_not_allowed" }));
+        return true;
+    }
+    try {
+        const lifetime = readProviderCacheLifetime(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+        // D3: compute dollar savings from the latest model snapshot.  Null-safe:
+        // when no snapshot or zero input rate, savings stays null (UI shows "—").
+        let savings = null;
+        try {
+            const snap = latestModelSnapshot(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+            if (snap && snap.inputRate > 0) {
+                const s = computeCacheSavings(lifetime.totalCacheRead, lifetime.totalCacheWrite, snap.inputRate);
+                savings = {
+                    cacheReadSaved: s.cacheReadSaved,
+                    cacheWriteCost: s.cacheWriteCost,
+                    netSaved: s.netSaved,
+                    model: snap.modelName ?? snap.modelId ?? "unknown",
+                    inputRate: snap.inputRate,
+                };
+            }
+        }
+        catch {
+            /* pricing unavailable — savings stays null */
+        }
+        const body = {
+            cache: {
+                avgHitPct: lifetime.avgHitPct,
+                turnCount: lifetime.sampleCount,
+                totalCacheRead: lifetime.totalCacheRead,
+                totalCacheWrite: lifetime.totalCacheWrite,
+                totalInput: lifetime.totalInput,
+                firstTurnAt: lifetime.firstSampleAt,
+                latestTurnAt: lifetime.latestSampleAt,
+            },
+            savings,
+            updatedAt: new Date().toISOString(),
+        };
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(body));
+    }
+    catch (e) {
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            error: "provider_cache_unavailable",
+            detail: String(e),
+        }));
+    }
+    return true;
+}

package/dist/extensions/dashboard-server/routes-cache.test.js

@@ -0,0 +1,248 @@
+/**
+ * routes-cache.test.ts — Sprint A /api/provider-cache endpoint tests.
+ *
+ * Covers the A.4 spec:
+ * - GET 200 → shape matches ProviderCacheResponse
+ * - POST → 405
+ * - empty perf_samples → zeros/nulls
+ * - no model snapshot → savings: null
+ * - with model snapshot → priced savings fields
+ *
+ * Uses the same spawn-and-fetch harness as perf-server.test.ts.
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { recordPerfSample, recordModelSnapshot, } from "../../src/store/sqlite.js";
+const SERVER_ENTRY = new URL("./server.js", import.meta.url).pathname;
+function waitFor(cond, timeoutMs = 6000) {
+    const start = Date.now();
+    return new Promise((resolve, reject) => {
+        const tick = async () => {
+            if (await cond())
+                return resolve();
+            if (Date.now() - start > timeoutMs)
+                return reject(new Error("timeout"));
+            setTimeout(tick, 50);
+        };
+        tick();
+    });
+}
+function freshDir(prefix) {
+    return mkdtempSync(join(tmpdir(), prefix));
+}
+async function withServer(port, dir, fn) {
+    process.env.MEGACOMPACT_DASHBOARD_PORT = port;
+    const child = spawn(process.execPath, [SERVER_ENTRY, dir], {
+        stdio: "ignore",
+    });
+    try {
+        await waitFor(async () => {
+            try {
+                const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+                const res = await fetch(`http://localhost:${raw.port}/api/version`);
+                return res.ok;
+            }
+            catch {
+                return false;
+            }
+        });
+        const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+        return await fn(raw.port);
+    }
+    finally {
+        child.kill("SIGTERM");
+        delete process.env.MEGACOMPACT_DASHBOARD_PORT;
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+describe("/api/provider-cache", () => {
+    test("GET 200 — shape matches ProviderCacheResponse", async () => {
+        const dir = freshDir("dash-pcache-agg-");
+        // Seed one cache_hit_pct sample with full meta.
+        recordPerfSample(dir, "cache_hit_pct", 42, {
+            cacheRead: 100,
+            cacheWrite: 20,
+            input: 500,
+        });
+        await withServer("19450", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            // Shape assertions
+            assert.ok("cache" in body, "should have cache");
+            assert.ok("savings" in body, "should have savings");
+            assert.ok("updatedAt" in body, "should have updatedAt");
+            assert.equal(body.cache.turnCount, 1);
+            assert.equal(body.cache.totalCacheRead, 100);
+            assert.equal(body.cache.totalCacheWrite, 20);
+            assert.equal(body.cache.totalInput, 500);
+            assert.ok(typeof body.cache.firstTurnAt === "string");
+            assert.ok(typeof body.cache.latestTurnAt === "string");
+            assert.ok(typeof body.updatedAt === "string");
+        });
+    });
+    test("GET 200 — empty perf_samples returns zeros/nulls", async () => {
+        const dir = freshDir("dash-pcache-empty-");
+        await withServer("19451", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.equal(body.cache.turnCount, 0);
+            assert.equal(body.cache.avgHitPct, 0);
+            assert.equal(body.cache.totalCacheRead, 0);
+            assert.equal(body.cache.totalCacheWrite, 0);
+            assert.equal(body.cache.totalInput, 0);
+            assert.equal(body.cache.firstTurnAt, null);
+            assert.equal(body.cache.latestTurnAt, null);
+            assert.equal(body.savings, null);
+        });
+    });
+    test("POST → 405", async () => {
+        const dir = freshDir("dash-pcache-meth-");
+        await withServer("19452", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`, {
+                method: "POST",
+            });
+            assert.equal(res.status, 405);
+            const body = (await res.json());
+            assert.equal(body.error, "method_not_allowed");
+        });
+    });
+    test("no model snapshot → savings: null", async () => {
+        const dir = freshDir("dash-pcache-nosnap-");
+        recordPerfSample(dir, "cache_hit_pct", 50, {
+            cacheRead: 200,
+            cacheWrite: 30,
+            input: 1000,
+        });
+        await withServer("19453", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.equal(body.savings, null);
+        });
+    });
+    test("with model snapshot → priced savings fields", async () => {
+        const dir = freshDir("dash-pcache-savings-");
+        recordPerfSample(dir, "cache_hit_pct", 50, {
+            cacheRead: 2000,
+            cacheWrite: 400,
+            input: 10000,
+        });
+        // Record a model snapshot with a known input rate.
+        recordModelSnapshot("/tmp/test-repo", {
+            provider: "anthropic",
+            providerName: "Anthropic",
+            modelId: "claude-sonnet-4-20250514",
+            modelName: "Claude Sonnet 4",
+            inputRate: 3e-6, // $3 / 1M tokens
+            outputRate: 15e-6,
+            contextWindow: 200000,
+            maxTokens: 32000,
+            reasoning: false,
+        }, dir);
+        await withServer("19454", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.ok(body.savings, "savings should not be null");
+            // cacheReadSaved = 2000 * 3e-6 * 0.9 = 0.0054
+            assert.ok(body.savings.cacheReadSaved > 0, "cacheReadSaved > 0");
+            // cacheWriteCost = 400 * 3e-6 * 0.25 = 0.0003
+            assert.ok(body.savings.cacheWriteCost > 0, "cacheWriteCost > 0");
+            assert.ok(body.savings.netSaved ===
+                body.savings.cacheReadSaved - body.savings.cacheWriteCost, "netSaved = cacheReadSaved - cacheWriteCost");
+            assert.equal(body.savings.model, "Claude Sonnet 4");
+            assert.equal(body.savings.inputRate, 3e-6);
+        });
+    });
+    test("partial meta (missing fields) → treated as 0", async () => {
+        const dir = freshDir("dash-pcache-partial-");
+        // Only input in meta; cacheRead/cacheWrite missing → treated as 0.
+        recordPerfSample(dir, "cache_hit_pct", 30, { input: 800 });
+        // Only cacheRead in meta; input/cacheWrite missing → treated as 0.
+        recordPerfSample(dir, "cache_hit_pct", 60, { cacheRead: 150 });
+        await withServer("19455", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            // First sample: input=800, cacheRead=0, cacheWrite=0
+            // Second sample: cacheRead=150, input=0, cacheWrite=0
+            assert.equal(body.cache.turnCount, 2);
+            assert.equal(body.cache.totalCacheRead, 150);
+            assert.equal(body.cache.totalCacheWrite, 0);
+            assert.equal(body.cache.totalInput, 800);
+        });
+    });
+    test("NULL meta → counted in turnCount, contributes 0 tokens + 0 avg", async () => {
+        const dir = freshDir("dash-pcache-nullmeta-");
+        // avgHitPct is derived from (cacheRead / (cacheRead + input + cacheWrite)) * 100,
+        // NOT from the `value` column. NULL meta → no tokens → avg 0, not 25.
+        recordPerfSample(dir, "cache_hit_pct", 25, undefined);
+        await withServer("19456", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.equal(body.cache.turnCount, 1);
+            assert.equal(body.cache.avgHitPct, 0);
+            assert.equal(body.cache.totalCacheRead, 0);
+            assert.equal(body.cache.totalCacheWrite, 0);
+            assert.equal(body.cache.totalInput, 0);
+        });
+    });
+    test("model snapshot with modelName=null → falls back to modelId", async () => {
+        const dir = freshDir("dash-pcache-modelid-");
+        recordPerfSample(dir, "cache_hit_pct", 10, {
+            cacheRead: 100,
+            cacheWrite: 10,
+            input: 1000,
+        });
+        recordModelSnapshot("/tmp/test-repo", {
+            provider: "openai",
+            providerName: null,
+            modelId: "gpt-4o",
+            modelName: null,
+            inputRate: 2.5e-6,
+            outputRate: 10e-6,
+            contextWindow: 128000,
+            maxTokens: 16384,
+            reasoning: false,
+        }, dir);
+        await withServer("19457", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.ok(body.savings);
+            assert.equal(body.savings.model, "gpt-4o");
+        });
+    });
+    test("model snapshot with zero inputRate → savings: null", async () => {
+        const dir = freshDir("dash-pcache-zerorate-");
+        recordPerfSample(dir, "cache_hit_pct", 10, {
+            cacheRead: 100,
+            cacheWrite: 10,
+            input: 1000,
+        });
+        recordModelSnapshot("/tmp/test-repo", {
+            provider: "local",
+            providerName: null,
+            modelId: "local-llm",
+            modelName: null,
+            inputRate: 0,
+            outputRate: 0,
+            contextWindow: 4096,
+            maxTokens: 2048,
+            reasoning: false,
+        }, dir);
+        await withServer("19458", dir, async (port) => {
+            const res = await fetch(`http://localhost:${port}/api/provider-cache`);
+            assert.equal(res.status, 200);
+            const body = (await res.json());
+            assert.equal(body.savings, null);
+        });
+    });
+});

package/dist/extensions/dashboard-server/routes-maintenance.js

@@ -102,14 +102,16 @@ function sendSchemaHealth(res, ctx) {
             .get("schema_version");
         const schemaVersion = metaRow ? Number(metaRow.value) : 0;
         // PRAGMA foreign_key_check
-        const fkRows = db
-            .prepare("PRAGMA foreign_key_check")
-            .all();
+        const fkRows = db.prepare("PRAGMA foreign_key_check").all();
         const fkCheck = fkRows.map((r) => JSON.stringify(r));
         // Per-column audit: every ensureColumn migration column declared in
         // schema.ts, checked via PRAGMA table_info (read-only).
         const expectedColumns = [
-            { table: "context_chunks", column: "original_token_estimate", decl: "INTEGER" },
+            {
+                table: "context_chunks",
+                column: "original_token_estimate",
+                decl: "INTEGER",
+            },
             { table: "raw_transcript", column: "content_ref", decl: "TEXT" },
             { table: "memories", column: "category", decl: "TEXT" },
             { table: "memories", column: "target", decl: "TEXT" },
@@ -121,9 +123,7 @@ function sendSchemaHealth(res, ctx) {
             { table: "session_state", column: "last_turn_id", decl: "INTEGER" },
         ];
         const columns = expectedColumns.map((ec) => {
-            const cols = db
-                .prepare(`PRAGMA table_info(${ec.table})`)
-                .all();
+            const cols = db.prepare(`PRAGMA table_info(${ec.table})`).all();
             const present = cols.some((c) => c.name === ec.column);
             return {
                 table: ec.table,

package/dist/extensions/dashboard-server/routes-repo.js

@@ -7,6 +7,9 @@ import { readSnapshot } from "./snapshot.js";
 import { dashboardHtml } from "./html.js";
 import { readIndex, getIndexDir } from "./index-reader.js";
 import { ACTIVE_WINDOW_SEC } from "./types.js";
+import { readProviderCacheForRepo } from "../../src/store/sqlite/perf-samples.js";
+import { computeCacheSavings, lookupModelInputRate } from "../../src/pricing.js";
+import { latestModelSnapshot } from "../../src/store/sqlite/model-snapshots.js";
 // ---------------------------------------------------------------------------
 // handleIndex — "/" | "/index.html" | "/api/snapshot" | "/api/version"
 // ---------------------------------------------------------------------------
@@ -132,6 +135,27 @@ export function handleRepoIndex(req, res, ctx) {
                         out.compacts = snap.compacts ?? null;
                         out.timeSaved = snap.timeSaved ?? null;
                         out.updatedAt = snap.updatedAt ?? null;
+                        // Provider cache per-repo lifetime (E.2)
+                        try {
+                            const pc = readProviderCacheForRepo(r.stateDir);
+                            // Price from model snapshot if available
+                            const modelSnap = latestModelSnapshot(r.stateDir);
+                            const inputRate = modelSnap
+                                ? modelSnap.inputRate
+                                : lookupModelInputRate(r.modelName ?? "") ?? 0;
+                            const savings = computeCacheSavings(pc.totalCacheRead, pc.totalCacheWrite, inputRate);
+                            out.providerCache = {
+                                avgHitPct: pc.avgHitPct,
+                                cacheRead: pc.totalCacheRead,
+                                cacheWrite: pc.totalCacheWrite,
+                                totalInput: pc.totalInput,
+                                sampleCount: pc.sampleCount,
+                                estimatedSaved: savings.netSaved > 0 ? savings.netSaved : null,
+                            };
+                        }
+                        catch {
+                            /* best-effort — repo may not have perf_samples */
+                        }
                     }
                 }
                 catch {

package/dist/extensions/dashboard-server/routes.js

@@ -11,3 +11,4 @@ export { handleEvents, handleSessions } from "./routes-sessions.js";
 export { handleTopics } from "./routes-topics.js";
 export { handleTurns } from "./routes-turns.js";
 export { handleMaintenance } from "./routes-maintenance.js";
+export { handleProviderCache } from "./routes-cache.js";

package/dist/extensions/dashboard-server/server.js

@@ -12,7 +12,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
-import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleStatic, } from "./routes.js";
 export async function launchDashboardServer(stateDir) {
     // Our own package version — exposed at /api/version so the launcher can
     // detect a stale server (started by an older build) and replace it on
@@ -193,6 +193,8 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleMaintenance(req, res, ctx))
             return;
+        if (handleProviderCache(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,