pi-mega-compact 0.8.17 → 0.8.19

package/extensions/dashboard-server/api-contracts/endpoints.ts

@@ -336,6 +336,94 @@ export interface AchievementRow {
   readonly unlocked_at: number | null;
 }
 
+// ─── Sessions Memory Graph (S39) ─────────────────────────────────────────
+
+/**
+ * A single active session in the GET /api/sessions response. Represents a
+ * live pi process with its latest token usage and heartbeat.
+ */
+export interface ActiveSession {
+  /** OS process ID of the pi process. */
+  readonly pid: number;
+  /** Session identifier (normalized). */
+  readonly sessionId: string;
+  /** Absolute path to the repo root, or null if not in a git repo. */
+  readonly repoRoot: string | null;
+  /** Display name (repo basename or state dir basename). */
+  readonly displayName: string;
+  /** Model name, or null if not captured. Available from repo_registry join. */
+  readonly model: string | null;
+  /** Latest context token count, or null if no sample yet. */
+  readonly tokens: number | null;
+  /** Latest context pressure percentage (0–100), or null. */
+  readonly percent: number | null;
+  /** Context window size in tokens. */
+  readonly ctxWindow: number;
+  /** Unix timestamp (ms) of the last heartbeat. */
+  readonly lastSeen: number;
+  /** State directory of the session. */
+  readonly stateDir: string | null;
+}
+
+/**
+ * Response for GET /api/sessions. Lists active sessions with their latest
+ * token usage after pruning stale entries.
+ */
+export interface SessionsResponse {
+  /** ISO timestamp when the response was generated. */
+  readonly updatedAt: string;
+  /** Number of stale sessions pruned during this request. */
+  readonly pruned: number;
+  /** Array of active sessions, sorted by lastSeen descending. */
+  readonly sessions: ActiveSession[];
+}
+
+/** A single time-series data point for a session. */
+export interface SessionDataPoint {
+  /** Unix timestamp (ms). */
+  readonly ts: number;
+  /** Token count at this sample. */
+  readonly tokens: number;
+  /** Context pressure percentage (0–100). */
+  readonly percent: number;
+}
+
+/** A recharts-ready per-session series with a stable color. */
+export interface SessionSeries {
+  /** Session identifier. */
+  readonly sessionId: string;
+  /** Short display label for the legend. */
+  readonly label: string;
+  /** Stable hex color string (e.g. "#60a5fa"). */
+  readonly color: string;
+  /** Data points ordered by timestamp ascending. */
+  readonly data: SessionDataPoint[];
+}
+
+/**
+ * Query parameters for GET /api/sessions/timeseries. The `minutes` parameter
+ * controls the rolling window size.
+ */
+export interface SessionTimeseriesQuery {
+  /** Rolling window size in minutes (default: 30, clamped to [1, 1440]). */
+  readonly minutes?: number;
+}
+
+/**
+ * Response for GET /api/sessions/timeseries. Returns recharts-ready stacked
+ * per-session series + a totals array.
+ */
+export interface SessionTimeseriesResponse {
+  /** ISO timestamp when the response was generated. */
+  readonly updatedAt: string;
+  /** Rolling window size in minutes. */
+  readonly windowMinutes: number;
+  /** Per-session series with stable colors. */
+  readonly series: SessionSeries[];
+  /** Totals (sum of all sessions) per timestamp. */
+  readonly totals: { readonly ts: number; readonly tokens: number }[];
+}
+
 // ─── Game State Patch (PUT request body) ────────────────────────────────────
 
 /**
@@ -473,4 +561,18 @@ export const ENDPOINTS = {
     path: '/api/achievements',
     description: 'All achievement rows with unlock state.',
   } as const satisfies EndpointDef<'GET', undefined, AchievementRow[]>,
+
+  /** GET /api/sessions — Active sessions with latest token usage (S39). */
+  sessions: {
+    method: 'GET',
+    path: '/api/sessions',
+    description: 'Active pi sessions with latest token usage + heartbeat.',
+  } as const satisfies EndpointDef<'GET', undefined, SessionsResponse>,
+
+  /** GET /api/sessions/timeseries — Stacked per-session token timeseries (S39). */
+  sessionTimeseries: {
+    method: 'GET',
+    path: '/api/sessions/timeseries',
+    description: 'Recharts-ready per-session token timeseries for the stacked memory graph.',
+  } as const satisfies EndpointDef<'GET', SessionTimeseriesQuery, SessionTimeseriesResponse>,
 } as const;

