pi-mega-compact 0.11.5 → 0.11.6

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

@@ -0,0 +1,8 @@
+/**
+ * api-contracts/cache-stripes.ts — Cache stripe API contract (A3, PLAN_V2 Phase 4).
+ *
+ * Response shape for GET /api/cache-stripes: per-stripe distribution counts,
+ * average stability, and a top-level health score. Loopback-only data;
+ * zero network (PREVENT-PI-004).
+ */
+export {};

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

@@ -196,6 +196,13 @@ export const ENDPOINTS = {
         path: "/api/provider-cache",
         description: "Lifetime provider prompt cache hit-rate aggregates + dollar savings estimate.",
     },
+    // ─── A3 Cache Stripes (PLAN_V2 Phase 4) ───────────────────────────
+    /** GET /api/cache-stripes — Per-stripe distribution + health score. */
+    cacheStripes: {
+        method: "GET",
+        path: "/api/cache-stripes",
+        description: "Per-stripe distribution counts, average stability scores, and composite cache health.",
+    },
     // ─── Memory Effectiveness (S53B) ───────────────────────────────────────
     /** GET /api/memory-status — Memory store aggregate statistics. */
     memoryStatus: {
@@ -215,4 +222,10 @@ export const ENDPOINTS = {
         path: "/api/setup-detect",
         description: "Best-effort detection of local embedder backends (ollama, llama.cpp, ONNX) available on the machine.",
     },
+    /** POST /api/setup-configure — Write embedder config to .mega-compact.env. */
+    setupConfigure: {
+        method: "POST",
+        path: "/api/setup-configure",
+        description: "Write the chosen embedder configuration to .mega-compact.env (loaded at next startup). Returns whether a restart is required.",
+    },
 };

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

@@ -0,0 +1 @@
+export {};

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

@@ -138,3 +138,31 @@ export function handleProviderCache(req, res, ctx) {
         return false;
     }
 }
+// ---------------------------------------------------------------------------
+// handleCacheStripes — "GET /api/cache-stripes"
+// ---------------------------------------------------------------------------
+export function handleCacheStripes(req, res, ctx) {
+    if (!req.url?.startsWith("/api/cache-stripes"))
+        return false;
+    if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "method_not_allowed" }));
+        return true;
+    }
+    try {
+        const stateDir = ctx.stateDir;
+        const pfReq = createRequire(import.meta.url);
+        const { readCacheStripes } = pfReq("../../src/store/sqlite/cache-stripes.js");
+        const result = readCacheStripes(stateDir);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result));
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            error: "cache_stripes_unavailable",
+            detail: String(e),
+        }));
+    }
+    return true;
+}

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

