pi-mega-compact 0.8.17 → 0.8.18

package/extensions/dashboard-client/src/tabs/SessionsTab.tsx

@@ -0,0 +1,193 @@
+/**
+ * dashboard-client/src/tabs/SessionsTab.tsx — Sessions tab (S39).
+ *
+ * Renders: window selector (5/15/30/60 min), sessions summary tiles,
+ * the stacked-memory graph (SessionsMemoryChart), and the active sessions
+ * table (ActiveSessionsTable).
+ *
+ * Data sources: fetchSessions() + fetchSessionTimeseries(minutes). Both poll
+ * every 2s for near-real-time updates. useSSE() listens for session_sample
+ * events emitted by appendTokenSample (Step 5) so the chart refetches
+ * instantly between polls when a new token sample is appended to events.log.
+ *
+ * Empty state: shows "No active sessions." when the /api/sessions response
+ * returns an empty array (e.g. no pi processes are running yet).
+ */
+
+import type React from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useApi } from "../hooks/useApi";
+import { useSSE } from "../hooks/useSSE";
+import { fetchSessions, fetchSessionTimeseries } from "../api/client";
+import type { SseEvent, SseSessionSample, SessionsResponse, SessionTimeseriesResponse } from "@contracts";
+import { SessionsMemoryChart } from "../components/SessionsMemoryChart";
+import { ActiveSessionsTable } from "../components/ActiveSessionsTable";
+
+/**
+ * Shape of the {@link SseSessionSample} SSE event appended to events.log by
+ * `appendTokenSample` (src/store/sqlite/global-index.ts). The contract now
+ * defines this variant as part of the {@link SseEvent} union (Step 5); the
+ * local alias keeps the surface terser in this file.
+ */
+type SessionSampleEvent = SseSessionSample;
+
+/** Type guard: narrows an SSE event to a session_sample event. */
+function isSessionSample(
+	e: SseEvent,
+): e is SessionSampleEvent {
+	return e.type === "session_sample";
+}
+
+const WINDOWS: ReadonlyArray<{ value: number; label: string }> = [
+	{ value: 5, label: "5m" },
+	{ value: 15, label: "15m" },
+	{ value: 30, label: "30m" },
+	{ value: 60, label: "60m" },
+] as const;
+
+interface SummaryTilesProps {
+	sessions: SessionsResponse;
+}
+
+function SummaryTiles({ sessions }: SummaryTilesProps): React.ReactElement {
+	const active = sessions.sessions.length;
+	const combinedTokens = sessions.sessions.reduce(
+		(sum, s) => sum + (s.tokens ?? 0),
+		0,
+	);
+	const maxWindow = sessions.sessions.reduce(
+		(max, s) => Math.max(max, s.ctxWindow),
+		0,
+	);
+	const combinedPct = maxWindow > 0 ? (combinedTokens / maxWindow) * 100 : 0;
+	return (
+		<div className="sessions-summary-tiles">
+			<div className="tile">
+				<span className="tile-label">Active sessions</span>
+				<span className="tile-value">{active}</span>
+			</div>
+			<div className="tile">
+				<span className="tile-label">Combined tokens</span>
+				<span className="tile-value">
+					{combinedTokens >= 100_000
+						? `${(combinedTokens / 1000).toFixed(0)}k`
+						: combinedTokens.toLocaleString()}
+				</span>
+			</div>
+			<div className="tile">
+				<span className="tile-label">Combined % of max window</span>
+				<span className="tile-value">{Math.round(combinedPct)}%</span>
+			</div>
+			<div className="tile">
+				<span className="tile-label">Pruned (stale)</span>
+				<span className="tile-value">{sessions.pruned}</span>
+			</div>
+		</div>
+	);
+}
+
+export default function SessionsTab(): React.ReactElement {
+	const [minutes, setMinutes] = useState(30);
+
+	const {
+		data: sessionsData,
+		error: sessionsErr,
+		refetch: refetchSessions,
+	} = useApi<SessionsResponse>(
+		useCallback(() => fetchSessions(), []),
+		{ pollInterval: 2_000 },
+	);
+
+	const {
+		data: timeseriesData,
+		error: timeseriesErr,
+		refetch: refetchTimeseries,
+	} = useApi<SessionTimeseriesResponse>(
+		useCallback(() => fetchSessionTimeseries(minutes), [minutes]),
+		{ pollInterval: 2_000 },
+	);
+
+	const { events } = useSSE();
+
+	// Filter SSE events for session_sample pushes (Step 5) and trigger an
+	// immediate refetch when a new sample arrives, so the chart updates
+	// between the 2s polls. The events array grows as new samples arrive; the
+	// length-based dependency means the effect re-runs when a new sample event
+	// lands (not on every poll). We debounce via a microtask guard.
+	const sampleEvents = useMemo(
+		() => events.filter(isSessionSample),
+		[events],
+	);
+
+	const lastSampleTs = useMemo(() => {
+		if (sampleEvents.length === 0) return null;
+		return sampleEvents[sampleEvents.length - 1].ts;
+	}, [sampleEvents]);
+
+	useEffect(() => {
+		if (lastSampleTs == null) return;
+		refetchSessions();
+		refetchTimeseries();
+	}, [lastSampleTs, refetchSessions, refetchTimeseries]);
+
+	if (sessionsErr && !sessionsData) {
+		return (
+			<div className="tab-stub">
+				Error loading sessions: {sessionsErr.message}
+			</div>
+		);
+	}
+	if (timeseriesErr && !timeseriesData) {
+		return (
+			<div className="tab-stub">
+				Error loading timeseries: {timeseriesErr.message}
+			</div>
+		);
+	}
+	if (!sessionsData) {
+		return <div className="tab-stub">Loading sessions…</div>;
+	}
+
+	const sessions = sessionsData.sessions;
+	const series = timeseriesData?.series ?? [];
+	const totals = timeseriesData?.totals ?? [];
+	const windowLabel =
+		WINDOWS.find((w) => w.value === minutes)?.label ?? `${minutes}m`;
+
+	return (
+		<div className="sessions-tab">
+			<div className="sessions-toolbar">
+				<h2>Session Memory Graph</h2>
+				<div className="sessions-window-select">
+					{WINDOWS.map((w) => (
+						<button
+							key={w.value}
+							type="button"
+							className={`sessions-window-btn ${minutes === w.value ? "active" : ""}`}
+							onClick={() => setMinutes(w.value)}
+							aria-pressed={minutes === w.value}
+						>
+							{w.label}
+						</button>
+					))}
+				</div>
+			</div>
+
+			{sessions.length === 0 ? (
+				<div className="sessions-empty">No active sessions.</div>
+			) : (
+				<>
+					<SummaryTiles sessions={sessionsData} />
+					<SessionsMemoryChart series={series} totals={totals} />
+					<h2 className="section-header">Active Sessions</h2>
+					<ActiveSessionsTable sessions={sessions} series={series} />
+					<div className="sessions-footer">
+						{series.length} series · {totals.length} timestamps ·{" "}
+						{windowLabel} window · updated{" "}
+						{timeseriesData?.updatedAt ?? sessionsData.updatedAt}
+					</div>
+				</>
+			)}
+		</div>
+	);
+}

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

@@ -300,3 +300,28 @@ export interface SseCrewBanditChosen {
   /** Cumulative regret of the bandit policy (dimensionless). */
   regret: number;
 }
+
+/**
+ * SSE event appened to events.log by `appendTokenSample`
+ * (src/store/sqlite/global-index.ts) on every material snapshot. The existing
+ * `GET /api/events` SSE handler tails events.log line-by-line, so these
+ * `session_sample` lines stream to the dashboard client for free
+ * (real-time chart updates between the 2s polls in the Sessions tab).
+ *
+ * Wire shape mirrors {@link SseCompactStart} etc. with `ts` (ISO 8601 string)
+ * plus `type` (`'session_sample'`) and the per-session payload.
+ *
+ * Served via `GET /api/events` (Server-Sent Events stream).
+ */
+export interface SseSessionSample {
+  /** Discriminator. Always `'session_sample'`. */
+  type: 'session_sample';
+  /** ISO 8601 timestamp of the sample (coincides with the token_samples row `ts`). */
+  ts: string;
+  /** Session identifier the sample belongs to. */
+  sessionId: string;
+  /** Context window token count at this sample (tokens). */
+  tokens: number;
+  /** Context pressure percentage (0–100). */
+  percent: number;
+}

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-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.18",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",