package/extensions/dashboard-server/api-contracts/index.ts

@@ -26,6 +26,7 @@ export type {
   SseCrewPresenceChanged,
   SseCrewTurnChanged,
   SseCrewBanditChosen,
+  SseSessionSample,
 } from './core.js';
 
 // Snapshot / store / compression / session
@@ -103,6 +104,7 @@ import type {
   SseCrewPresenceChanged,
   SseCrewTurnChanged,
   SseCrewBanditChosen,
+  SseSessionSample,
 } from './core.js';
 
 // Endpoints registry (Sprint A1)
@@ -130,6 +132,12 @@ export type {
   GameScoresQuery,
   AchievementRow,
   GameStatePatch,
+  ActiveSession,
+  SessionsResponse,
+  SessionDataPoint,
+  SessionSeries,
+  SessionTimeseriesQuery,
+  SessionTimeseriesResponse,
   SseEndpointDef,
 } from './endpoints.js';
 
@@ -156,4 +164,5 @@ export type SseEvent =
   | SseGameRitualStage
   | SseGameRitualEnd
   | SseGameModeChanged
-  | SseGameRender;
+  | SseGameRender
+  | SseSessionSample;

package/extensions/dashboard-server/api-contracts.test.ts

@@ -158,10 +158,11 @@ void _c_perf;
 void _c_achievements;
 
 // ─── Compile-Time: ENDPOINTS path/method consistency ─────────────────────────