@@ -256,6 +256,9 @@ export function handlePerf(req, res, ctx) {
                 avg: avg(get("cache_hit_pct")),
                 latest: latest(get("cache_hit_pct")),
                 n: get("cache_hit_pct").length,
+                samples: rows
+                    .filter((r) => r.kind === "cache_hit_pct")
+                    .map((r) => ({ pct: r.value, ts: r.ts })),
             },
             db_recompute_ms: {
                 p50: pct(get("db_recompute_ms"), 50),

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

@@ -0,0 +1,50 @@
+/**
+ * routes-memory-map.ts — GET /api/memory-map route handler (S46).
+ *
+ * Builds a memory graph from the local SQLite store and returns it as JSON.
+ * Uses an inline require to the pi-agnostic src/memoryGraph.ts builder.
+ */
+import { createRequire } from "node:module";
+import { parse as parseUrl } from "node:url";
+const _req = createRequire(import.meta.url);
+// guardrails-allow PREVENT-PI-004: localhost-only dashboard API endpoint that reads from the local SQLite store — zero remote network calls.
+export function handleMemoryMap(req, res, ctx) {
+    if (req.method !== "GET")
+        return false;
+    const parsed = parseUrl(req.url ?? "", true);
+    if (parsed.pathname !== "/api/memory-map")
+        return false;
+    // guardrails-allow PREVENT-PI-004: local loopback-only dashboard server — reads the local SQLite store for graph data.
+    const { buildMemoryGraph } = _req("../../src/memoryGraph.js");
+    const sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : undefined;
+    const threshold = typeof parsed.query.threshold === "string" ? Number.parseFloat(parsed.query.threshold) : undefined;
+    const maxEdges = typeof parsed.query.maxEdgesPerNode === "string" ? Number.parseInt(parsed.query.maxEdgesPerNode, 10) : undefined;
+    const raptorEdges = parsed.query.includeRaptorEdges === "false" ? false : true;
+    const temporalEdges = parsed.query.includeTemporalEdges === "false" ? false : true;
+    const graph = buildMemoryGraph({
+        sessionId,
+        similarityThreshold: threshold,
+        maxEdgesPerNode: maxEdges,
+        stateDir: ctx.stateDir,
+        includeRaptorEdges: raptorEdges,
+        includeTemporalEdges: temporalEdges,
+    });
+    const nodes = graph.nodes.map((n) => ({
+        id: n.id,
+        sessionId: n.sessionId,
+        label: n.label,
+        summaryTruncated: n.summaryTruncated,
+        tokenEstimate: n.tokenEstimate,
+        timestamp: n.timestamp,
+        dedupStatus: n.dedupStatus,
+        raptorLevel: n.raptorLevel,
+        topicSummary: n.topicSummary,
+        decisionCount: n.decisionCount,
+        textSnippet: n.textSnippet,
+    }));
+    const edges = graph.edges;
+    const response = { nodes, edges, metadata: graph.metadata };
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(response));
+    return true;
+}

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

@@ -10,6 +10,8 @@
  */
 import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only
 import { createRequire } from "node:module";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 // ---------------------------------------------------------------------------
 // handleSetupStatus — "/api/setup-status"
 // ---------------------------------------------------------------------------
@@ -160,3 +162,106 @@ export function handleSetupDetect(req, res, _ctx) {
     res.end(JSON.stringify(body));
     return true;
 }
