pi-mega-compact 0.8.8 → 0.8.10

package/extensions/dashboard-client/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pi-mega-compact-dashboard-client",
+  "version": "0.8.9",
+  "private": true,
+  "type": "module",
+  "description": "React + Vite frontend for the pi-mega-compact dashboard server (Sprint B1 scaffold).",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11"
+  },
+  "allowScripts": {
+    "esbuild@0.21.5": true
+  }
+}

package/extensions/dashboard-client/src/App.tsx

@@ -0,0 +1,82 @@
+/**
+ * dashboard-client/src/App.tsx — Dashboard shell layout.
+ *
+ * SPRINT-B1: React scaffold with tab routing, header, error boundary.
+ * SPRINT-C1+: tabs wired progressively with real content.
+ */
+
+import React, { useState, useCallback } from "react";
+import { ErrorBoundary } from "./components/ErrorBoundary";
+import { TabBar } from "./components/TabBar";
+import { LoadingSpinner } from "./components/LoadingSpinner";
+import { useApi } from "./hooks/useApi";
+import { fetchSnapshot } from "./api/client";
+import type { SnapshotResponse } from "@contracts";
+
+// Tab components — lazy-loaded. C1 fills Overview + Events; C2/C3 fill the rest.
+const OverviewTab = React.lazy(() => import("./tabs/OverviewTab"));
+const ReposTab = React.lazy(() => import("./tabs/ReposTab"));
+const EventsTab = React.lazy(() => import("./tabs/EventsTab"));
+const ConfigTab = React.lazy(() => import("./tabs/ConfigTab"));
+const MetricsTab = React.lazy(() => import("./tabs/MetricsTab"));
+
+// SPRINT-C2/C3-REMAINING: GameTab, DiagnosticsPanel lazy imports.
+
+export type TabId = "overview" | "repos" | "events" | "config" | "metrics";
+
+const TABS: Array<{ id: TabId; label: string }> = [
+	{ id: "overview", label: "Overview" },
+	{ id: "repos", label: "Repos" },
+	{ id: "events", label: "Events" },
+	{ id: "config", label: "Config" },
+	{ id: "metrics", label: "Metrics" },
+];
+
+export default function App(): React.ReactElement {
+	const [activeTab, setActiveTab] = useState<TabId>("overview");
+	const {
+		data: snapshot,
+		loading,
+		error,
+	} = useApi<SnapshotResponse>(
+		useCallback(() => fetchSnapshot(), []),
+		{
+			// Poll every 5s so Overview stays live without SSE. D1 will add retry/stale.
+			pollInterval: 5000,
+		},
+	);
+
+	const tier = snapshot?.tier ?? "unknown";
+	const version = snapshot?.model?.name ?? "";
+
+	return (
+		<ErrorBoundary>
+			<div className="dashboard-app">
+				<header className="dashboard-header">
+					<h1>
+						mega-compact dashboard
+						<span className="tier">{tier}</span>
+						{version && <span className="version-pill">{version}</span>}
+					</h1>
+				</header>
+				<TabBar tabs={TABS} active={activeTab} onTabChange={setActiveTab} />
+				<main className="dashboard-content">
+					<React.Suspense fallback={<LoadingSpinner />}>
+						{activeTab === "overview" && (
+							<OverviewTab
+								snapshot={snapshot}
+								loading={loading}
+								error={error}
+							/>
+						)}
+						{activeTab === "repos" && <ReposTab />}
+						{activeTab === "events" && <EventsTab />}
+						{activeTab === "config" && <ConfigTab />}
+						{activeTab === "metrics" && <MetricsTab />}
+						{/* SPRINT-C2/C3-REMAINING: Game tab, diagnostics panel */}
+					</React.Suspense>
+				</main>
+			</div>
+		</ErrorBoundary>
+	);
+}

package/extensions/dashboard-client/src/api/client.ts

