pi-mega-compact 0.11.3 → 0.11.5

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

@@ -196,4 +196,23 @@ export const ENDPOINTS = {
         path: "/api/provider-cache",
         description: "Lifetime provider prompt cache hit-rate aggregates + dollar savings estimate.",
     },
+    // ─── Memory Effectiveness (S53B) ───────────────────────────────────────
+    /** GET /api/memory-status — Memory store aggregate statistics. */
+    memoryStatus: {
+        method: "GET",
+        path: "/api/memory-status",
+        description: "Memory store statistics: total count, 30-day window, top-N stable memories, avg recall score.",
+    },
+    /** GET /api/setup-status — Current embedder configuration. */
+    setupStatus: {
+        method: "GET",
+        path: "/api/setup-status",
+        description: "Current embedder configuration (which embedder is active, embedding URL, cache, MiniLM flag).",
+    },
+    /** GET /api/setup-detect — Detect available local embedder backends. */
+    setupDetect: {
+        method: "GET",
+        path: "/api/setup-detect",
+        description: "Best-effort detection of local embedder backends (ollama, llama.cpp, ONNX) available on the machine.",
+    },
 };

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

@@ -0,0 +1,8 @@
+/**
+ * api-contracts/memory.ts — Memory effectiveness stats contract (S53B).
+ *
+ * Response shape for GET /api/memory-status: aggregate memory-store statistics
+ * including total count, 30-day window, top-N stable memories by recall, and
+ * average recall score.
+ */
+export {};

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

@@ -3,5 +3,6 @@
  *
  * Response shape for GET /api/provider-cache: lifetime cache hit-rate
  * aggregates plus optional $ savings estimate priced from model snapshots.
+ * F4 adds per-model breakdown (byModel).
  */
 export {};

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

@@ -0,0 +1,10 @@
+/**
+ * api-contracts/setup.ts — Setup wizard API response types.
+ *
+ * Types for the /api/setup-status and /api/setup-detect endpoints used
+ * by the /megasetup command and dashboard Setup tab.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type — all types are explicit.
+ */
+export {};

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

@@ -123,7 +123,9 @@ export function readIndex() {
         // paths that should never have been real repos, and collapse duplicate
         // display names to the most-recently-seen row (rows are last_seen DESC, so
         // the first occurrence wins). Keeps the All-repos list readable.
-        const isTransient = (p) => /^\/tmp\//.test(p) || /^\/private\/tmp\//.test(p) || /^\/var\/folders\//.test(p) ||
+        const isTransient = (p) => /^\/tmp\//.test(p) ||
+            /^\/private\/tmp\//.test(p) ||
+            /^\/var\/folders\//.test(p) ||
             /\/mc-(ext|e2e|resume|recall)-/.test(p);
         const seenName = new Set();
         const repos = [];
@@ -150,6 +152,8 @@ export function readIndex() {
         try {
             db?.close();
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
     }
 }

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

@@ -3,6 +3,7 @@
  *
  * GET /api/provider-cache — Lifetime provider prompt cache hit-rate aggregates
  * plus dollar savings estimate (priced from latest model snapshot).
+ * Accepts optional ?minutes=N, ?since=<epoch-ms>, ?until=<epoch-ms> (S53A).
  *
  * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe JSON parse),
  * PREVENT-002 (parameterized SQL). Loopback-only localhost dashboard endpoint.
@@ -15,66 +16,125 @@ import { computeCacheSavings } from "../../src/pricing.js";
 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,
-                };
+        const stateDir = ctx.stateDir;
+        // PREVENT-PI-004: loopback.
+        const pfReq = createRequire(import.meta.url);
+        const { readProviderCacheLifetime, readProviderCacheWindow, 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;
+        }
+        // Parse query params: ?minutes=N | ?since=&until= (mutually exclusive).
+        let windowMinutes = null;
+        let sinceTs = 0;
+        let untilTs = 0;
+        if (req.url) {
+            const qIdx = req.url.indexOf("?");
+            if (qIdx !== -1) {
+                const params = new URLSearchParams(req.url.slice(qIdx));
+                const m = params.get("minutes");
+                if (m != null) {
+                    const n = parseInt(m, 10);
+                    if (Number.isFinite(n) && n > 0 && String(n) === m.trim()) {
+                        windowMinutes = n;
+                    }
+                }
+                // S53A: ?since=&until= epoch-ms timestamps.
+                const s = params.get("since");
+                const u = params.get("until");
+                if (s != null) {
+                    const sn = Number(s);
+                    if (Number.isFinite(sn) && sn >= 0)
+                        sinceTs = sn;
+                }
+                if (u != null) {
+                    const un = Number(u);
+                    if (Number.isFinite(un) && un > 0)
+                        untilTs = un;
+                }
             }
         }