+// ---------------------------------------------------------------------------
+// handleSetupConfigure — POST "/api/setup-configure"
+// ---------------------------------------------------------------------------
+const OLLAMA_DEFAULT_URL = "http://localhost:11434/api/embeddings"; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+const LLAMA_DEFAULT_URL = "http://localhost:8080/v1/embeddings"; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+function readJsonBody(req, cb) {
+    let body = "";
+    let tooBig = false;
+    req.on("data", (chunk) => {
+        if (body.length > 65536) {
+            tooBig = true;
+            return;
+        }
+        body += chunk.toString();
+    });
+    req.on("end", () => {
+        if (tooBig)
+            return cb({ ok: false, error: "body_too_large" });
+        try {
+            const v = body ? JSON.parse(body) : {}; // PREVENT-001: parsed value type-checked below
+            if (typeof v !== "object" || v === null || Array.isArray(v)) {
+                return cb({ ok: false, error: "invalid_object" });
+            }
+            cb({ ok: true, value: v });
+        }
+        catch {
+            cb({ ok: false, error: "invalid_json" });
+        }
+    });
+    req.on("error", () => cb({ ok: false, error: "read_error" }));
+}
+export function handleSetupConfigure(req, res, ctx) {
+    if (req.url !== "/api/setup-configure")
+        return false;
+    if (req.method !== "POST") {
+        // 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;
+    }
+    readJsonBody(req, (parsed) => {
+        if (!parsed.ok) {
+            // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: parsed.error }));
+            return;
+        }
+        const body = parsed.value;
+        const embedder = body.embedder;
+        if (embedder !== "ollama" && embedder !== "llama" && embedder !== "trigram") {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "invalid_embedder" }));
+            return;
+        }
+        const url = body.url;
+        let resolvedUrl;
+        if (embedder === "ollama")
+            resolvedUrl = typeof url === "string" && url ? url : OLLAMA_DEFAULT_URL;
+        else if (embedder === "llama")
+            resolvedUrl = typeof url === "string" && url ? url : LLAMA_DEFAULT_URL;
+        else
+            resolvedUrl = null;
+        // Write .mega-compact.env to the state dir (loaded by env-loader at next startup).
+        const stateDir = ctx.stateDir;
+        const envPath = join(stateDir, ".mega-compact.env");
+        const lines = [
+            "# Mega-Compact Embedder Configuration",
+            `# Configured via dashboard Setup tab at ${new Date().toISOString()}`,
+        ];
+        if (resolvedUrl) {
+            lines.push(`export MEGACOMPACT_EMBEDDING_URL="${resolvedUrl}"`);
+        }
+        else {
+            lines.push("# trigram: built-in embedder, no URL needed");
+            lines.push("# unset MEGACOMPACT_EMBEDDING_URL (commented to override any shell-set value)");
+            lines.push("# export MEGACOMPACT_EMBEDDING_URL=");
+        }
+        lines.push("");
+        try {
+            mkdirSync(stateDir, { recursive: true });
+            writeFileSync(envPath, lines.join("\n"), "utf-8");
+        }
+        catch (e) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: `write_failed: ${e instanceof Error ? e.message : String(e)}` }));
+            return;
+        }
+        // Detect if the new config matches what's already active (no restart needed).
+        const currentUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
+        const alreadyActive = (resolvedUrl === null && !currentUrl) || (resolvedUrl !== null && currentUrl === resolvedUrl);
+        const resp = {
+            embedder,
+            url: resolvedUrl,
+            envPath,
+            restartRequired: !alreadyActive,
+            alreadyActive,
+        };
+        // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(resp));
+    });
+    return true;
+}

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

@@ -13,4 +13,6 @@ 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";
+export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
+export { handleMemoryMap } from "./routes-memory-map.js";
+export { handleCacheStripes } 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, handleProviderCache, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleStatic, } from "./routes.js";
+import { buildRouteContext, handleIndex, handleRepoIndex, handleEvents, handleGameState, handleGameScores, handlePerf, handleAchievements, handleSessions, handleTopics, handleTurns, handleMaintenance, handleProviderCache, handleCacheStripes, handleMemoryStatus, handleSetupStatus, handleSetupDetect, handleSetupConfigure, handleMemoryMap, 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
@@ -197,10 +197,16 @@ export async function launchDashboardServer(stateDir) {
             return;
         if (handleMemoryStatus(req, res, ctx))
             return;
+        if (handleCacheStripes(req, res, ctx))
+            return;
         if (handleSetupStatus(req, res, ctx))
             return;
         if (handleSetupDetect(req, res, ctx))
             return;
+        if (handleSetupConfigure(req, res, ctx))
+            return;
+        if (handleMemoryMap(req, res, ctx))
+            return;
         handleStatic(req, res, ctx);
     });
     // Bind base + range are env-configurable so tests can use a private,

package/dist/extensions/mega-compact.js

@@ -28,6 +28,7 @@
 import { closeVectorIndex } from "../src/store/vectorIndex.js";
 import { closeMemoryIndex } from "../src/store/memoryIndex.js";
 import { loadConfig } from "./mega-config.js";
+import { loadMegaEnv } from "./mega-runtime/env-loader.js";
 import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
 import { registerCommands } from "./mega-commands.js";