@@ -0,0 +1,145 @@
+/**
+ * dashboard-client/src/api/client.ts — typed fetch wrappers using A1 contracts.
+ *
+ * PREVENT-PI-004: every request targets a relative path (loopback-only —
+ * the dashboard server is the same origin that serves this static bundle).
+ * No absolute URLs, no external hosts.
+ *
+ * Uses the ENDPOINTS registry from A1 as the single source of truth for
+ * paths + methods. Response types come from the api-contracts domain modules.
+ */
+
+import { ENDPOINTS } from "@contracts";
+import type {
+	SnapshotResponse,
+	VersionResponse,
+	IndexesSummaryResponse,
+	IndexFallbackResponse,
+	ReposResponse,
+	SummaryResponse,
+	DriftReportResponse,
+	ServersResponse,
+	GameStateResponse,
+	GameStatePatch,
+	GameScoreRow,
+	GameScoresQuery,
+	PerfResponse,
+	PerfQuery,
+	AchievementRow,
+} from "@contracts";
+
+/** Error thrown when a dashboard API response is not 2xx. */
+export class ApiError extends Error {
+	readonly status: number;
+	constructor(status: number, message: string) {
+		super(`dashboard API ${status}: ${message}`);
+		this.name = "ApiError";
+		this.status = status;
+	}
+}
+
+/** Internal: typed GET that throws ApiError on non-2xx. */
+async function getJson<T>(path: string): Promise<T> {
+	// guardrails-allow PREVENT-PI-004: relative-path fetch to same-origin dashboard server (loopback-only, static bundle served by the same Node HTTP server).
+	const res = await fetch(path);
+	if (!res.ok) {
+		throw new ApiError(
+			res.status,
+			await res.text().catch(() => res.statusText),
+		);
+	}
+	return res.json() as Promise<T>;
+}
+
+/** Internal: typed PUT that throws ApiError on non-2xx. */
+async function putJson<T>(path: string, body: unknown): Promise<T> {
+	// guardrails-allow PREVENT-PI-004: relative-path fetch to same-origin dashboard server (loopback-only).
+	const res = await fetch(path, {
+		method: "PUT",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	});
+	if (!res.ok) {
+		throw new ApiError(
+			res.status,
+			await res.text().catch(() => res.statusText),
+		);
+	}
+	return res.json() as Promise<T>;
+}
+
+/** Build a query string from a record, skipping undefined/null values. */
+function query(
+	params: Record<string, string | number | undefined | null>,
+): string {
+	const sp = new URLSearchParams();
+	for (const [k, v] of Object.entries(params)) {
+		if (v !== undefined && v !== null) sp.set(k, String(v));
+	}
+	const qs = sp.toString();
+	return qs ? `?${qs}` : "";
+}
+
+// ─── Endpoint wrappers ──────────────────────────────────────────────────────
+
+export function fetchSnapshot(): Promise<SnapshotResponse> {
+	return getJson<SnapshotResponse>(ENDPOINTS.snapshot.path);
+}
+
+export function fetchVersion(): Promise<VersionResponse> {
+	return getJson<VersionResponse>(ENDPOINTS.version.path);
+}
+
+export function fetchIndex(): Promise<
+	IndexesSummaryResponse | IndexFallbackResponse
+> {
+	return getJson<IndexesSummaryResponse | IndexFallbackResponse>(
+		ENDPOINTS.index.path,
+	);
+}
+
+export function fetchRepos(activeHours?: number): Promise<ReposResponse> {
+	return getJson<ReposResponse>(
+		`${ENDPOINTS.repos.path}${query({ active: activeHours ? `${activeHours}h` : undefined })}`,
+	);
+}
+
+export function fetchSummary(): Promise<SummaryResponse> {
+	return getJson<SummaryResponse>(ENDPOINTS.summary.path);
+}
+
+export function fetchDrift(): Promise<DriftReportResponse> {
+	return getJson<DriftReportResponse>(ENDPOINTS.drift.path);
+}
+
+export function fetchServers(): Promise<ServersResponse> {
+	return getJson<ServersResponse>(ENDPOINTS.servers.path);
+}
+
+export function fetchGameState(): Promise<GameStateResponse> {
+	return getJson<GameStateResponse>(ENDPOINTS.getGameState.path);
+}
+
+export function putGameState(
+	patch: GameStatePatch,
+): Promise<GameStateResponse> {
+	return putJson<GameStateResponse>(ENDPOINTS.putGameState.path, patch);
+}
+
+export function fetchGameScores(
+	params: GameScoresQuery = {},
+): Promise<GameScoreRow[]> {
+	return getJson<GameScoreRow[]>(
+		`${ENDPOINTS.gameScores.path}${query({ metric: params.metric, limit: params.limit })}`,
+	);
+}
+
+export function fetchPerf(params: PerfQuery = {}): Promise<PerfResponse> {
+	return getJson<PerfResponse>(
+		`${ENDPOINTS.perf.path}${query({ minutes: params.minutes })}`,
+	);
+}
+
+export function fetchAchievements(): Promise<AchievementRow[]> {
+	return getJson<AchievementRow[]>(ENDPOINTS.achievements.path);
+}