+        // S53A: read prefix_break samples in the same window as the aggregates.
+        // Import lazily to avoid a circular dependency in the test harness.
+        let prefixBreaks = [];
+        try {
+            // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+            const { readPrefixBreaks } = pfReq("../../src/store/sqlite/perf-samples.js");
+            // When ?since=&until= is used, pass those directly; otherwise derive
+            // from windowMinutes or 0 (no bounds = lifetime).
+            const pSince = sinceTs > 0 ? sinceTs : (windowMinutes != null ? Date.now() - windowMinutes * 60_000 : 0);
+            const pUntil = untilTs > 0 ? untilTs : (windowMinutes != null ? Date.now() : 0);
+            const rows = readPrefixBreaks(stateDir, pSince, pUntil);
+            prefixBreaks = rows.map((r) => ({
+                id: r.id,
+                ts: r.ts,
+                cause: r.meta.cause,
+                confidence: r.meta.confidence,
+                prevHitPct: r.meta.prevHitPct,
+                currHitPct: r.meta.currHitPct,
+                breakAt: r.meta.breakAt,
+            }));
+        }
         catch {
-            /* pricing unavailable — savings stays null */
+            /* prefix-break read unavailable — response still returns empty array */
         }
-        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));
+        try {
+            const lifetime = windowMinutes != null
+                ? readProviderCacheWindow(stateDir, windowMinutes)
+                : 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,
+                    byModel: lifetime.byModel,
+                },
+                savings,
+                updatedAt: new Date().toISOString(),
+                windowMinutes,
+                prefixBreaks,
+            };
+            // 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;
     }
-    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),
-        }));
+    catch {
+        return false;
     }
-    return true;
 }

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

@@ -0,0 +1,51 @@
+/**
+ * dashboard-server/routes-memory.ts — Memory effectiveness stats route handler (S53B).
+ *
+ * GET /api/memory-status — Returns memoryStats() aggregated data:
+ *   totalMemories, memoriesInLast30Days, topStableMemories, avgRecallScore.
+ *
+ * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe JSON),
+ * PREVENT-002 (parameterized SQL — memoryStats uses openStore internally).
+ * Loopback-only localhost dashboard endpoint.
+ */
+import { createRequire } from "node:module";
+// PREVENT-PI-004: memoryStats is a pure local module (no network, no side-effects at import time).
+// guardrails-allow PREVENT-PI-004: local TypeScript module import (loopback-only).
+const { memoryStats } = createRequire(import.meta.url)("../../src/memoryStats.js");
+// ---------------------------------------------------------------------------
+// handleMemoryStatus — "/api/memory-status"
+// ---------------------------------------------------------------------------
+export function handleMemoryStatus(req, res, ctx) {
+    if (!req.url?.startsWith("/api/memory-status"))
+        return false;
+    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;
+    }
+    // PREVENT-PI-004: loopback-only — memoryStats reads from local SQLite store.
+    memoryStats(ctx.stateDir)
+        .then((stats) => {
+        const body = {
+            totalMemories: stats.totalMemories,
+            memoriesInLast30Days: stats.memoriesInLast30Days,
+            topStableMemories: stats.topStableMemories.map((m) => ({
+                id: m.id,
+                text: m.text,
+                recallCount: m.recallCount,
+                lastRecalledAt: m.lastRecalledAt,
+            })),
+            avgRecallScore: stats.avgRecallScore,
+        };
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(body));
+    })
+        .catch(() => {
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "memory_stats_unavailable" }));
+    });
+    return true;
+}

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

@@ -8,7 +8,7 @@ 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 { computeCacheSavings, lookupModelInputRate, } from "../../src/pricing.js";
 import { latestModelSnapshot } from "../../src/store/sqlite/model-snapshots.js";
 // ---------------------------------------------------------------------------
 // handleIndex — "/" | "/index.html" | "/api/snapshot" | "/api/version"