-// Verify the ENDPOINTS registry has exactly 13 entries with correct paths.
+// 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) as (keyof typeof ENDPOINTS)[];
-const EXPECTED_ENDPOINT_COUNT = 13;
+const EXPECTED_ENDPOINT_COUNT = 15;
 
 /** All `/api/*` paths served by server.ts (extracted from the route handlers). */
 const SERVER_TS_PATHS: string[] = [
@@ -177,12 +178,14 @@ const SERVER_TS_PATHS: string[] = [
   "/api/game-scores",
   "/api/perf",
   "/api/achievements",
+  "/api/sessions",
+  "/api/sessions/timeseries",
 ];
 
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 describe("ENDPOINTS registry", () => {
-  test("has exactly 13 endpoint entries", () => {
+  test("has exactly 15 endpoint entries", () => {
     assert.equal(
       ENDPOINT_KEYS.length,
       EXPECTED_ENDPOINT_COUNT,
@@ -803,7 +806,7 @@ describe("GET /api/achievements", () => {
 // matching its discriminator.
 
 describe("SSE /api/events — SseEvent union discriminator validation", () => {
-  /** All 20 SseEvent variants with their discriminator `type` value and a minimal payload. */
+  /** All 21 SseEvent variants with their discriminator `type` value and a minimal payload. */
   const SSE_VARIANTS: ReadonlyArray<{
     discriminator: string;
     payload: string;
@@ -996,13 +999,23 @@ describe("SSE /api/events — SseEvent union discriminator validation", () => {
         frame: "\x1b[2J\x1b[H",
       }),
     },
+    {
+      discriminator: "session_sample",
+      payload: JSON.stringify({
+        type: "session_sample",
+        ts: "2025-01-01T00:00:00Z",
+        sessionId: "sess-abc",
+        tokens: 42_000,
+        percent: 35.5,
+      }),
+    },
   ];
 
-  test("all 20 SseEvent variants have a type field matching their discriminator", () => {
+  test("all 21 SseEvent variants have a type field matching their discriminator", () => {
     assert.equal(
       SSE_VARIANTS.length,
-      20,
-      "SseEvent union should have 20 variants",
+      21,
+      "SseEvent union should have 21 variants",
     );
 
     for (const variant of SSE_VARIANTS) {

package/extensions/dashboard-server/server.ts

@@ -770,6 +770,106 @@ export async function launchDashboardServer(
 			return;
 		}
 
+		// /api/sessions — S39: active pi sessions with latest token usage + heartbeat.
+		// GET returns {updatedAt, pruned, sessions[]} after pruning stale heartbeats.
+		// The dashboard server is a detached child with no MegaRuntime ref, so it
+		// reads session_heartbeats via a require()'d sqlite helper (same pattern as
+		// /api/achievements, /api/perf). Non-GET -> 405. PREVENT-PI-004: loopback.
+		if (req.url?.startsWith("/api/sessions")) {
+			// Guard: /api/sessions/timeseries handled separately below.
+			if (req.url.startsWith("/api/sessions/timeseries")) {
+				// Fall through to the timeseries handler below.
+			} else {
+				const sReq = createRequire(import.meta.url);
+				const {
+					readActiveSessions,
+					pruneStaleSessions,
+					listRepoRegistry,
+				} = sReq(
+						"../../src/store/sqlite.js",
+					) as typeof import("../../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 pruned = pruneStaleSessions(); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+					const active = readActiveSessions();
+					const repos = listRepoRegistry();
+					const repoMap = new Map(repos.map((r) => [r.repoRoot, r]));
+					const sessions = active.map((s) => ({
+						pid: s.pid,
+						sessionId: s.sessionId,
+						repoRoot: s.repoRoot,
+						displayName: s.repoRoot
+							? (s.repoRoot.split(/[\\/]/).filter(Boolean).pop() ?? s.repoRoot)
+							: (s.stateDir?.split(/[\\/]/).filter(Boolean).pop() ?? "unknown"),
+						model: s.repoRoot ? (repoMap.get(s.repoRoot)?.modelName ?? null) : null,
+						tokens: s.tokens,
+						percent: s.percent,
+						ctxWindow: s.ctxWindow,
+						lastSeen: s.lastSeen,
+						stateDir: s.stateDir,
+					}));
+					res.writeHead(200, { "Content-Type": "application/json" });
+					res.end(
+						JSON.stringify({ updatedAt: new Date().toISOString(), pruned, sessions }),
+					);
+				} catch (e) {
+					res.writeHead(500, { "Content-Type": "application/json" });
+					res.end(
+						JSON.stringify({ error: "sessions_unavailable", detail: String(e) }),
+					);
+				}
+				return;
+			}
+		}
+
+		// /api/sessions/timeseries — S39: stacked per-session token timeseries for
+		// the recharts memory graph. GET ?minutes=N (clamped [1,1440]) returns
+		// {updatedAt, windowMinutes, series[], totals[]} in recharts-ready shape.
+		// Non-GET -> 405. PREVENT-PI-004: loopback.
+		if (req.url?.startsWith("/api/sessions/timeseries")) {
+			const tsReq = createRequire(import.meta.url);
+			const {
+				readSessionTimeseries,
+				pruneTokenSamples,
+			} = tsReq(
+					"../../src/store/sqlite.js",
+				) as typeof import("../../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(Math.max(minutes, 1), 1440);
+				const sinceTs = Date.now() - minutes * 60_000;
+				const pruneMs = Math.max(minutes * 60_000, 1_800_000);
+				pruneTokenSamples(pruneMs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+				const result = readSessionTimeseries(sinceTs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+				res.writeHead(200, { "Content-Type": "application/json" });
+				res.end(
+					JSON.stringify({
+						updatedAt: new Date().toISOString(),
+						windowMinutes: minutes,
+						series: result.series,
+						totals: result.totals,
+					}),
+				);
+			} catch (e) {
+				res.writeHead(500, { "Content-Type": "application/json" });
+				res.end(
+					JSON.stringify({ error: "timeseries_unavailable", detail: String(e) }),
+				);
+			}
+			return;
+		}
+
 		// 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 (

package/extensions/mega-events/context-handler.ts

@@ -21,7 +21,7 @@ import {
 import { epochIdFor } from "../../src/mirror/epoch.js";
 import { autoCompactCheck } from "../../src/compact.js";
 import { estimateSessionTokens } from "../../src/tokens.js";
-import { type MegaRuntime } from "../mega-runtime.js";
+import type { MegaRuntime } from "../mega-runtime.js";
 import { runCompact, piCompactWouldNoop } from "../mega-pipeline.js";
 import { computeLiveTrimCut, liveTrimSummaryMessage } from "../mega-trim.js";
 import {
@@ -42,13 +42,19 @@ function toRawTranscriptRow(
 	epochId: string,
 ): RawTranscriptRow | null {
 	// Narrow to Message union (has content + timestamp).
-	const m = msg as { role?: string; content?: unknown; timestamp?: number; toolName?: string };
+	const m = msg as {
+		role?: string;
+		content?: unknown;
+		timestamp?: number;
+		toolName?: string;
+	};
 	const content = m.content;
 	if (content == null || content === "") return null;
 	// Canonical form: sort object keys for deterministic hashing.
-	const contentBytes = typeof content === "string"
-		? content
-		: JSON.stringify(content, Object.keys(content as object).sort());
+	const contentBytes =
+		typeof content === "string"
+			? content
+			: JSON.stringify(content, Object.keys(content as object).sort());
 	const contentHash = createHash("sha256").update(contentBytes).digest("hex");
 	return {
 		contentHash,
@@ -85,21 +91,32 @@ export function registerContextHandler(
 	pi.on("context", async (event: ContextEvent, ctx: ExtensionContext) => {
 		const usage = ctx.getContextUsage();
 		const pct = usage?.percent;
+		const messages = event.messages;
 		// Always track context for the dashboard/widget, even when auto is off.
 		// (v0.8 regression: !config.auto gate sat above this, leaving ctx stats
 		// null -> widget '?% / ?/?' when auto disabled. Track first, THEN gate.)
-		runtime.lastCtxTokens = usage?.tokens ?? null;
+		// S40 fix: fall back to estimateSessionTokens(view) when the provider
+		// doesn't report tokens (e.g. plexus / claude-mythos-5 via OpenRouter).
+		// Without this, lastCtxTokens is null -> appendTokenSample (S39) never
+		// fires -> Sessions chart + Overview per-repo stack + ContextGauge all
+		// show empty/zero. Compute view lazily only when the fallback is needed
+		// (at most one engineView call per context event; when auto is on and
+		// usage.tokens is present, view is computed once below via reuse).
+		const viewForFallback =
+			usage?.tokens == null ? runtime.engineView(messages) : null;
+		const currentTokens =
+			usage?.tokens ??
+			(viewForFallback != null
+				? estimateSessionTokens(viewForFallback)
+				: null) ??
+			Math.round(((pct ?? 0) / 100) * (usage?.contextWindow ?? 0));
+		runtime.lastCtxTokens = currentTokens ?? null;
 		runtime.lastCtxPercent = pct ?? null;
 		runtime.lastCtxWindow = usage?.contextWindow ?? 0;
 		runtime.snapshot(ctx);
 		if (!config.auto) return;
 
-		const messages = event.messages;
-		const view = runtime.engineView(messages);
-		const currentTokens =
-			usage?.tokens ??
-			estimateSessionTokens(view) ??
-			Math.round(((pct ?? 0) / 100) * (usage?.contextWindow ?? 0));
+		const view = viewForFallback ?? runtime.engineView(messages);
 
 		// S27 DB-mirror: append ALL incoming messages to raw_transcript.
 		// Runs BEFORE fast-gate so every message is captured, even if we
@@ -178,7 +195,7 @@ export function registerContextHandler(
 				pct != null && runtime.trimCache.ctxPct != null
 					? pct - runtime.trimCache.ctxPct >= RECOMPACT_PCT_DELTA
 					: currentTokens - (runtime.trimCache.ctxTokens ?? 0) >=
-							runtime.effectiveThreshold * 0.5;
+						runtime.effectiveThreshold * 0.5;
 			if (!grewEnough) {
 				const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002: cached `cut` was sanitized once by computeLiveTrimCut (src/boundary.ts) and replayed verbatim; the transcript only grows within an epoch (cache is cleared on durable truncation), so the preserved run still starts on a toolPair-safe index.
 				runtime.diagLiveTrimFires++; // trim view returned this call (replay counts as a fire)
@@ -186,7 +203,9 @@ export function registerContextHandler(
 				runtime.snapshot(ctx);
 				// v0.8.7: shallow-copy the cached summary so pi's transformContext can't
 				// mutate the shared reference across replays (audit P3).
-				return { messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent] };
+				return {
+					messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
+				};
 			}
 			// else: context grew enough → fall through to re-compact (cache is stale)
 		}
@@ -195,7 +214,10 @@ export function registerContextHandler(
 		// with how close we are to the model context limit. Null-safe: when the
 		// token-fallback path ran (pct unavailable) use the token-basis pressure
 		// (the same basis the runtime `pressure` getter uses for custom/no-window).
-		const pressure = pct != null ? pressureFromPct(pct) : pressureRatio(currentTokens, runtime.effectiveThreshold);
+		const pressure =
+			pct != null
+				? pressureFromPct(pct)
+				: pressureRatio(currentTokens, runtime.effectiveThreshold);
 		const ran = runCompact(pi, runtime, config, ctx, messages, {
 			compressionPressure: pressure,
 		});
@@ -269,9 +291,9 @@ export function registerContextHandler(
 				setTimeout(() => {
 					try {
 						if (runtime.rt.sessionId !== liveSid) return; // session reset
-						const since2 =
-							Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
-						if (runtime.rt.lastNativeCompactAt !== stamp && since2 < cooldownMs) return;
+						const since2 = Date.now() - (runtime.rt.lastNativeCompactAt ?? 0);
+						if (runtime.rt.lastNativeCompactAt !== stamp && since2 < cooldownMs)
+							return;
 						if (piCompactWouldNoop(ctx)) return;
 						ctx.compact({
 							customInstructions: undefined,

package/extensions/mega-runtime/state.ts

@@ -29,6 +29,8 @@ import {
 	getCacheHitTokensSaved,
 	getGameState,
 	recordPerfSample,
+	recordSessionHeartbeat,
+	appendTokenSample,
 	type ModelSnapshot,
 	type GameState,
 } from "../../src/store/sqlite.js";
@@ -575,6 +577,35 @@ export class MegaRuntime {
 		} as DashboardSnapshot);
 		const perfDiskMs = this.dashboard.lastWriteMs;
 
+		// S39: record a session heartbeat + token sample into the shared
+		// machine-wide index.sqlite so the dashboard can show a real-time
+		// stacked-memory graph across all active pi processes. Behind the
+		// material-change gate (this code only runs when sig changed). Non-fatal
+		// try/catch mirrors the recordPerfSample pattern below. Skip the token
+		// sample when lastCtxTokens is null (no context data yet).
+		try {
+			const repo = resolveRepoRoot(ctx?.cwd ?? this.currentStateDir) ?? this.currentStateDir;
+			recordSessionHeartbeat(
+				process.pid,
+				this.rt.sessionId,
+				repo,
+				this.currentStateDir,
+				this.lastCtxWindow || 0,
+			);
+			if (this.lastCtxTokens != null) {
+				appendTokenSample(
+					this.rt.sessionId,
+					repo,
+					this.lastCtxTokens,
+					this.lastCtxPercent ?? 0,
+					this.lastCtxWindow || 0,
+					join(this.currentStateDir, "events.log"),
+				);
+			}
+		} catch {
+			/* non-fatal: S39 monitoring must never block the snapshot path */
+		}
+
 		// Live stats widget above the editor
 		if (ctx) {
 			// ── gather widget data (computed per snapshot, rendered per frame) ────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",