pi-mega-compact 0.11.13 → 0.12.1

package/src/contextHealth/outputQuality.ts

@@ -0,0 +1,139 @@
+/**
+ * outputQuality.ts — pure assistant-output text quality detectors.
+ *
+ * No I/O beyond the injected Embedder (which is fully local / PREVENT-PI-004).
+ * All functions are deterministic and side-effect free.
+ */
+import type { Embedder } from "../embedder.js";
+import { cosineSimilarity } from "../embedder.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Tokenize on whitespace; skip empty tokens. */
+function tokenizeWords(text: string): string[] {
+	return text.split(/\s+/).filter((w) => w.length > 0);
+}
+
+/** Split on sentence-terminating punctuation; skip empty. */
+function splitSentences(text: string): string[] {
+	return text.split(/[.!?]+/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// ─── Detectors ─────────────────────────────────────────────────────────────
+
+/**
+ * Repetition ratio via 3-gram overlap.
+ *
+ * Builds sliding 3-word windows over the token stream. Returns the fraction
+ * of 3-grams that appear more than once (i.e. are repeated). Range 0–1;
+ * values above 0.30 signal likely garbled / looping output.
+ */
+export function detectRepetition(text: string): number {
+	const words = tokenizeWords(text);
+	if (words.length < 3) return 0;
+	const count = new Map<string, number>();
+	for (let i = 0; i <= words.length - 3; i++) {
+		const gram = words.slice(i, i + 3).join(" ");
+		count.set(gram, (count.get(gram) ?? 0) + 1);
+	}
+	const total = words.length - 2;
+	if (total === 0) return 0;
+	let repeated = 0;
+	for (const n of count.values()) {
+		if (n > 1) repeated += n;
+	}
+	// Each duplicate occurrence beyond the first adds to the repeated count.
+	// Clamp total to total_3grams so the ratio stays in [0,1].
+	return Math.min(1, repeated / total);
+}
+
+/**
+ * Sentence-level coherence score via adjacent cosine similarity.
+ *
+ * Splits text into sentences, embeds each, and computes the cosine similarity
+ * between every consecutive pair. Returns the average. Range 0–1 (higher =
+ * more coherent); fewer than 2 sentences returns 1.0 (cannot measure).
+ */
+export function detectCoherence(text: string, embedder: Embedder): number {
+	const sentences = splitSentences(text);
+	if (sentences.length < 2) return 1.0;
+
+	let sum = 0;
+	let pairCount = 0;
+	for (let i = 0; i < sentences.length - 1; i++) {
+		const a = embedder.embed(sentences[i]);
+		const b = embedder.embed(sentences[i + 1]);
+		sum += cosineSimilarity(a, b);
+		pairCount++;
+	}
+	return pairCount > 0 ? sum / pairCount : 1.0;
+}
+
+/**
+ * Token-salad detector.
+ *
+ * A word is "recognized" if it has length ≥ 2 AND contains at least one vowel
+ * (a / e / i / o / u, case-insensitive). Returns the fraction of unrecognized
+ * words. Values above 0.6 suggest scrambled / token-confused output.
+ */
+export function detectTokenSalad(text: string): number {
+	const words = tokenizeWords(text);
+	if (words.length === 0) return 0;
+
+	const VOWELS = /[aeiou]/i;
+	let unrecognized = 0;
+	for (const w of words) {
+		if (w.length < 2 || !VOWELS.test(w)) unrecognized++;
+	}
+	return unrecognized / words.length;
+}
+
+/**
+ * True when the output is entirely absent or whitespace-only.
+ */
+export function detectEmptyOutput(text: string): boolean {
+	return text.trim().length === 0;
+}
+
+// ─── Composite ─────────────────────────────────────────────────────────────
+
+/**
+ * Compute the full output-quality profile for assistant output text.
+ *
+ * Returns a score 0–1 (1 = healthy) and the three sub-diagnostics.
+ *
+ * Penalty weights (sum to 1.0):
+ *   repetition  40% — repeated 3-grams are the strongest corruption signal
+ *   coherence   30% — incoherent sentence transitions
+ *   salad       30% — garbage tokens
+ *
+ * Empty output is a hard 0.0 (nothing to evaluate).
+ */
+export function computeOutputQuality(
+	text: string,
+	embedder: Embedder,
+): {
+	score: number;
+	repetitionRatio: number;
+	coherenceScore: number;
+	isEmpty: boolean;
+} {
+	const isEmpty = detectEmptyOutput(text);
+	if (isEmpty) {
+		return { score: 0.0, repetitionRatio: 0, coherenceScore: 1.0, isEmpty: true };
+	}
+
+	const repetitionRatio = detectRepetition(text);
+	const coherenceScore = detectCoherence(text, embedder);
+	const saladRatio = detectTokenSalad(text);
+
+	const repetitionPenalty = repetitionRatio * 0.4;
+	const coherencePenalty = (1 - coherenceScore) * 0.3;
+	const saladPenalty = saladRatio * 0.3;
+
+	const score = Math.max(0, Math.min(1,
+		1.0 - repetitionPenalty - coherencePenalty - saladPenalty,
+	));
+
+	return { score, repetitionRatio, coherenceScore, isEmpty: false };
+}

package/src/contextHealth.ts

@@ -0,0 +1,191 @@
+/**
+ * contextHealth.ts — Context Health scoring engine.
+ *
+ * Composite scoring + SQLite persistence for session-level context quality
+ * telemetry. The three sub-scoring modules are:
+ *   outputQuality.ts — assistant output text analysis
+ *   drift.ts         — rolling-window topic / error / prefix drift
+ *
+ * All SQL is fully parameterized (PREVENT-002). The `context_health` table
+ * is created inline on first write so this module is self-contained and does
+ * not require schema.ts to be modified (no existing files touched).
+ *
+ * PREVENT-PI-004: local SQLite only, zero network. All I/O is node:sqlite.
+ * PREVENT-011: no `any` — all row shapes are typed.
+ */
+import { openStore } from "./store/sqlite/utils.js";
+
+// ─── Composite score ─────────────────────────────────────────────────────────
+
+/** Sub-scores fed into the composite health score. */
+export interface ContextHealthSubScores {
+	/** Topic drift score (0–1, higher = less drift). */
+	drift: number;
+	/** Output quality score (0–1, higher = healthier output). */
+	outputQuality: number;
+	/** Error-rate score (0–1, higher = fewer errors). */
+	errorRate: number;
+	/** Cache health score (0–1, higher = healthier cache). */
+	cacheHealth: number;
+	/** Cache poison score (0–1, higher = less poison). */
+	cachePoison: number;
+}
+
+/**
+ * Weighted composite health score from five sub-dimensions.
+ *
+ * Weights:
+ *   output quality  22% — primary measure of model output health
+ *   drift           22% — session-level coherence
+ *   cache poison    20% — prompt-cache integrity
+ *   cache health    18% — cache hit rate stability
+ *   error rate      18% — error frequency
+ *
+ * Returns 0–1: 1 = fully healthy, 0 = severely degraded.
+ */
+export function computeHealthScore(sub: ContextHealthSubScores): number {
+	const raw =
+		sub.outputQuality * 0.22 +
+		sub.drift * 0.22 +
+		sub.cachePoison * 0.20 +
+		sub.cacheHealth * 0.18 +
+		sub.errorRate * 0.18;
+	return Math.max(0, Math.min(1, raw));
+}
+
+// ─── SQLite persistence ───────────────────────────────────────────────────────
+
+/** A single row as stored in + returned from the context_health table. */
+export interface ContextHealthRow {
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	composite: number;
+	modelId?: string;
+	repetitionRatio?: number;
+	coherenceScore?: number;
+	prefixHash?: string;
+}
+
+/**
+ * Record one context health sample into the SQLite store.
+ *
+ * Non-fatal: errors are caught and silently ignored so instrumentation never
+ * blocks the agent loop. Table schema is owned by schema.ts (SCHEMA_VERSION 5).
+ *
+ * PREVENT-002: all values are bound as parameters (? placeholders).
+ */
+export function recordContextHealth(
+	stateDir: string,
+	row: ContextHealthRow,
+): void {
+	try {
+		const db = openStore(stateDir);
+		db.prepare(
+			`INSERT INTO context_health
+       (ts, session_id, turn_index, drift_score, output_quality,
+        error_score, cache_health, cache_poison, composite,
+        model_id, repetition_ratio, coherence_score, prefix_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			row.ts,
+			row.sessionId,
+			row.turnIndex,
+			row.driftScore,
+			row.outputQuality,
+			row.errorScore,
+			row.cacheHealth,
+			row.cachePoison,
+			row.composite,
+			row.modelId ?? null,
+			row.repetitionRatio ?? null,
+			row.coherenceScore ?? null,
+			row.prefixHash ?? null,
+		);
+	} catch {
+		/* non-fatal: context health instrumentation never blocks the agent loop */
+	}
+}
+
+/**
+ * Read context health samples since `sinceTs`, optionally filtered by modelId.
+ *
+ * Returns rows in ascending ts order. Non-fatal (empty array on error).
+ *
+ * PREVENT-002: modelId is bound as a parameter (? placeholder).
+ * PREVENT-001: row.meta column (if added later) is handled by null-safe reads.
+ */
+export function readContextHealth(
+	stateDir: string,
+	sinceTs: number,
+	modelId?: string,
+): ContextHealthRow[] {
+	try {
+		const db = openStore(stateDir);
+		const sql = modelId
+			? `SELECT ts, session_id, turn_index, drift_score, output_quality,
+              error_score, cache_health, cache_poison, composite,
+              model_id, repetition_ratio, coherence_score, prefix_hash
+         FROM context_health
+         WHERE ts >= ? AND model_id = ?
+         ORDER BY ts ASC`
+			: `SELECT ts, session_id, turn_index, drift_score, output_quality,
+              error_score, cache_health, cache_poison, composite,
+              model_id, repetition_ratio, coherence_score, prefix_hash
+         FROM context_health
+         WHERE ts >= ?
+         ORDER BY ts ASC`;
+		const params = modelId ? [sinceTs, modelId] : [sinceTs];
+		const rows = db.prepare(sql).all(...params) as Array<{
+			ts: number;
+			session_id: string;
+			turn_index: number;
+			drift_score: number;
+			output_quality: number;
+			error_score: number;
+			cache_health: number;
+			cache_poison: number;
+			composite: number;
+			model_id: string | null;
+			repetition_ratio: number | null;
+			coherence_score: number | null;
+			prefix_hash: string | null;
+		}>;
+		const out: ContextHealthRow[] = [];
+		for (const r of rows) {
+			out.push({
+				ts: r.ts,
+				sessionId: r.session_id,
+				turnIndex: r.turn_index,
+				driftScore: r.drift_score,
+				outputQuality: r.output_quality,
+				errorScore: r.error_score,
+				cacheHealth: r.cache_health,
+				cachePoison: r.cache_poison,
+				composite: r.composite,
+				modelId: r.model_id ?? undefined,
+				repetitionRatio: r.repetition_ratio ?? undefined,
+				coherenceScore: r.coherence_score ?? undefined,
+				prefixHash: r.prefix_hash ?? undefined,
+			});
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
+// ─── Re-exports for consumers ────────────────────────────────────────────────
+
+export { computeOutputQuality } from "./contextHealth/outputQuality.js";
+export {
+	computeTopicDrift,
+	computeErrorEscalation,
+	computePrefixInstability,
+	computeDriftScore,
+} from "./contextHealth/drift.js";

package/src/store/sqlite/context-health.ts

@@ -0,0 +1,342 @@
+/**
+ * context-health.ts — `context_health` and `cache_poison_events` table accessors.
+ *
+ * Append-only per-turn Context Health metrics recorded during compactSession:
+ * drift_score, output_quality, error_score, cache_health, cache_poison,
+ * composite, repetition_ratio, coherence_score, and prefix_hash.
+ *
+ * Also records cache-poison advisory events when cache corruption/inconsistency
+ * is detected at a given cache layer.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL uses ? placeholders, no string-concatenated values.
+ * Pi-agnostic: no pi runtime types.
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+
+// ─── Shared row types ────────────────────────────────────────────────────────
+
+/** A single context_health row (as stored + returned). */
+export interface ContextHealthRow {
+	id: number;
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	composite: number;
+	modelId: string | null;
+	repetitionRatio: number | null;
+	coherenceScore: number | null;
+	prefixHash: string | null;
+}
+
+/** Latest summary row (most recent by ts). */
+export interface LatestContextHealth {
+	composite: number;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	ts: number;
+	modelId: string | null;
+}
+
+/** A single cache_poison_events row (as stored + returned). */
+export interface CachePoisonEvent {
+	id: number;
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	layer: number | null;
+	detail: string | null;
+	severity: string | null;
+}
+
+// ─── context_health accessors ────────────────────────────────────────────────
+
+/**
+ * Record one context health sample. All values are fully parameterized
+ * (PREVENT-002). Optional columns (model_id, repetition_ratio, coherence_score,
+ * prefix_hash) are passed as-is; the column list enumerates every field so
+ * missing optional fields are NULL in the row.
+ *
+ * Non-fatal: any write error is logged to stderr and silently swallowed so
+ * instrumentation can never block the agent loop.
+ */
+export function recordContextHealthRow(
+	stateDir: string = getStateDir(),
+	row: {
+		ts: number;
+		turnIndex: number;
+		sessionId: string;
+		driftScore: number;
+		outputQuality: number;
+		errorScore: number;
+		cacheHealth: number;
+		cachePoison: number;
+		composite: number;
+		modelId?: string;
+		repetitionRatio?: number;
+		coherenceScore?: number;
+		prefixHash?: string;
+	},
+): void {
+	try {
+		const db = openStore(stateDir);
+		db.prepare(
+			`INSERT INTO context_health
+			   (ts, turn_index, session_id, drift_score, output_quality,
+			    error_score, cache_health, cache_poison, composite,
+			    model_id, repetition_ratio, coherence_score, prefix_hash)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			row.ts,
+			row.turnIndex,
+			row.sessionId,
+			row.driftScore,
+			row.outputQuality,
+			row.errorScore,
+			row.cacheHealth,
+			row.cachePoison,
+			row.composite,
+			row.modelId ?? null,
+			row.repetitionRatio ?? null,
+			row.coherenceScore ?? null,
+			row.prefixHash ?? null,
+		);
+	} catch (err) {
+		// Non-fatal: log and continue — health sampling must never block the agent.
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[context-health] recordContextHealthRow error: ${msg}\n`);
+	}
+}
+
+/**
+ * Read context health rows since `sinceTs`. When `modelId` is provided the
+ * query adds an AND filter; otherwise all models are returned. Results are
+ * ordered ascending by ts. Returns an empty array on any error (non-fatal).
+ *
+ * SQL is fully parameterized (PREVENT-002).
+ */
+export function readContextHealthRows(
+	stateDir: string = getStateDir(),
+	sinceTs: number,
+	modelId?: string,
+): ContextHealthRow[] {
+	try {
+		const db = openStore(stateDir);
+		let rows: Array<{
+			id: number;
+			ts: number;
+			turn_index: number;
+			session_id: string;
+			drift_score: number;
+			output_quality: number;
+			error_score: number;
+			cache_health: number;
+			cache_poison: number;
+			composite: number;
+			model_id: string | null;
+			repetition_ratio: number | null;
+			coherence_score: number | null;
+			prefix_hash: string | null;
+		}>;
+
+		if (modelId != null) {
+			rows = db
+				.prepare(
+					`SELECT id, ts, turn_index, session_id, drift_score, output_quality,
+					        error_score, cache_health, cache_poison, composite,
+					        model_id, repetition_ratio, coherence_score, prefix_hash
+					 FROM context_health
+					 WHERE ts >= ? AND model_id = ?
+					 ORDER BY ts ASC`,
+				)
+				.all(sinceTs, modelId) as typeof rows;
+		} else {
+			rows = db
+				.prepare(
+					`SELECT id, ts, turn_index, session_id, drift_score, output_quality,
+					        error_score, cache_health, cache_poison, composite,
+					        model_id, repetition_ratio, coherence_score, prefix_hash
+					 FROM context_health
+					 WHERE ts >= ?
+					 ORDER BY ts ASC`,
+				)
+				.all(sinceTs) as typeof rows;
+		}
+
+		return rows.map((r) => ({
+			id: r.id,
+			ts: r.ts,
+			turnIndex: r.turn_index,
+			sessionId: r.session_id,
+			driftScore: r.drift_score,
+			outputQuality: r.output_quality,
+			errorScore: r.error_score,
+			cacheHealth: r.cache_health,
+			cachePoison: r.cache_poison,
+			composite: r.composite,
+			modelId: r.model_id,
+			repetitionRatio: r.repetition_ratio,
+			coherenceScore: r.coherence_score,
+			prefixHash: r.prefix_hash,
+		}));
+	} catch {
+		// Non-fatal: return empty array on DB error.
+		return [];
+	}
+}
+
+/**
+ * Read the most recent context_health row (ORDER BY ts DESC LIMIT 1).
+ * Returns null when no rows exist or on any error.
+ */
+export function readLatestContextHealth(
+	stateDir: string = getStateDir(),
+): LatestContextHealth | null {
+	try {
+		const db = openStore(stateDir);
+		const row = db
+			.prepare(
+				`SELECT composite, drift_score, output_quality, error_score,
+				        cache_health, cache_poison, ts, model_id
+				 FROM context_health
+				 ORDER BY ts DESC
+				 LIMIT 1`,
+			)
+			.get() as
+			| {
+					composite: number;
+					drift_score: number;
+					output_quality: number;
+					error_score: number;
+					cache_health: number;
+					cache_poison: number;
+					ts: number;
+					model_id: string | null;
+				}
+			| undefined;
+
+		if (!row) return null;
+		return {
+			composite: row.composite,
+			driftScore: row.drift_score,
+			outputQuality: row.output_quality,
+			errorScore: row.error_score,
+			cacheHealth: row.cache_health,
+			cachePoison: row.cache_poison,
+			ts: row.ts,
+			modelId: row.model_id,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Read the trailing `limit` composite scores (most recent first), then reverse
+ * to chronological order for sparkline rendering. Returns an empty array when
+ * no rows exist or on any error.
+ *
+ * SQL is fully parameterized (PREVENT-002).
+ */
+export function readContextHealthTrend(
+	stateDir: string = getStateDir(),
+	limit: number,
+): number[] {
+	try {
+		const db = openStore(stateDir);
+		const rows = db
+			.prepare(
+				`SELECT composite FROM context_health
+				 ORDER BY ts DESC LIMIT ?`,
+			)
+			.all(limit) as Array<{ composite: number }>;
+
+		// Reverse to chronological (oldest first) for sparkline display.
+		return rows.map((r) => r.composite).reverse();
+	} catch {
+		return [];
+	}
+}
+
+// ─── cache_poison_events accessors ───────────────────────────────────────────
+
+/**
+ * Record one cache poison advisory event. Fully parameterized (PREVENT-002).
+ * Non-fatal: write errors are logged to stderr and silently swallowed.
+ */
+export function recordCachePoisonEvent(
+	stateDir: string = getStateDir(),
+	event: {
+		ts: number;
+		turnIndex: number;
+		sessionId: string;
+		layer: number;
+		detail: string;
+		severity: "warn" | "alert";
+	},
+): void {
+	try {
+		const db = openStore(stateDir);
+		db.prepare(
+			`INSERT INTO cache_poison_events
+			   (ts, turn_index, session_id, layer, detail, severity)
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+		).run(event.ts, event.turnIndex, event.sessionId, event.layer, event.detail, event.severity);
+	} catch (err) {
+		// Non-fatal: advisory logging must never block the agent loop.
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[context-health] recordCachePoisonEvent error: ${msg}\n`);
+	}
+}
+
+/**
+ * Read cache poison events since `sinceTs`, ordered descending by ts (most
+ * recent first), capped at 100 rows. Returns an empty array on any error
+ * (non-fatal). SQL is fully parameterized (PREVENT-002).
+ */
+export function readCachePoisonEvents(
+	stateDir: string = getStateDir(),
+	sinceTs: number,
+): CachePoisonEvent[] {
+	try {
+		const db = openStore(stateDir);
+		const rows = db
+			.prepare(
+				`SELECT id, ts, turn_index, session_id, layer, detail, severity
+				 FROM cache_poison_events
+				 WHERE ts >= ?
+				 ORDER BY ts DESC
+				 LIMIT 100`,
+			)
+			.all(sinceTs) as Array<{
+			id: number;
+			ts: number;
+			turn_index: number;
+			session_id: string;
+			layer: number | null;
+			detail: string | null;
+			severity: string | null;
+		}>;
+
+		return rows.map((r) => ({
+			id: r.id,
+			ts: r.ts,
+			turnIndex: r.turn_index,
+			sessionId: r.session_id,
+			layer: r.layer,
+			detail: r.detail,
+			severity: r.severity,
+		}));
+	} catch {
+		return [];
+	}
+}

package/src/store/sqlite/meta.ts

@@ -79,6 +79,22 @@ export function bumpDedupStats(deduped: boolean, stateDir: string = getStateDir(
   if (deduped) incMeta("deduped", 1, stateDir);
 }
 
+// --- Context health mitigation (runtime-toggleable via dashboard) ----------
+
+/** Read the context_health_mitigate flag from meta. Returns false if unset. */
+export function getHealthMitigate(stateDir: string = getStateDir()): boolean {
+  return getMeta("context_health_mitigate", stateDir) === "true";
+}
+
+/** Set the context_health_mitigate flag in meta (runtime-toggleable). */
+export function setHealthMitigate(enabled: boolean, stateDir: string = getStateDir()): void {
+  const db = openStore(stateDir);
+  db.prepare(
+    `INSERT INTO meta(key, value) VALUES('context_health_mitigate', ?)
+     ON CONFLICT(key) DO UPDATE SET value = ?`,
+  ).run(enabled ? "true" : "false", enabled ? "true" : "false");
+}
+
 // --- Live dashboard counters (schemaless meta key/value — NO migration) -----
 // These reuse the private `incMeta` atomically-incrementing integer counter so
 // all cumulative tallies live in the same `meta` table as tokens_saved etc.