pi-mega-compact 0.8.7 → 0.8.10

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

@@ -1,8 +1,8 @@
 /**
  * dashboard-server/server.ts — HTTP server creation + launch + CLI entry point.
  */
-import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { createServer, } from "node:http";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync, } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
@@ -16,12 +16,14 @@ export async function launchDashboardServer(stateDir) {
     // detect a stale server (started by an older build) and replace it on
     // upgrade instead of reuse it.
     let SERVER_VERSION = "0.0.0";
+    // `here` is hoisted out of the version-detection try block so the
+    // dashboard-client dist path (Sprint B1) can reuse it without recompute.
+    const here = dirname(fileURLToPath(import.meta.url));
     try {
         // Since v0.7.9 (8821ef3) dashboard-server.js lives at
         // <pkg>/dist/extensions/dashboard-server/, so package.json is THREE levels
         // up. Keep the two- and one-level-up candidates as fallbacks for flatter
         // dev-checkout layouts. Guard each candidate so a missing file is skipped.
-        const here = dirname(fileURLToPath(import.meta.url));
         const candidates = [
             join(here, "..", "..", "..", "package.json"),
             join(here, "..", "..", "package.json"),
@@ -38,16 +40,68 @@ export async function launchDashboardServer(stateDir) {
             }
         }
     }
-    catch { /* non-fatal */ }
+    catch {
+        /* non-fatal */
+    }
     // Lazy-loaded via require so the dashboard stays cheap to boot and we don't
     // need a top-level await in the handler.
     const driftReq = createRequire(import.meta.url);
-    const detectCrossRepoDrift = (idxDir) => driftReq("../../src/driftDetection.js")
-        .detectCrossRepoDrift(idxDir);
+    const detectCrossRepoDrift = (idxDir) => driftReq("../../src/driftDetection.js").detectCrossRepoDrift(idxDir);
     const portFile = join(stateDir, "port.pid");
     const snapshotPath = join(stateDir, "dashboard.json");
     const eventsPath = join(stateDir, "events.log");
     setLogPath(join(stateDir, "dashboard.log"));
+    // ── React client build (Sprint B1) ────────────────────────────────────
+    // If the Vite-built dashboard-client bundle is present, serve it as the
+    // dashboard UI (SPA fallback for all non-/api/* routes). If absent, fall
+    // back to the legacy inline html.ts template. Candidate paths cover both
+    // the dist/ build layout and a flat dev checkout (mirrors the package.json
+    // candidate pattern above).
+    const clientDistCandidates = [
+        join(here, "..", "dashboard-client", "dist"), // dist/extensions/dashboard-client/dist
+        join(here, "..", "..", "dashboard-client", "dist"), // dist/dashboard-client/dist (flat)
+        join(here, "..", "..", "..", "extensions", "dashboard-client", "dist"), // repo-root extensions/dashboard-client/dist (dist build)
+        join(here, "..", "dashboard-client", "dist"), // dev: extensions/dashboard-server/../dashboard-client/dist
+    ];
+    const clientDist = clientDistCandidates.find((p) => existsSync(join(p, "index.html"))) ??
+        clientDistCandidates[0];
+    const clientIndexHtml = join(clientDist, "index.html");
+    const hasClientBuild = existsSync(clientIndexHtml);
+    if (hasClientBuild)
+        log("client build present", { clientDist });
+    // guardrails-allow PREVENT-PI-004: read-only static file serving from the local dashboard-client/dist bundle (loopback-only UI).
+    const serveClientAsset = (reqPath, res) => {
+        if (!hasClientBuild)
+            return false;
+        // Normalize: strip query, prevent path traversal, map "/" to index.html.
+        const clean = reqPath.split("?")[0];
+        if (clean.includes(".."))
+            return false;
+        const rel = clean === "/" || clean === "" ? "index.html" : clean.replace(/^\//, "");
+        const file = join(clientDist, rel);
+        if (!file.startsWith(clientDist) || !existsSync(file)) {
+            // SPA fallback: unknown non-asset routes serve index.html (client-side routing).
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(readFileSync(clientIndexHtml));
+            return true;
+        }
+        const ext = rel.slice(rel.lastIndexOf(".") + 1);
+        const types = {
+            html: "text/html; charset=utf-8",
+            js: "text/javascript",
+            css: "text/css",
+            json: "application/json",
+            svg: "image/svg+xml",
+            png: "image/png",
+            ico: "image/x-icon",
+            map: "application/json",
+        };
+        res.writeHead(200, {
+            "Content-Type": types[ext] ?? "application/octet-stream",
+        });
+        res.end(readFileSync(file));
+        return true;
+    };
     log("launch invoked", { stateDir });
     // ── Existing server? ───────────────────────────────────────────────────────
     // A stale port.pid pointing at a dead/competing process is the classic cause
@@ -70,7 +124,9 @@ export async function launchDashboardServer(stateDir) {
                     log("reusing live server from port.pid", { port: info.port });
                     return { port: info.port, url: `http://localhost:${info.port}` }; // guardrails-allow PREVENT-PI-004: localhost dashboard URL (loopback-only)
                 }
-                log("port.pid present but no live server — treating as stale", { port: info.port });
+                log("port.pid present but no live server — treating as stale", {
+                    port: info.port,
+                });
             }
         }
         catch {
@@ -81,7 +137,9 @@ export async function launchDashboardServer(stateDir) {
         try {
             unlinkSync(portFile);
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
     }
     // ── New server ────────────────────────────────────────────────────────────
     mkdirSync(stateDir, { recursive: true });
@@ -112,7 +170,9 @@ export async function launchDashboardServer(stateDir) {
         const prevCp = cur.checkpointCount;
         const prevBytes = cur.compressedOriginalBytes;
         const comp = snap.compression?.repo;
-        const liveSaved = comp ? comp.tokensFreed : (snap.repo.tokensSaved ?? prevSaved);
+        const liveSaved = comp
+            ? comp.tokensFreed
+            : (snap.repo.tokensSaved ?? prevSaved);
         const liveCp = snap.repo.checkpointCount ?? prevCp;
         const liveBytes = snap.integrity?.compressedOriginalBytes ?? prevBytes;
         cur.tokensSaved = liveSaved;
@@ -126,9 +186,14 @@ export async function launchDashboardServer(stateDir) {
         idx.updatedAt = snap.updatedAt ?? idx.updatedAt;
     }
     const server = createServer((req, res) => {
-        // guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard localhost server (loopback-only) — CORS open for local browser access
-        // CORS for local access
-        res.setHeader("Access-Control-Allow-Origin", "*");
+        // guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard localhost server (loopback-only) — CORS restricted to same-origin localhost browsers.
+        // CORS for local access — restricted to loopback origins (the dashboard server only binds to localhost).
+        const origin = req.headers.origin;
+        if (typeof origin === "string" &&
+            /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Vary", "Origin");
+        }
         res.setHeader("Access-Control-Allow-Methods", "GET, PUT, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type");
         if (req.method === "OPTIONS") {
@@ -137,6 +202,10 @@ export async function launchDashboardServer(stateDir) {
             return;
         }
         if (req.url === "/" || req.url === "/index.html") {
+            // Sprint B1: prefer the React client build when present; fall back to the
+            // legacy inline html.ts template when the client dist is absent.
+            if (serveClientAsset("/", res))
+                return;
             const tier = readSnapshot(snapshotPath).tier;
             res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
             res.end(dashboardHtml(tier));
@@ -184,7 +253,11 @@ export async function launchDashboardServer(stateDir) {
                 }
             }
             res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ updatedAt: idx?.updatedAt ?? null, repos, count: repos.length }));
+            res.end(JSON.stringify({
+                updatedAt: idx?.updatedAt ?? null,
+                repos,
+                count: repos.length,
+            }));
             return;
         }
         // /api/summary — header tiles without the full repo list (keeps payload
@@ -219,14 +292,26 @@ export async function launchDashboardServer(stateDir) {
             try {
                 const idx = readIndex();
                 const nowSec = Math.floor(Date.now() / 1000);
-                const servers = (idx?.repos ?? []).filter((r) => (r.lastSeen ?? 0) >= nowSec - ACTIVE_WINDOW_SEC).map((r) => {
-                    const out = { repoRoot: r.repoRoot, displayName: r.displayName, model: r.modelName, provider: r.providerName, lastSeen: r.lastSeen, lastCompactedAt: r.lastCompactedAt };
+                const servers = (idx?.repos ?? [])
+                    .filter((r) => (r.lastSeen ?? 0) >= nowSec - ACTIVE_WINDOW_SEC)
+                    .map((r) => {
+                    const out = {
+                        repoRoot: r.repoRoot,
+                        displayName: r.displayName,
+                        model: r.modelName,
+                        provider: r.providerName,
+                        lastSeen: r.lastSeen,
+                        lastCompactedAt: r.lastCompactedAt,
+                    };
                     try {
                         const p = join(r.stateDir, "dashboard.json");
                         if (existsSync(p)) {
                             const snap = JSON.parse(readFileSync(p, "utf-8"));
                             out.tier = snap.tier ?? null;
-                            out.contextPct = (snap.context && snap.context.percent != null) ? snap.context.percent : null;
+                            out.contextPct =
+                                snap.context && snap.context.percent != null
+                                    ? snap.context.percent
+                                    : null;
                             out.state = (snap.session && snap.session.state) || null;
                             out.cacheHits = snap.cacheHits ?? null;
                             out.compacts = snap.compacts ?? null;
@@ -234,9 +319,12 @@ export async function launchDashboardServer(stateDir) {
                             out.updatedAt = snap.updatedAt ?? null;
                         }
                     }
-                    catch { /* best-effort */ }
+                    catch {
+                        /* best-effort */
+                    }
                     return out;
-                }).sort((a, b) => b.lastSeen - a.lastSeen);
+                })
+                    .sort((a, b) => b.lastSeen - a.lastSeen);
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({ updatedAt: new Date().toISOString(), servers }));
             }
@@ -250,7 +338,7 @@ export async function launchDashboardServer(stateDir) {
             res.writeHead(200, {
                 "Content-Type": "text/event-stream",
                 "Cache-Control": "no-cache",
-                "Connection": "keep-alive",
+                Connection: "keep-alive",
             });
             // Drain existing events so the client starts with history
             const { data: existing, offset: initialOffset } = readFrom(eventsPath, 0);
@@ -282,7 +370,9 @@ export async function launchDashboardServer(stateDir) {
                 try {
                     watcher = watch(eventsPath, onWatch);
                 }
-                catch { /* give up */ }
+                catch {
+                    /* give up */
+                }
             }
             if (existsSync(eventsPath)) {
                 startFileWatch();
@@ -325,7 +415,10 @@ export async function launchDashboardServer(stateDir) {
                 }
                 catch (e) {
                     res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "game_state_unavailable", detail: String(e) }));
+                    res.end(JSON.stringify({
+                        error: "game_state_unavailable",
+                        detail: String(e),
+                    }));
                 }
                 return;
             }
@@ -335,6 +428,7 @@ export async function launchDashboardServer(stateDir) {
                 let body = "";
                 let tooBig = false;
                 req.on("data", (chunk) => {
+                    // guardrails-allow PREVENT-PI-004: loopback dashboard request body (local)
                     if (body.length > 65536) {
                         tooBig = true;
                         return;
@@ -359,7 +453,9 @@ export async function launchDashboardServer(stateDir) {
                     // Reject valid-but-non-object JSON (null/[]/42) — dereferencing
                     // patch.game_mode_on would throw an unhandled TypeError inside this
                     // 'end' listener and crash the detached server (audit P1: loopback DoS).
-                    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+                    if (typeof patch !== "object" ||
+                        patch === null ||
+                        Array.isArray(patch)) {
                         res.writeHead(400, { "Content-Type": "application/json" });
                         res.end(JSON.stringify({ error: "invalid_patch_object" }));
                         return;
@@ -380,7 +476,8 @@ export async function launchDashboardServer(stateDir) {
                             clean.theme = patch.theme;
                     }
                     if (patch.tui_display_mode != null) {
-                        if (patch.tui_display_mode !== "full" && patch.tui_display_mode !== "minimal")
+                        if (patch.tui_display_mode !== "full" &&
+                            patch.tui_display_mode !== "minimal")
                             bad = true;
                         else
                             clean.tui_display_mode = patch.tui_display_mode;
@@ -397,7 +494,10 @@ export async function launchDashboardServer(stateDir) {
                     }
                     catch (e) {
                         res.writeHead(500, { "Content-Type": "application/json" });
-                        res.end(JSON.stringify({ error: "game_state_write_failed", detail: String(e) }));
+                        res.end(JSON.stringify({
+                            error: "game_state_write_failed",
+                            detail: String(e),
+                        }));
                     }
                 });
                 return;
@@ -440,7 +540,128 @@ export async function launchDashboardServer(stateDir) {
             }
             catch (e) {
                 res.writeHead(500, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: "game_scores_unavailable", detail: String(e) }));
+                res.end(JSON.stringify({
+                    error: "game_scores_unavailable",
+                    detail: String(e),
+                }));
+            }
+            return;
+        }
+        // /api/perf — v0.8.8 Perf dashboard tab. GET returns rolling-window
+        // aggregates over perf_samples: per-kind p50/p95 (turn/provider latency,
+        // tps avg, db recompute, disk write), latest rss/heap, cpu user/sys delta,
+        // cache hit %, plus the diag recompute/skip/replay counts (read from
+        // dashboard.json snapshot if available). The dashboard server is a detached
+        // child with no MegaRuntime ref, so it reads perf_samples via a require()'d
+        // sqlite helper (same pattern as /api/game-scores). Unknown/invalid params
+        // are clamped (never throw). Non-GET -> 405. PREVENT-PI-004: loopback.
+        if (req.url?.startsWith("/api/perf")) {
+            const pfReq = createRequire(import.meta.url);
+            const { readPerfSamples } = pfReq("../../src/store/sqlite.js");
+            if (req.method !== "GET") {
+                res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+                res.end(JSON.stringify({ error: "method_not_allowed" }));
+                return;
+            }
+            try {
+                const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
+                let minutes = Number(url.searchParams.get("minutes") ?? "30");
+                if (!Number.isFinite(minutes) || minutes <= 0)
+                    minutes = 30;
+                minutes = Math.min(minutes, 1440); // cap at 24h
+                const sinceTs = Date.now() - minutes * 60_000;
+                const rows = readPerfSamples(stateDir, sinceTs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+                const byKind = new Map();
+                for (const r of rows) {
+                    let arr = byKind.get(r.kind);
+                    if (!arr) {
+                        arr = [];
+                        byKind.set(r.kind, arr);
+                    }
+                    arr.push(r.value);
+                }
+                // Nearest-rank percentile (ceil(p/100*n)-1, clamped). Code-controlled,
+                // never user input (PREVENT-002 safe).
+                function pct(arr, p) {
+                    if (!arr.length)
+                        return 0;
+                    const s = [...arr].sort((a, b) => a - b);
+                    const idx = Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1));
+                    return s[idx];
+                }
+                function avg(arr) {
+                    if (!arr.length)
+                        return 0;
+                    return arr.reduce((a, b) => a + b, 0) / arr.length;
+                }
+                // rows are ASC by ts, so the last pushed value is the most recent.
+                function latest(arr) {
+                    return arr.length ? arr[arr.length - 1] : 0;
+                }
+                const get = (k) => byKind.get(k) ?? [];
+                // diag counters live in the runtime-written dashboard.json (the server is
+                // a detached child with no MegaRuntime ref). Read defensively — absent
+                // until the first snapshot() write (PREVENT-001: assign before access).
+                let diag = null;
+                try {
+                    const raw = readFileSync(snapshotPath, "utf-8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === "object" && parsed.diag)
+                        diag = parsed.diag;
+                }
+                catch {
+                    /* dashboard.json not written yet */
+                }
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    updatedAt: new Date().toISOString(),
+                    windowMinutes: minutes,
+                    sampleCount: rows.length,
+                    turn_latency_ms: {
+                        p50: pct(get("turn_latency_ms"), 50),
+                        p95: pct(get("turn_latency_ms"), 95),
+                        n: get("turn_latency_ms").length,
+                    },
+                    provider_latency_ms: {
+                        p50: pct(get("provider_latency_ms"), 50),
+                        p95: pct(get("provider_latency_ms"), 95),
+                        n: get("provider_latency_ms").length,
+                    },
+                    tps: { avg: avg(get("tps")), n: get("tps").length },
+                    cache_hit_pct: {
+                        avg: avg(get("cache_hit_pct")),
+                        latest: latest(get("cache_hit_pct")),
+                        n: get("cache_hit_pct").length,
+                    },
+                    db_recompute_ms: {
+                        p50: pct(get("db_recompute_ms"), 50),
+                        p95: pct(get("db_recompute_ms"), 95),
+                        n: get("db_recompute_ms").length,
+                    },
+                    disk_write_ms: {
+                        p50: pct(get("disk_write_ms"), 50),
+                        p95: pct(get("disk_write_ms"), 95),
+                        n: get("disk_write_ms").length,
+                    },
+                    rss_mb: { latest: latest(get("rss_mb")), n: get("rss_mb").length },
+                    heap_mb: {
+                        latest: latest(get("heap_mb")),
+                        n: get("heap_mb").length,
+                    },
+                    cpu_user_ms: {
+                        latest: latest(get("cpu_user_ms")),
+                        n: get("cpu_user_ms").length,
+                    },
+                    cpu_sys_ms: {
+                        latest: latest(get("cpu_sys_ms")),
+                        n: get("cpu_sys_ms").length,
+                    },
+                    diag,
+                }));
+            }
+            catch (e) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "perf_unavailable", detail: String(e) }));
             }
             return;
         }