@@ -142,7 +142,7 @@ export function handleRepoIndex(req, res, ctx) {
                             const modelSnap = latestModelSnapshot(r.stateDir);
                             const inputRate = modelSnap
                                 ? modelSnap.inputRate
-                                : lookupModelInputRate(r.modelName ?? "") ?? 0;
+                                : (lookupModelInputRate(r.modelName ?? "") ?? 0);
                             const savings = computeCacheSavings(pc.totalCacheRead, pc.totalCacheWrite, inputRate);
                             out.providerCache = {
                                 avgHitPct: pc.avgHitPct,

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

@@ -0,0 +1,162 @@
+/**
+ * dashboard-server/routes-setup.ts — Setup wizard route handlers.
+ *
+ * GET /api/setup-status  — Returns current embedder configuration from env.
+ * GET /api/setup-detect  — Runs best-effort detection of local embedder backends.
+ *
+ * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe JSON).
+ * The detection commands run local subprocesses via spawnSync, NOT network calls.
+ * Each decoration line carries a guardrails-allow annotation.
+ */
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only
+import { createRequire } from "node:module";
+// ---------------------------------------------------------------------------
+// handleSetupStatus — "/api/setup-status"
+// ---------------------------------------------------------------------------
+function detectCurrentEmbedder() {
+    const url = process.env["MEGACOMPACT_EMBEDDING_URL"];
+    const minilm = process.env["MEGACOMPACT_MINILM"];
+    if (url && url.trim().length > 0)
+        return "http";
+    if (minilm && ["1", "true", "yes"].includes(minilm.trim().toLowerCase()))
+        return "minilm";
+    return "trigram";
+}
+export function handleSetupStatus(req, res, _ctx) {
+    if (req.url !== "/api/setup-status")
+        return false;
+    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;
+    }
+    const body = {
+        currentEmbedder: detectCurrentEmbedder(),
+        embeddingUrl: process.env["MEGACOMPACT_EMBEDDING_URL"] ?? null,
+        embedCache: process.env["MEGACOMPACT_EMBED_CACHE"] ?? null,
+        minilm: ["1", "true", "yes"].includes((process.env["MEGACOMPACT_MINILM"] ?? "").trim().toLowerCase()),
+    };
+    // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+    return true;
+}
+// ---------------------------------------------------------------------------
+// handleSetupDetect — "/api/setup-detect"
+// ---------------------------------------------------------------------------
+function detectOllama() {
+    try {
+        const version = spawnSync("ollama", ["--version"], {
+            timeout: 5000,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (version.status !== 0) {
+            return { installed: false, models: [], running: false, detail: version.stderr?.trim() || "not found" };
+        }
+        // Check for running server
+        let running = false;
+        let models = [];
+        try {
+            const listResult = spawnSync("ollama", ["list"], {
+                timeout: 5000,
+                encoding: "utf-8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            if (listResult.status === 0) {
+                running = true;
+                // Parse lines: NAME  ID  SIZE  MODIFIED
+                const lines = listResult.stdout?.split("\n") ?? [];
+                for (const line of lines) {
+                    const name = line.split(/\s+/)[0];
+                    if (name && name !== "NAME")
+                        models.push(name);
+                }
+            }
+        }
+        catch {
+            // ollama list failed — server may not be running
+            running = false;
+        }
+        return {
+            installed: true,
+            models,
+            running,
+            detail: version.stdout?.trim() || null,
+        };
+    }
+    catch {
+        return { installed: false, models: [], running: false, detail: "detection error" };
+    }
+}
+function detectLlamaCpp() {
+    try {
+        const which = spawnSync("which", ["llama-server", "llama.cpp"], {
+            timeout: 3000,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const installed = which.status === 0 && which.stdout.trim().length > 0;
+        return {
+            installed,
+            detail: installed ? which.stdout.trim() : null,
+        };
+    }
+    catch {
+        return { installed: false, detail: "detection error" };
+    }
+}
+function detectOnnx() {
+    try {
+        // Check for onnxruntime-node in a parent node_modules
+        const req = createRequire(import.meta.url);
+        try {
+            req.resolve("onnxruntime-node");
+            return { installed: true, detail: "onnxruntime-node found in node_modules" };
+        }
+        catch {
+            return { installed: false, detail: "onnxruntime-node not found in node_modules" };
+        }
+    }
+    catch {
+        return { installed: false, detail: "detection error" };
+    }
+}
+export function handleSetupDetect(req, res, _ctx) {
+    if (req.url !== "/api/setup-detect")
+        return false;
+    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;
+    }
+    let error = null;
+    let ollama = null;
+    let llamaCpp = null;
+    let onnx = null;
+    try {
+        ollama = detectOllama();
+    }
+    catch (e) {
+        error = `ollama detection failed: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    try {
+        llamaCpp = detectLlamaCpp();
+    }
+    catch (e) {
+        error = error ?? `llama.cpp detection failed: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    try {
+        onnx = detectOnnx();
+    }
+    catch (e) {
+        error = error ?? `onnx detection failed: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    const body = { ollama, llamaCpp, onnx, error };
+    // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+    return true;
+}

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

@@ -12,3 +12,5 @@ export { handleTopics } from "./routes-topics.js";
 export { handleTurns } from "./routes-turns.js";
 export { handleMaintenance } from "./routes-maintenance.js";
 export { handleProviderCache } from "./routes-cache.js";
+export { handleMemoryStatus } from "./routes-memory.js";
+export { handleSetupStatus, handleSetupDetect } from "./routes-setup.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, handleProviderCache, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleMemoryStatus, handleSetupStatus, handleSetupDetect, 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
@@ -195,6 +195,12 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleProviderCache(req, res, ctx))
             return;
+        if (handleMemoryStatus(req, res, ctx))
+            return;
+        if (handleSetupStatus(req, res, ctx))
+            return;
+        if (handleSetupDetect(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,