@@ -38,6 +39,10 @@ import { registerGameCommands } from "./mega-game-cmds.js";
 import { registerMetricsCommands } from "./mega-metrics-cmds.js";
 import { registerTopicsCommands } from "./mega-topics-cmds.js";
 export default function (pi) {
+    // Load .mega-compact.env (written by /mega-setup + dashboard Setup tab) BEFORE
+    // config resolution so the wizard's choices take effect. Shell env wins over
+    // the file (see env-loader.ts). Non-fatal: missing/malformed file is a no-op.
+    loadMegaEnv(loadConfig().stateDir);
     const config = loadConfig();
     // S38.9: preflight env validation — check for obviously invalid values at startup.
     // Non-fatal: log warnings and fall back to defaults.

package/dist/extensions/mega-config.js

@@ -167,7 +167,12 @@ export function loadConfig() {
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
         recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
+        messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", false),
         tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
+        ragQueryReformulation: envBool("MEGACOMPACT_QUERY_REFORMULATION", false),
+        ragTieredRouter: envBool("MEGACOMPACT_TIERED_ROUTER", false),
+        ragRecallMetrics: envBool("MEGACOMPACT_RECALL_METRICS", false),
+        ragMemoryGraph: envBool("MEGACOMPACT_MEMORY_GRAPH", false),
         // D.1: env-overridable recompact delta (minimum context growth % before
         // re-compacting instead of replaying the cached live trim). Default 50.
         recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),

package/dist/extensions/mega-events/context-handler.js

@@ -11,6 +11,7 @@ import { computeLiveTrimCut, liveTrimSummaryMessage } from "../mega-trim.js";
 import { pressureFromPct, pressureRatio, } from "../mega-config.js";
 import { appendMirrorMessages } from "./mirror-append.js";
 import { stagedForTail, withRecallTail } from "./recall-tail.js";
+import { buildSeparatedPrompt } from "./separated-prompt.js";
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(pi, runtime, config) {
     // ---- Auto-trigger: live trim (compact and continue) + native durable ----
@@ -38,9 +39,16 @@ export function registerContextHandler(pi, runtime, config) {
         // REAL transcript before any view is built, so the injected tail never
         // reaches raw_transcript (PREVENT-PI: append-only, view-only).
         const tailResult = (msgs) => {
-            if (!stagedForTail(runtime, config))
+            const base = msgs ?? messages;
+            if (!stagedForTail(runtime, config) && !config.messageSeparation)
                 return undefined;
-            return { messages: withRecallTail(msgs ?? messages, runtime, config) };
+            let result = stagedForTail(runtime, config)
+                ? withRecallTail(base, runtime, config)
+                : base;
+            if (config.messageSeparation) {
+                result = buildSeparatedPrompt(result);
+            }
+            return { messages: result };
         };
         // Always track context for the dashboard/widget, even when auto is off.
         // (v0.8 regression: !config.auto gate sat above this, leaving ctx stats

package/dist/extensions/mega-events/perf-handler.js

@@ -1,4 +1,4 @@
-import { recordPerfSample } from "../../src/store/sqlite.js";
+import { recordPerfSample, readPerfSamples, } from "../../src/store/sqlite.js";
 import { classifyPrefixBreak } from "../../src/prefix-break.js";
 /** Narrow a turn_end message to its usage block when it is an assistant msg. */
 function usageOf(msg) {
@@ -14,6 +14,9 @@ function usageOf(msg) {
  * classifyPrefixBreak with the three candidate event timestamps from the
  * runtime and records a `prefix_break` sample.  Best-effort + non-fatal.
  *
+ * Also evaluates rolling cache health and emits a degradation event when the
+ * composite score falls below 0.6 (A3, PLAN_V2 Phase 4).
+ *
  * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite write only.
  * PREVENT-002: SQL is fully parameterized via recordPerfSample.
  */
@@ -34,11 +37,90 @@ function tryRecordPrefixBreak(stateDir, prevHitPct, currHitPct, breakAt, runtime
             currHitPct,
             breakAt,
         }); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback perf instrumentation)
+        // A3: compute rolling cache health score and emit alert on degradation.
+        tryComputeCacheHealth(stateDir, currHitPct, runtime);
     }
     catch {
         /* non-fatal: prefix-break detection never blocks the agent loop */
     }
 }
+/**
+ * Compute a rolling cache health score and emit a dashboard event when it
+ * falls below the degradation threshold (0.6 / "yellow").
+ *
+ * The score is a weighted composite of:
+ *   - hitRateScore (0-1): recent cache_hit_pct sample average / 100
+ *   - stabilityScore (0-1): 1 - recent prefix_break count / maxExpectedBreaks
+ *   - churnScore (0-1): 1 - stripe re-assignment rate (derived from prefix_break classifications)
+ *
+ * Weights: hit rate 50%, prefix stability 30%, churn 20%.
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite read, no network.
+ * PREVENT-001: readPerfSamples returns empty array when no data; handled.
+ * PREVENT-011: no `any` — all arrays are typed PerfSampleRow[].
+ */
+function tryComputeCacheHealth(stateDir, currHitPct, runtime) {
+    try {
+        const now = Date.now();
+        const windowMs = 300_000; // 5-minute lookback
+        const sinceTs = now - windowMs;
+        // Read recent cache_hit_pct and prefix_break samples.
+        const hitSamples = readPerfSamples(stateDir, sinceTs, "cache_hit_pct");
+        const breakSamples = readPerfSamples(stateDir, sinceTs, "prefix_break");
+        // hitRateScore: average of recent cache hit percentages / 100.
+        let hitRateAvg = currHitPct;
+        if (hitSamples.length > 0) {
+            const sum = hitSamples.reduce((a, r) => a + r.value, 0);
+            hitRateAvg = sum / hitSamples.length;
+        }
+        const hitRateScore = Math.max(0, Math.min(1, hitRateAvg / 100));
+        // stabilityScore: penalize for frequent prefix breaks.
+        // Assume at most 2 breaks in 5min is tolerable.
+        const maxExpectedBreaks = 2;
+        const stabilityScore = Math.max(0, 1 - breakSamples.length / maxExpectedBreaks);
+        // churnScore: if recent breaks have varied causes, penalize.
+        const causeVariety = new Set(breakSamples.map((r) => {
+            const m = typeof r.meta === "string" ? JSON.parse(r.meta) : null;
+            return typeof m?.cause === "string" ? m.cause : "other";
+        }));
+        const churnPenalty = Math.min(1, causeVariety.size / 4); // 4 possible causes
+        const churnScore = 1 - churnPenalty;
+        // Composite: hitRate dominates.
+        const composite = hitRateScore * 0.5 + stabilityScore * 0.3 + churnScore * 0.2;
+        // Emit degradation event when score < 0.6.
+        if (composite < 0.6) {
+            const prevScore = runtime.rt._lastCacheHealthScore ?? 1;
+            runtime.rt._lastCacheHealthScore = composite;
+            recordPerfSample(stateDir, "cache_health", composite, {
+                hitRateScore: Math.round(hitRateScore * 1000) / 1000,
+                stabilityScore: Math.round(stabilityScore * 1000) / 1000,
+                churnScore: Math.round(churnScore * 1000) / 1000,
+                breakCount: breakSamples.length,
+                hitSampleCount: hitSamples.length,
+                currHitPct,
+                trend: composite < prevScore ? "falling" : "stable",
+            }); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback dashboard event)
+            // Structured log line for the host to pick up.
+            const level = composite < 0.4 ? "error" : "warn";
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({
+                ts: now,
+                event: `cache_health_${level}`,
+                composite: Math.round(composite * 1000) / 1000,
+                hitRateAvg: Math.round(hitRateAvg * 10) / 10,
+                breakCount: breakSamples.length,
+                trend: composite < prevScore ? "falling" : "stable",
+            }));
+        }
+        else {
+            // Still healthy — just update the stored score.
+            runtime.rt._lastCacheHealthScore = composite;
+        }
+    }
+    catch {
+        /* non-fatal: cache health computation never blocks */
+    }
+}
 /** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
 export function registerPerfHandler(pi, runtime) {
     // turn_start: record the wall-clock start of the turn. Using Date.now() (not