package/extensions/dashboard-client/src/components/CacheStatusPerModel.tsx

@@ -0,0 +1,44 @@
+import type React from "react";
+export interface CacheRow {
+	model: string;
+	provider: string;
+	hits: number;
+	total: number;
+	saved: string;
+	pct: number;
+	compactions: number;
+}
+export function CacheStatusPerModel({
+	rows,
+}: {
+	rows: CacheRow[];
+}): React.ReactElement {
+	return (
+		<div className="cache-per-model">
+			<table>
+				<thead>
+					<tr>
+						<th>Model</th>
+						<th>Provider</th>
+						<th>Hits</th>
+						<th>Saved</th>
+						<th>Pct</th>
+						<th>Comp</th>
+					</tr>
+				</thead>
+				<tbody>
+					{rows.map((r) => (
+						<tr key={r.model}>
+							<td>{r.model}</td>
+							<td>{r.provider}</td>
+							<td>{r.hits}</td>
+							<td>{r.saved}</td>
+							<td>{r.pct}%</td>
+							<td>{r.compactions}</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}

package/extensions/dashboard-client/src/components/CompressionCard.tsx

@@ -0,0 +1,61 @@
+/**
+ * dashboard-client/src/components/CompressionCard.tsx — compression stats.
+ *
+ * Stat grid: tokens in → out, freed amount highlighted, compression %,
+ * dedup contribution %. Consumes snapshot.compression.repo.
+ */
+
+import type React from "react";
+
+export interface CompressionCardProps {
+	/** Repo-level compression stats (tokens in/out/freed + percentages). */
+	tokensIn: number;
+	tokensOut: number;
+	tokensFreed: number;
+	/** Compression ratio (percent, 0–100). */
+	compressionPct: number;
+	/** Dedup contribution (percent, 0–100). */
+	dedupPct: number;
+}
+
+function fmt(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+export function CompressionCard({
+	tokensIn,
+	tokensOut,
+	tokensFreed,
+	compressionPct,
+	dedupPct,
+}: CompressionCardProps): React.ReactElement {
+	return (
+		<div className="card compression-card">
+			<h3>Compression (repo)</h3>
+			<div className="stat-grid">
+				<div className="stat">
+					<span className="stat-label">In</span>
+					<span className="stat-value">{fmt(tokensIn)}</span>
+				</div>
+				<div className="stat">
+					<span className="stat-label">Out</span>
+					<span className="stat-value">{fmt(tokensOut)}</span>
+				</div>
+				<div className="stat stat-highlight">
+					<span className="stat-label">Freed</span>
+					<span className="stat-value">{fmt(tokensFreed)}</span>
+				</div>
+				<div className="stat">
+					<span className="stat-label">Ratio</span>
+					<span className="stat-value">{compressionPct.toFixed(1)}%</span>
+				</div>
+				<div className="stat">
+					<span className="stat-label">Dedup</span>
+					<span className="stat-value">{dedupPct.toFixed(1)}%</span>
+				</div>
+			</div>
+		</div>
+	);
+}

package/extensions/dashboard-client/src/components/ContextGauge.tsx

@@ -0,0 +1,59 @@
+/**
+ * dashboard-client/src/components/ContextGauge.tsx — token usage meter.
+ *
+ * Color-coded percent fill bar: green <60%, yellow 60–80%, red >80%.
+ * Sublabel: "{tokens} / {contextWindow} tokens ({percent}%)".
+ */
+
+import type React from "react";
+
+export interface ContextGaugeProps {
+	/** Current token count in the context window, or null if unknown. */
+	tokens: number | null;
+	/** Context window usage percent (0–100), or null if unknown. */
+	percent: number | null;
+	/** Maximum context window size for the active model. */
+	contextWindow: number;
+}
+
+function severityClass(percent: number): string {
+	if (percent >= 80) return "gauge-red";
+	if (percent >= 60) return "gauge-yellow";
+	return "gauge-green";
+}
+
+function formatTokens(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+export function ContextGauge({
+	tokens,
+	percent,
+	contextWindow,
+}: ContextGaugeProps): React.ReactElement {
+	const pct = percent ?? 0;
+	const fillWidth = Math.max(0, Math.min(100, pct));
+	const cls = severityClass(pct);
+	const label =
+		tokens !== null && tokens !== undefined
+			? `${formatTokens(tokens)} / ${formatTokens(contextWindow)} tokens (${pct.toFixed(1)}%)`
+			: `${formatTokens(contextWindow)} window (usage unknown)`;
+
+	return (
+		<div className="card context-gauge">
+			<h3>Context</h3>
+			<div
+				className={`gauge-bar ${cls}`}
+				role="meter"
+				aria-valuenow={pct}
+				aria-valuemin={0}
+				aria-valuemax={100}
+			>
+				<div className="gauge-fill" style={{ width: `${fillWidth}%` }} />
+			</div>
+			<p className="gauge-label">{label}</p>
+		</div>
+	);
+}

package/extensions/dashboard-client/src/components/DataSafetyCard.tsx

@@ -0,0 +1,49 @@
+/**
+ * dashboard-client/src/components/DataSafetyCard.tsx — Data Safety / Shield.
+ *
+ * Shows regions retained, compressed-original size, storage dedup %,
+ * and permanently deleted count. Read-only (no mutations).
+ */
+import type React from "react";
+
+export interface DataSafetyCardProps {
+	regionsRetained: number;
+	compressedOriginalKiB: number;
+	storageDedupPct: number;
+	permanentlyDeleted: number;
+}
+
+export function DataSafetyCard({
+	regionsRetained,
+	compressedOriginalKiB,
+	storageDedupPct,
+	permanentlyDeleted,
+}: DataSafetyCardProps): React.ReactElement {
+	return (
+		<div className="data-safety-card">
+			<h4>Data Safety</h4>
+			<div className="safety-grid">
+				<div className="safety-row">
+					<span className="label">Regions Retained</span>
+					<span className="value">{regionsRetained}</span>
+				</div>
+				<div className="safety-row">
+					<span className="label">Compressed-Original</span>
+					<span className="value">{compressedOriginalKiB.toFixed(1)} KiB</span>
+				</div>
+				<div className="safety-row">
+					<span className="label">Storage Dedup</span>
+					<span className="value">{storageDedupPct}%</span>
+				</div>
+				<div className="safety-row">
+					<span className="label">Permanently Deleted</span>
+					<span className="value">{permanentlyDeleted}</span>
+				</div>
+			</div>
+			<div className="safety-note">
+				Every compacted region is kept verbatim (compressed). "Drop" = removed
+				from the live window only. We never delete your data.
+			</div>
+		</div>
+	);
+}

package/extensions/dashboard-client/src/components/ErrorBoundary.tsx

@@ -0,0 +1,53 @@
+/**
+ * dashboard-client/src/components/ErrorBoundary.tsx — React error boundary.
+ *
+ * Catches render errors anywhere in the child tree and shows a fallback
+ * with a reload button. Re-throws are prevented; recovery is via reload.
+ */
+
+import React, { type ReactNode } from "react";
+
+interface ErrorBoundaryProps {
+	children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+	hasError: boolean;
+	error: Error | null;
+}
+
+export class ErrorBoundary extends React.Component<
+	ErrorBoundaryProps,
+	ErrorBoundaryState
+> {
+	override state: ErrorBoundaryState = { hasError: false, error: null };
+
+	static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+		return { hasError: true, error };
+	}
+
+	override componentDidCatch(error: Error, info: React.ErrorInfo): void {
+		// Keep the error visible in the console for debugging; no network reporting
+		// (PREVENT-PI-004 — dashboard is fully local).
+		console.error("[dashboard] render error:", error, info.componentStack);
+	}
+
+	private handleReload = (): void => {
+		window.location.reload();
+	};
+
+	override render(): ReactNode {
+		if (this.state.hasError) {
+			return (
+				<div className="error-fallback">
+					<h2>Something went wrong</h2>
+					<p>{this.state.error?.message ?? "Unknown render error"}</p>
+					<button type="button" onClick={this.handleReload}>
+						Reload dashboard
+					</button>
+				</div>
+			);
+		}
+		return this.props.children;
+	}
+}

package/extensions/dashboard-client/src/components/EventCategoryFilter.tsx

@@ -0,0 +1,16 @@
+import type React from "react";
+export function EventCategoryFilter({
+	onFilter,
+}: {
+	onFilter: (f: string) => void;
+}): React.ReactElement {
+	return (
+		<div className="event-filter">
+			<button onClick={() => onFilter("all")}>All</button>
+			<button onClick={() => onFilter("agent_start")}>Agent Start</button>
+			<button onClick={() => onFilter("agent_end")}>Agent End</button>
+			<button onClick={() => onFilter("turn_start")}>Turn Start</button>
+			<button onClick={() => onFilter("turn_end")}>Turn End</button>
+		</div>
+	);
+}

package/extensions/dashboard-client/src/components/EventStream.tsx

@@ -0,0 +1,152 @@
+/**
+ * dashboard-client/src/components/EventStream.tsx — SSE event list with filters.
+ *
+ * Type badge colored by event type. Timestamp + expandable detail row.
+ * Type filter chips (all + per-type). Virtualization: manual windowing for
+ * 500+ events (render last N visible).
+ */
+
+import type React from "react";
+import { useState, useMemo } from "react";
+import type { SseEvent } from "@contracts";
+
+export interface EventStreamProps {
+	events: SseEvent[];
+}
+
+const TYPE_COLORS: Record<string, string> = {
+	compact_start: "ev-compact",
+	compact_end: "ev-compact",
+	compact_trigger: "ev-trigger",
+	compact_skip: "ev-trigger",
+	tier_changed: "ev-tier",
+	model_changed: "ev-tier",
+	pressure_lifted: "ev-tier",
+	checkpoint_persisted: "ev-checkpoint",
+	recall_inject: "ev-recall",
+	anchors_updated: "ev-recall",
+	config_updated: "ev-config",
+	config_preset: "ev-config",
+	crew_presence_changed: "ev-crew",
+	crew_turn_changed: "ev-crew",
+	crew_bandit_chosen: "ev-crew",
+	game_ritual_start: "ev-game",
+	game_ritual_stage: "ev-game",
+	game_ritual_end: "ev-game",
+	game_mode_changed: "ev-game",
+	game_render: "ev-game",
+};
+
+// Filterable event types (spec: compact_start/end, recall_inject, checkpoint_persisted + all).
+const FILTER_TYPES = [
+	"all",
+	"compact_start",
+	"compact_end",
+	"recall_inject",
+	"checkpoint_persisted",
+] as const;
+type FilterType = (typeof FILTER_TYPES)[number];
+
+const RENDER_WINDOW = 200; // render last 200 to keep DOM light under 500+ events
+
+function summarize(ev: SseEvent): string {
+	switch (ev.type) {
+		case "compact_start":
+			return `trigger=${ev.trigger} session=${ev.sessionId.slice(0, 8)}`;
+		case "compact_end":
+			return `freed=${ev.tokensFreed} ok=${ev.success} cp=${ev.checkpointId.slice(0, 8)}`;
+		case "compact_trigger":
+			return `pressure=${ev.pressure}% threshold=${ev.threshold}% armed=${ev.armed}`;
+		case "compact_skip":
+			return `reason=${ev.reason}`;
+		case "tier_changed":
+			return `${ev.from} → ${ev.to} ctx=${ev.contextPct}%`;
+		case "model_changed":
+			return `${ev.providerName}/${ev.model}`;
+		case "pressure_lifted":
+			return `${ev.beforePct}% → ${ev.afterPct}%`;
+		case "checkpoint_persisted":
+			return `cp=${ev.checkpointId.slice(0, 8)} sessionTok=${ev.sessionTokens}`;
+		case "recall_inject":
+			return `q="${ev.query.slice(0, 40)}" chunks=${ev.chunks} tok=${ev.tokens}`;
+		case "anchors_updated":
+			return `count=${ev.count} pinned=${ev.pinned}`;
+		case "config_updated":
+			return `key=${ev.key}`;
+		case "config_preset":
+			return `preset=${ev.preset}`;
+		case "crew_presence_changed":
+			return `agents=${ev.activeAgents} turn=${ev.currentTurn}`;
+		case "crew_turn_changed":
+			return `turn=${ev.turnIndex} agent=${ev.agentName}`;
+		case "crew_bandit_chosen":
+			return `agent=${ev.chosenAgent} score=${ev.score} regret=${ev.regret}`;
+		case "game_ritual_start":
+		case "game_ritual_stage":
+		case "game_ritual_end":
+		case "game_mode_changed":
+		case "game_render":
+			return `stage=${ev.type}`;
+	}
+}
+
+function formatTs(ts: string): string {
+	try {
+		const d = new Date(ts);
+		return d.toLocaleTimeString();
+	} catch {
+		return ts;
+	}
+}
+
+export function EventStream({ events }: EventStreamProps): React.ReactElement {
+	const [filter, setFilter] = useState<FilterType>("all");
+	const [expanded, setExpanded] = useState<number | null>(null);
+
+	const filtered = useMemo(() => {
+		const list =
+			filter === "all" ? events : events.filter((e) => e.type === filter);
+		// Newest first; render only the last RENDER_WINDOW to keep DOM light.
+		return list.slice(-RENDER_WINDOW).reverse();
+	}, [events, filter]);
+
+	return (
+		<div className="event-stream">
+			<div className="event-filters" role="toolbar">
+				{FILTER_TYPES.map((t) => (
+					<button
+						key={t}
+						type="button"
+						className={`filter-chip ${filter === t ? "active" : ""}`}
+						onClick={() => setFilter(t)}
+					>
+						{t === "all" ? "all" : t.replace(/_/g, " ")}
+					</button>
+				))}
+				<span className="event-count">{events.length} buffered</span>
+			</div>
+			<ul className="event-list">
+				{filtered.length === 0 && (
+					<li className="event-empty">No events yet.</li>
+				)}
+				{filtered.map((ev, idx) => {
+					const cls = TYPE_COLORS[ev.type] ?? "ev-default";
+					return (
+						<li
+							key={`${ev.ts}-${idx}`}
+							className={`event-row ${cls}`}
+							onClick={() => setExpanded(expanded === idx ? null : idx)}
+						>
+							<span className="ev-time">{formatTs(ev.ts)}</span>
+							<span className="ev-type">{ev.type}</span>
+							<span className="ev-summary">{summarize(ev)}</span>
+							{expanded === idx && (
+								<pre className="ev-detail">{JSON.stringify(ev, null, 2)}</pre>
+							)}
+						</li>
+					);
+				})}
+			</ul>
+		</div>
+	);
+}