@@ -463,11 +684,21 @@ export async function launchDashboardServer(stateDir) {
             }
             catch (e) {
                 res.writeHead(500, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: "achievements_unavailable", detail: String(e) }));
+                res.end(JSON.stringify({
+                    error: "achievements_unavailable",
+                    detail: String(e),
+                }));
             }
             return;
         }
-        // Fallback — serve the dashboard
+        // Fallback — serve the React client build (SPA route) or legacy dashboard.
+        // Non-/api/* GETs hit here: serve client assets if built, else inline HTML.
+        if (req.method === "GET" &&
+            req.url &&
+            !req.url.startsWith("/api/") &&
+            serveClientAsset(req.url, res)) {
+            return;
+        }
         const tier = readSnapshot(snapshotPath).tier;
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
         res.end(dashboardHtml(tier));
@@ -505,7 +736,11 @@ export async function launchDashboardServer(stateDir) {
                 const v4Handler = server.listeners("request")[0];
                 if (v4Handler) {
                     v6 = createServer((r, s) => v4Handler.call(server, r, s));
-                    v6.on("error", (e) => log("ipv6 loopback bind skipped", { port, code: e.code, message: e.message }));
+                    v6.on("error", (e) => log("ipv6 loopback bind skipped", {
+                        port,
+                        code: e.code,
+                        message: e.message,
+                    }));
                     v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the localhost dashboard server
                 }
                 // Write port.pid
@@ -520,12 +755,16 @@ export async function launchDashboardServer(stateDir) {
                     try {
                         unlinkSync(portFile);
                     }
-                    catch { /* already gone */ }
+                    catch {
+                        /* already gone */
+                    }
                     server.close();
                     try {
                         v6?.close();
                     }
-                    catch { /* not bound */ }
+                    catch {
+                        /* not bound */
+                    }
                     process.exit(0);
                 };
                 process.on("SIGTERM", cleanup);

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

@@ -0,0 +1,8 @@
+export function setupTailscaleServe(port = 3000, httpsPort = 443) {
+    // Tailscale serve: exposes localhost dashboard securely.
+    // Only activates when TAILSCALE_ENABLED=1 is set.
+    if (process.env.TAILSCALE_ENABLED !== "1")
+        return false;
+    console.log(`[tailscale] Serve enabled on port ${port} (https:${httpsPort})`);
+    return true;
+}

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

@@ -1,5 +1,9 @@
 /**
  * dashboard-server/types.ts — shared types for the dashboard server.
+ *
+ * Re-exports shared shapes from `api-contracts/` where they overlap with
+ * the legacy local types, while preserving 100% backward compatibility for
+ * all existing consumers (server.ts, index-reader.ts, snapshot.ts).
  */
 // Active-window cutoff (seconds) for the /api/servers endpoint.
 export const ACTIVE_WINDOW_SEC = 1800;

package/dist/extensions/mega-dashboard.js

@@ -23,9 +23,18 @@ export class Dashboard {
         this.snapshotPath = join(stateDir, "dashboard.json");
         this.eventsPath = join(stateDir, "events.log");
     }
+    /** v0.8.8: duration (ms) of the last dashboard.json write — read by
+     *  MegaRuntime.snapshot() to record a `disk_write_ms` perf sample without
+     *  wrapping the giant snapshot object literal at the call site. */
+    _lastWriteMs = 0;
+    get lastWriteMs() {
+        return this._lastWriteMs;
+    }
     /** Write a full state snapshot (atomically replaces previous). */
     snapshot(data) {
+        const t = performance.now();
         writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
+        this._lastWriteMs = performance.now() - t;
     }
     /** Append a timestamped JSONL event line. */
     event(type, data) {

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

@@ -0,0 +1,71 @@
+import { recordPerfSample } from "../../src/store/sqlite.js";
+/** Narrow a turn_end message to its usage block when it is an assistant msg. */
+function usageOf(msg) {
+    if (msg.role !== "assistant" || !msg.usage)
+        return null;
+    return msg.usage;
+}
+/** 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
+    // event.timestamp) so the turn_end duration is on ONE clock — mixing pi's
+    // timestamp with Date.now() would skew the delta. Also (re)arms the cpu/mem
+    // interval so a new session after a dispose() resumes sampling on its first
+    // turn (the interval is cleared in runtime.dispose()).
+    pi.on("turn_start", async () => {
+        try {
+            runtime.perfTurnStart = Date.now();
+            runtime.ensurePerfInterval();
+        }
+        catch {
+            /* non-fatal */
+        }
+    });
+    // turn_end: compute turn latency + TPS + cache hit % from the assistant
+    // message's usage block. One perf_samples row per metric per turn.
+    pi.on("turn_end", async (event) => {
+        try {
+            if (runtime.perfTurnStart > 0) {
+                const durMs = Date.now() - runtime.perfTurnStart;
+                recordPerfSample(runtime.currentStateDir, "turn_latency_ms", durMs, {
+                    turnIndex: event.turnIndex,
+                });
+                const u = usageOf(event.message);
+                if (u) {
+                    const durSec = Math.max(durMs / 1000, 0.001);
+                    recordPerfSample(runtime.currentStateDir, "tps", u.output / durSec, { outputTokens: u.output });
+                    const denom = u.cacheRead + u.input + u.cacheWrite;
+                    const hitPct = denom > 0 ? (u.cacheRead / denom) * 100 : 0;
+                    recordPerfSample(runtime.currentStateDir, "cache_hit_pct", hitPct, { input: u.input, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite });
+                }
+            }
+        }
+        catch {
+            /* non-fatal: instrumentation must never break the agent loop */
+        }
+    });
+    // before_provider_request -> after_provider_response: raw round-trip latency
+    // to the model endpoint (HTTP status carried on the response event).
+    pi.on("before_provider_request", async () => {
+        try {
+            runtime.perfProviderStart = Date.now();
+        }
+        catch {
+            /* non-fatal */
+        }
+    });
+    pi.on("after_provider_response", async (event) => {
+        try {
+            if (runtime.perfProviderStart > 0) {
+                const lat = Date.now() - runtime.perfProviderStart;
+                recordPerfSample(runtime.currentStateDir, "provider_latency_ms", lat, { status: event.status });
+            }
+        }
+        catch {
+            /* non-fatal */
+        }
+    });
+    // Start the 5s cpu/mem sampling interval (one per MegaRuntime; cleared in
+    // runtime.dispose()). Idempotent — safe to call again after a dispose().
+    runtime.ensurePerfInterval();
+}

package/dist/extensions/mega-events/register.js

@@ -2,6 +2,7 @@ import { registerSessionHandlers } from "./session-handlers.js";
 import { registerAgentHandlers } from "./agent-handlers.js";
 import { registerContextHandler } from "./context-handler.js";
 import { registerCompactHandlers } from "./compact-handlers.js";
+import { registerPerfHandler } from "./perf-handler.js";
 /**
  * DIAG accessor for the headless test harness: the most recently constructed
  * MegaRuntime, so a test that loads the compiled extension via its default
@@ -18,4 +19,5 @@ export function registerEventHandlers(pi, runtime, config) {
     registerAgentHandlers(pi, runtime, config);
     registerContextHandler(pi, runtime, config);
     registerCompactHandlers(pi, runtime, config);
+    registerPerfHandler(pi, runtime);
 }

package/dist/extensions/mega-events.js

@@ -15,3 +15,4 @@ export * from "./mega-events/session-handlers.js";
 export * from "./mega-events/agent-handlers.js";
 export * from "./mega-events/context-handler.js";
 export * from "./mega-events/compact-handlers.js";
+export * from "./mega-events/perf-handler.js";