pi-mega-compact 0.13.0 → 0.13.2

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

@@ -0,0 +1,350 @@
+/**
+ * api-contracts/endpoints/types.ts — inline response/query types for the
+ * endpoint registry.
+ *
+ * Extracted from endpoints.ts (delegate-shell split). Holds the response types
+ * that were defined inline (version/drift/servers/perf) plus the backwards-
+ * compatible re-export of the types that migrated to game-types.ts.
+ *
+ * PREVENT-PI-004: zero network code (type definitions only).
+ * PREVENT-011: no `any` type — all types are explicit.
+ */
+import type { IndexesIndexRow, IndexesSummaryResponse } from "../multi-repo.js";
+
+// ─── Game Score & Achievement Types ─────────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+
+// ─── Sessions Memory Graph (S39) ─────────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+
+// ─── Game State Patch (PUT request body) ────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+
+// ─── SSE Endpoint Definition ────────────────────────────────────────────────
+// (moved to game-types.ts; re-exported for backwards compatibility)
+
+export type {
+	GameScoreRow,
+	GameScoresQuery,
+	AchievementRow,
+	ActiveSession,
+	SessionsResponse,
+	SessionDataPoint,
+	SessionSeries,
+	SessionTimeseriesQuery,
+	SessionTimeseriesResponse,
+	GameStatePatch,
+	SseEndpointDef,
+	TopicRow,
+	TopicAssignmentRow,
+	TopicsResponse,
+	TopicDetailResponse,
+} from "../game-types.js";
+
+// ─── New Response Types (inline) ───────────────────────────────────────────
+
+/**
+ * Response for GET /api/version. Returns the dashboard server version string
+ * so the launcher can detect stale servers from older builds.
+ */
+export interface VersionResponse {
+	/** Semver-style version string of the running dashboard server. */
+	readonly version: string;
+}
+
+/**
+ * Aggregated summary of the multi-repo index (subset of IndexesSummaryResponse).
+ * Used by GET /api/summary for lightweight header tiles.
+ */
+export type IndexSummary = Pick<
+	IndexesSummaryResponse,
+	| "totalRepos"
+	| "totalCheckpoints"
+	| "totalTokensSaved"
+	| "totalCompressedOriginalBytes"
+>;
+
+/**
+ * Fallback response for GET /api/index when the multi-repo index is unavailable
+ * (no index.sqlite file or read error). All fields are null/empty.
+ */
+export interface IndexFallbackResponse {
+	/** Always null — no index data available. */
+	readonly updatedAt: null;
+	/** Always null — no summary available. */
+	readonly summary: null;
+	/** Always an empty array — no repos registered. */
+	readonly repos: IndexesIndexRow[];
+}
+
+/**
+ * Query parameters for GET /api/repos. The `active` parameter filters to repos
+ * seen within the last N hours (format: "<N>h", e.g. "24h").
+ */
+export interface ReposQuery {
+	/** Active-window filter in format "<hours>h" (e.g. "24h"). Optional. */
+	readonly active?: string;
+}
+
+/**
+ * Response for GET /api/repos. Returns the registry list with an optional
+ * active-window filter applied.
+ */
+export interface ReposResponse {
+	/** ISO timestamp of the last index update, or null if unavailable. */
+	readonly updatedAt: string | null;
+	/** Array of repo index rows. */
+	readonly repos: IndexesIndexRow[];
+	/** Number of repos in the response (after filtering). */
+	readonly count: number;
+}
+
+/**
+ * Response for GET /api/summary. Lightweight header tiles without the full
+ * repo list (keeps payload small for embed scenarios).
+ */
+export interface SummaryResponse {
+	/** ISO timestamp of the last index update, or null if unavailable. */
+	readonly updatedAt: string | null;
+	/** Aggregate index summary, or null if no index exists. */
+	readonly summary: IndexSummary | null;
+	/** Number of repos active within the last 24 hours. */
+	readonly activeRepos: number;
+	/** Total number of repos in the registry. */
+	readonly totalRepos: number;
+}
+
+// ─── Drift Report Types ─────────────────────────────────────────────────────
+
+/** Severity level for a drift signal. */
+export type DriftSeverity = "warn" | "info";
+
+/**
+ * A single drift signal for a repo.
+ */
+export interface DriftSignal {
+	/** The kind of drift detected. */
+	readonly kind: "stale" | "compaction_lag" | "model_churn";
+	/** Severity level of the signal. */
+	readonly severity: DriftSeverity;
+	/** Human-readable detail describing the drift. */
+	readonly detail: string;
+}
+
+/**
+ * Drift classification for a single repo.
+ */
+export interface RepoDrift {
+	/** Absolute path to the repo root. */
+	readonly repoRoot: string;
+	/** Display name of the repo. */
+	readonly displayName: string;
+	/** Unix timestamp (seconds) of the last dashboard activity. */
+	readonly lastSeen: number;
+	/** Unix timestamp (seconds) of the last compaction, or null if never. */
+	readonly lastCompactedAt: number | null;
+	/** Unix timestamp (seconds) of the last model capture, or null. */
+	readonly modelCapturedAt: number | null;
+	/** Array of drift signals detected for this repo. */
+	readonly signals: DriftSignal[];
+	/** Highest severity across signals; "ok" if none. */
+	readonly status: "ok" | "warn";
+}
+
+/**
+ * Response for GET /api/drift. Cross-repo drift report over the machine-wide
+ * repo_registry, flagging stale repos, compaction lag, and model churn.
+ */
+export interface DriftReportResponse {
+	/** Unix timestamp (seconds) when the report was generated. */
+	readonly generatedAt: number;
+	/** Aggregate counts by status/signal. */
+	readonly totals: {
+		/** Repos with no drift signals. */
+		readonly ok: number;
+		/** Repos with at least one warning signal. */
+		readonly warn: number;
+		/** Repos with the "stale" signal. */
+		readonly stale: number;
+		/** Repos with the "compaction_lag" signal. */
+		readonly compactionLag: number;
+		/** Repos with the "model_churn" signal. */
+		readonly modelChurn: number;
+	};
+	/** Per-repo drift classifications. */
+	readonly repos: RepoDrift[];
+}
+
+// ─── Servers Types ──────────────────────────────────────────────────────────
+
+/**
+ * A single server entry in the GET /api/servers response. Represents a
+ * recently-active repo with its live dashboard snapshot data.
+ */
+export interface ServerEntry {
+	/** Absolute path to the repo root. */
+	readonly repoRoot: string;
+	/** Display name of the repo. */
+	readonly displayName: string;
+	/** Model name, or null if not set. */
+	readonly model: string | null;
+	/** Provider display name, or null if not set. */
+	readonly provider: string | null;
+	/** Unix timestamp (seconds) of the last dashboard activity. */
+	readonly lastSeen: number;
+	/** Unix timestamp (seconds) of the last compaction, or null. */
+	readonly lastCompactedAt: number | null;
+	/** Current compaction tier, or null if no live snapshot. Present when a live dashboard.json exists. */
+	readonly tier?: string | null;
+	/** Current context pressure percentage (0–100), or null. Present when a live snapshot has context data. */
+	readonly contextPct?: number | null;
+	/** Current session state string, or null. Present when a live snapshot has session data. */
+	readonly state?: string | null;
+	/** Cache hit counters from the live snapshot, or null. Present when a live snapshot has cacheHits. */
+	readonly cacheHits?: {
+		readonly session: number;
+		readonly total: number;
+		readonly sessionTokensSaved: number;
+		readonly totalTokensSaved: number;
+	} | null;
+	/** Compaction counters from the live snapshot, or null. Present when a live snapshot has compacts. */
+	readonly compacts?: {
+		readonly session: number;
+		readonly total: number;
+	} | null;
+	/** Time saved counters from the live snapshot, or null. Present when a live snapshot has timeSaved. */
+	readonly timeSaved?: {
+		readonly compact: {
+			readonly sessionSec: number;
+			readonly totalSec: number;
+		};
+		readonly cacheHit: {
+			readonly sessionSec: number;
+			readonly totalSec: number;
+		};
+	} | null;
+	/** ISO timestamp of the live snapshot, or null. Present when a live snapshot has updatedAt. */
+	readonly updatedAt?: string | null;
+	/** Provider prompt-cache lifetime aggregates for this repo, or null when unavailable. */
+	readonly providerCache?: {
+		readonly avgHitPct: number;
+		readonly cacheRead: number;
+		readonly cacheWrite: number;
+		readonly totalInput: number;
+		readonly sampleCount: number;
+		readonly estimatedSaved: number | null;
+	} | null;
+}
+
+/**
+ * Response for GET /api/servers. Lists recently-active repo servers with
+ * live snapshot data.
+ */
+export interface ServersResponse {
+	/** ISO timestamp when the response was generated. */
+	readonly updatedAt: string;
+	/** Array of server entries, sorted by lastSeen descending. */
+	readonly servers: ServerEntry[];
+}
+
+// ─── Perf Types ─────────────────────────────────────────────────────────────
+
+/** Percentile statistics for a latency metric (in milliseconds). */
+export interface PerfPercentile {
+	/** 50th percentile (median) in milliseconds. */
+	readonly p50: number;
+	/** 95th percentile in milliseconds. */
+	readonly p95: number;
+	/** Number of samples in the window. */
+	readonly n: number;
+}
+
+/** Average statistics for a rate metric. */
+export interface PerfAverage {
+	/** Average value across all samples in the window. */
+	readonly avg: number;
+	/** Number of samples in the window. */
+	readonly n: number;
+}
+
+/** Latest-value statistics for a gauge metric. */
+export interface PerfLatest {
+	/** Most recent value in the window. */
+	readonly latest: number;
+	/** Number of samples in the window. */
+	readonly n: number;
+}
+
+/** A single cache hit rate sample with timestamp. */
+export interface CacheHitSample {
+	/** Cache hit percentage (0–100). */
+	readonly pct: number;
+	/** Epoch ms timestamp of the sample. */
+	readonly ts: number;
+}
+
+/** Average + latest statistics for cache hit percentage. */
+export interface PerfCacheHit {
+	/** Average cache hit percentage (0–100). */
+	readonly avg: number;
+	/** Most recent cache hit percentage (0–100). */
+	readonly latest: number;
+	/** Number of samples in the window. */
+	readonly n: number;
+	/** Raw cache hit samples with timestamps for time-series charting. */
+	readonly samples: CacheHitSample[];
+}
+
+/** Diagnostic counters from the live dashboard snapshot. */
+export interface PerfDiag {
+	/** Number of fast-gate context trim fires. */
+	readonly ctxFastGate: number;
+	/** Number of live trim fires. */
+	readonly liveTrimFires: number;
+	/** Number of live trim replays. */
+	readonly liveTrimReplays: number;
+}
+
+/**
+ * Query parameters for GET /api/perf. The `minutes` parameter controls the
+ * rolling window size.
+ */
+export interface PerfQuery {
+	/** Rolling window size in minutes (default: 30, max: 1440). Optional. */
+	readonly minutes?: number;
+}
+
+/**
+ * Response for GET /api/perf. Rolling-window aggregates over perf_samples
+ * with per-kind p50/p95, latest rss/heap, cpu counters, and diagnostic data.
+ */
+export interface PerfResponse {
+	/** ISO timestamp when the response was generated. */
+	readonly updatedAt: string;
+	/** Rolling window size in minutes. */
+	readonly windowMinutes: number;
+	/** Total number of perf samples in the window. */
+	readonly sampleCount: number;
+	/** Turn latency statistics in milliseconds. */
+	readonly turn_latency_ms: PerfPercentile;
+	/** Provider latency statistics in milliseconds. */
+	readonly provider_latency_ms: PerfPercentile;
+	/** Tokens-per-second statistics. */
+	readonly tps: PerfAverage;
+	/** Cache hit percentage statistics. */
+	readonly cache_hit_pct: PerfCacheHit;
+	/** Database recompute duration statistics in milliseconds. */
+	readonly db_recompute_ms: PerfPercentile;
+	/** Disk write duration statistics in milliseconds. */
+	readonly disk_write_ms: PerfPercentile;
+	/** RSS memory usage in MB (latest value). */
+	readonly rss_mb: PerfLatest;
+	/** Heap memory usage in MB (latest value). */
+	readonly heap_mb: PerfLatest;
+	/** CPU user time in milliseconds (latest value). */
+	readonly cpu_user_ms: PerfLatest;
+	/** CPU system time in milliseconds (latest value). */
+	readonly cpu_sys_ms: PerfLatest;
+	/** Diagnostic counters from the live snapshot, or null if unavailable. */
+	readonly diag: PerfDiag | null;
+}