pi-mega-compact 0.16.0 → 0.16.2

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

@@ -54,6 +54,9 @@ import type {
 	SettingsUpdateRequest,
 	SettingsResponsePost,
 	RagMetricsResponse,
+	ModelThresholdsResponse,
+	ModelThresholdPutRequest,
+	ModelThresholdPutResponse,
 	WikiIndexResponse,
 	WikiPageResponse,
 	CurationResult,
@@ -337,7 +340,9 @@ export function configureEmbedder(
 // ─── RAPTOR tree (Part B) ─────────────────────────────────────────────
 
 /** GET /api/raptor-tree — tree for a session (defaults to latest with nodes). */
-export function fetchRaptorTree(sessionId?: string): Promise<RaptorTreeResponse> {
+export function fetchRaptorTree(
+	sessionId?: string,
+): Promise<RaptorTreeResponse> {
 	return getJson<RaptorTreeResponse>(
 		`${ENDPOINTS.raptorTree.path}${query({ sessionId })}`,
 	);
@@ -398,10 +403,7 @@ export function fetchWikiIndex(): Promise<WikiIndexResponse> {
 /** GET /api/wiki/topic/:topicId — single topic page + provenance. */
 export function fetchWikiTopic(topicId: string): Promise<WikiPageResponse> {
 	return getJson<WikiPageResponse>(
-		ENDPOINTS.wikiTopic.path.replace(
-			":topicId",
-			encodeURIComponent(topicId),
-		),
+		ENDPOINTS.wikiTopic.path.replace(":topicId", encodeURIComponent(topicId)),
 	);
 }
 
@@ -411,10 +413,7 @@ export function renameTopic(
 	label: string,
 ): Promise<CurationResult> {
 	return putJson<CurationResult>(
-		ENDPOINTS.renameTopic.path.replace(
-			":topicId",
-			encodeURIComponent(topicId),
-		),
+		ENDPOINTS.renameTopic.path.replace(":topicId", encodeURIComponent(topicId)),
 		{ label } satisfies RenameTopicRequest,
 	);
 }
@@ -436,10 +435,7 @@ export function splitTopic(
 	memoryIds: string[],
 ): Promise<CurationResult> {
 	return postJson<CurationResult>(
-		ENDPOINTS.splitTopic.path.replace(
-			":topicId",
-			encodeURIComponent(topicId),
-		),
+		ENDPOINTS.splitTopic.path.replace(":topicId", encodeURIComponent(topicId)),
 		{ memoryIds } satisfies SplitTopicRequest,
 	);
 }
@@ -460,3 +456,32 @@ export function fetchTopicTimeline(
 export function fetchTopicEvolution(): Promise<TopicEvolutionResponse> {
 	return getJson<TopicEvolutionResponse>(ENDPOINTS.topicEvolution.path);
 }
+
+// ─── Per-model compaction thresholds (S52 / v0.16.1) ────────────────────
+
+/** GET /api/model-thresholds — list known models with their thresholds. */
+export function fetchModelThresholds(): Promise<ModelThresholdsResponse> {
+	return getJson<ModelThresholdsResponse>(ENDPOINTS.modelThresholds.path);
+}
+
+/** PUT /api/model-thresholds — upsert a per-model override. */
+export function putModelThreshold(
+	body: ModelThresholdPutRequest,
+): Promise<ModelThresholdPutResponse> {
+	return putJson<ModelThresholdPutResponse>(
+		ENDPOINTS.modelThresholds.path,
+		body,
+	);
+}
+
+/** DELETE /api/model-thresholds/:modelId — delete an override (revert). */
+export async function deleteModelThreshold(
+	modelId: string,
+): Promise<{ deleted: boolean }> {
+	const res = await fetch(
+		`${ENDPOINTS.modelThresholds.path}/${encodeURIComponent(modelId)}`,
+		{ method: "DELETE" },
+	);
+	if (!res.ok) throw new Error(`deleteModelThreshold ${res.status}`);
+	return res.json() as Promise<{ deleted: boolean }>;
+}

package/extensions/dashboard-client/src/tabs/SetupTab/ThresholdsPanel.tsx

@@ -0,0 +1,334 @@
+/**
+ * SetupTab/ThresholdsPanel.tsx — per-model compaction thresholds (S52 / v0.16.1).
+ *
+ * Lists every known model (from model_snapshots) with two sliders each:
+ *   - Safety Margin (0-20%): reserved after summary + maxOutput. Lower =
+ *     more usable tail but risks the "too long even after compaction" error.
+ *   - Fire Point (10-90%): % of window where compaction fires. Lower = compact
+ *     earlier (more headroom); higher = more context before compaction.
+ *
+ * Warnings fire on <5% safety (overflow risk) and >85% fire point (aggressive
+ * — may hit the cap before compaction triggers). Changes save immediately via
+ * PUT /api/model-thresholds; a "Reset to default" button DELETEs the override.
+ *
+ * PREVENT-PI-004: all data comes from localhost dashboard API endpoints.
+ */
+import type React from "react";
+import { useState, useEffect, useCallback } from "react";
+import {
+	fetchModelThresholds,
+	putModelThreshold,
+	deleteModelThreshold,
+} from "../../api/client";
+import type { ModelThresholdsResponse } from "@contracts";
+
+interface ModelRow {
+	readonly modelId: string;
+	readonly provider: string;
+	readonly modelName: string | null;
+	readonly contextWindow: number;
+	readonly maxTokens: number;
+	readonly hasOverride: boolean;
+	readonly threshold: {
+		readonly safetyMarginPct: number;
+		readonly firePointPct: number;
+		readonly isOverride: boolean;
+	};
+}
+
+function fmtWindow(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
+	if (n >= 1000) return `${Math.round(n / 1000)}K`;
+	return String(n);
+}
+
+/** Live preview of the usable tail budget for a model + slider values. */
+function usableTail(
+	ctxWindow: number,
+	maxTokens: number,
+	safetyPct: number,
+): string {
+	if (ctxWindow <= 0) return "—";
+	const maxOut = maxTokens > 0 ? maxTokens : Math.ceil(ctxWindow * 0.1);
+	const reserve = maxOut + Math.ceil(ctxWindow * (safetyPct / 100));
+	const usable = ctxWindow - reserve;
+	if (usable <= 0) return "0 (at risk)";
+	return `${fmtWindow(usable)} tokens`;
+}
+
+function ThresholdSlider({
+	label,
+	value,
+	min,
+	max,
+	step = 1,
+	onChange,
+	warning,
+}: {
+	readonly label: string;
+	readonly value: number;
+	readonly min: number;
+	readonly max: number;
+	readonly step?: number;
+	readonly onChange: (v: number) => void;
+	readonly warning?: string;
+}): React.ReactElement {
+	return (
+		<div className="flex flex-col gap-1">
+			<div className="flex items-center justify-between text-xs">
+				<span className="font-medium text-fg-muted">{label}</span>
+				<span
+					className={`font-mono ${warning ? "text-warning" : "text-fg"}`}
+					title={warning}
+				>
+					{value}%
+				</span>
+			</div>
+			<input
+				type="range"
+				min={min}
+				max={max}
+				step={step}
+				value={value}
+				onChange={(e) => onChange(Number(e.target.value))}
+				className="threshold-slider w-full"
+			/>
+			{warning && <p className="text-[10px] text-warning">⚠ {warning}</p>}
+		</div>
+	);
+}
+
+function ModelThresholdRow({
+	model,
+	defaults,
+	safetyRange,
+	fireRange,
+	onSave,
+	onReset,
+	saving,
+}: {
+	readonly model: ModelRow;
+	readonly defaults: { safetyMarginPct: number; firePointPct: number };
+	readonly safetyRange: readonly [number, number];
+	readonly fireRange: readonly [number, number];
+	readonly onSave: (
+		modelId: string,
+		safetyMarginPct: number,
+		firePointPct: number,
+	) => Promise<void>;
+	readonly onReset: (modelId: string) => Promise<void>;
+	readonly saving: boolean;
+}): React.ReactElement {
+	const [safety, setSafety] = useState(model.threshold.safetyMarginPct);
+	const [fire, setFire] = useState(model.threshold.firePointPct);
+	const [dirty, setDirty] = useState(false);
+	const [err, setErr] = useState<string | null>(null);
+
+	// Re-sync when the server data changes (e.g. after reset).
+	useEffect(() => {
+		setSafety(model.threshold.safetyMarginPct);
+		setFire(model.threshold.firePointPct);
+		setDirty(false);
+	}, [model.threshold.safetyMarginPct, model.threshold.firePointPct]);
+
+	const safetyWarning =
+		safety < 5
+			? `Low safety margin — risks "conversation too long" errors when a single turn injects a large tool output between gate fires.`
+			: undefined;
+	const fireWarning =
+		fire > 85
+			? `High fire point — compaction may trigger close to the window cap; a single large turn can overshoot before the gate fires.`
+			: undefined;
+
+	const save = useCallback(async () => {
+		setErr(null);
+		try {
+			await onSave(model.modelId, safety, fire);
+			setDirty(false);
+		} catch (e) {
+			setErr(e instanceof Error ? e.message : String(e));
+		}
+	}, [model.modelId, safety, fire, onSave]);
+
+	return (
+		<div className="rounded-md border border-border bg-bg-elevated/30 p-3">
+			<div className="mb-2 flex items-start justify-between">
+				<div>
+					<div className="flex items-center gap-2">
+						<span className="text-sm font-semibold text-fg">
+							{model.modelName ?? model.modelId}
+						</span>
+						{model.threshold.isOverride && (
+							<span
+								className="rounded border border-primary/40 bg-primary/15 px-1.5 py-0.5 text-[10px] font-semibold uppercase text-primary"
+								title="This model has a custom override (not the default)"
+							>
+								Override
+							</span>
+						)}
+					</div>
+					<div className="text-[11px] text-fg-muted">
+						{model.provider} · {fmtWindow(model.contextWindow)} window ·{" "}
+						{fmtWindow(model.maxTokens)} output
+					</div>
+				</div>
+				<div className="text-right text-[11px] text-fg-muted">
+					<div>
+						Usable tail:{" "}
+						<span className="font-mono text-fg">
+							{usableTail(model.contextWindow, model.maxTokens, safety)}
+						</span>
+					</div>
+					<div>
+						Compaction fires at:{" "}
+						<span className="font-mono text-fg">
+							{fmtWindow(Math.ceil(model.contextWindow * (fire / 100)))}
+						</span>
+					</div>
+				</div>
+			</div>
+			<div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+				<ThresholdSlider
+					label="Safety margin"
+					value={safety}
+					min={safetyRange[0]}
+					max={safetyRange[1]}
+					onChange={(v) => {
+						setSafety(v);
+						setDirty(true);
+					}}
+					warning={safetyWarning}
+				/>
+				<ThresholdSlider
+					label="Fire point"
+					value={fire}
+					min={fireRange[0]}
+					max={fireRange[1]}
+					onChange={(v) => {
+						setFire(v);
+						setDirty(true);
+					}}
+					warning={fireWarning}
+				/>
+			</div>
+			<div className="mt-2 flex items-center gap-2">
+				<button
+					type="button"
+					onClick={save}
+					disabled={!dirty || saving}
+					className="rounded-md bg-primary px-2.5 py-1 text-xs font-semibold text-primary-fg disabled:cursor-not-allowed disabled:opacity-50"
+				>
+					{dirty ? "Save override" : "Saved"}
+				</button>
+				{model.threshold.isOverride && (
+					<button
+						type="button"
+						onClick={() => onReset(model.modelId)}
+						disabled={saving}
+						className="rounded-md border border-border px-2.5 py-1 text-xs text-fg-muted disabled:cursor-not-allowed disabled:opacity-50"
+					>
+						Reset to default ({defaults.safetyMarginPct}% /{" "}
+						{defaults.firePointPct}%)
+					</button>
+				)}
+				{err && <span className="text-[11px] text-error">{err}</span>}
+			</div>
+		</div>
+	);
+}
+
+export default function ThresholdsPanel(): React.ReactElement {
+	const [data, setData] = useState<ModelThresholdsResponse | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+	const [saving, setSaving] = useState(false);
+
+	const load = useCallback(async () => {
+		try {
+			setError(null);
+			setData(await fetchModelThresholds());
+		} catch (e) {
+			setError(e instanceof Error ? e.message : String(e));
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	useEffect(() => {
+		load();
+	}, [load]);
+
+	const onSave = useCallback(
+		async (modelId: string, safetyMarginPct: number, firePointPct: number) => {
+			setSaving(true);
+			try {
+				await putModelThreshold({ modelId, safetyMarginPct, firePointPct });
+				await load();
+			} finally {
+				setSaving(false);
+			}
+		},
+		[load],
+	);
+
+	const onReset = useCallback(
+		async (modelId: string) => {
+			setSaving(true);
+			try {
+				await deleteModelThreshold(modelId);
+				await load();
+			} finally {
+				setSaving(false);
+			}
+		},
+		[load],
+	);
+
+	if (loading)
+		return <div className="p-4 text-sm text-fg-muted">Loading thresholds…</div>;
+	if (error)
+		return <div className="p-4 text-sm text-error">Error: {error}</div>;
+	if (!data) return <div className="p-4 text-sm text-fg-muted">No data.</div>;
+
+	return (
+		<div className="flex flex-col gap-4">
+			<div className="rounded-md border border-border bg-bg-elevated/20 p-3">
+				<h3 className="text-sm font-semibold">
+					Per-Model Compaction Thresholds
+				</h3>
+				<p className="mt-1 text-[11px] text-fg-muted">
+					Tune when compaction fires + how much safety margin to reserve,
+					<strong> per model</strong>. Different providers' models range from 8K
+					to 1M+ context — one global % is wrong. Defaults:{" "}
+					<span className="font-mono">
+						{data.defaults.safetyMarginPct}% safety
+					</span>{" "}
+					/{" "}
+					<span className="font-mono">{data.defaults.firePointPct}% fire</span>.
+					Values outside the safe band show warnings.
+				</p>
+			</div>
+			{data.models.length === 0 ? (
+				<div className="rounded-md border border-border p-4 text-sm text-fg-muted">
+					No models captured yet. Start a pi session in any repo to populate
+					model snapshots, then return here to tune per-model thresholds.
+				</div>
+			) : (
+				<div className="flex flex-col gap-3">
+					{data.models.map((m) => (
+						<ModelThresholdRow
+							key={m.modelId}
+							model={m}
+							defaults={data.defaults}
+							safetyRange={data.defaults.safetyMarginRange}
+							fireRange={data.defaults.firePointRange}
+							onSave={onSave}
+							onReset={onReset}
+							saving={saving}
+						/>
+					))}
+				</div>
+			)}
+		</div>
+	);
+}

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

@@ -13,12 +13,19 @@ import GameTab from "./GameTab";
 import AchievementsTab from "./AchievementsTab";
 import ConfigTab from "./ConfigTab";
 import EmbedderSetup from "./SetupTab/EmbedderSetup";
+import ThresholdsPanel from "./SetupTab/ThresholdsPanel";
 import { Toggle } from "../components/ui/toggle";
 
-type SetupSubTab = "embedder" | "config" | "game" | "achievements";
+type SetupSubTab =
+	| "embedder"
+	| "thresholds"
+	| "config"
+	| "game"
+	| "achievements";
 
 const SUB_TABS: ReadonlyArray<{ id: SetupSubTab; label: string }> = [
 	{ id: "embedder", label: "Embedder" },
+	{ id: "thresholds", label: "Thresholds" },
 	{ id: "config", label: "Config" },
 	{ id: "game", label: "Game Mode" },
 	{ id: "achievements", label: "Achievements" },
@@ -45,6 +52,7 @@ export default function SetupTab(): React.ReactElement {
 			</nav>
 
 			{subTab === "embedder" && <EmbedderSetup />}
+			{subTab === "thresholds" && <ThresholdsPanel />}
 			{subTab === "config" && <ConfigTab />}
 			{subTab === "game" && <GameTab />}
 			{subTab === "achievements" && <AchievementsTab />}

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

@@ -15,9 +15,17 @@ import type { IndexesSummaryResponse } from "../multi-repo.js";
 import type { GameStateResponse } from "../game.js";
 import type { SseEvent } from "../index.js";
 import type { ProviderCacheResponse } from "../provider-cache.js";
-import type { RaptorTreeResponse, RaptorBuildHistoryResponse } from "../raptor.js";
+import type {
+	RaptorTreeResponse,
+	RaptorBuildHistoryResponse,
+} from "../raptor.js";
 import type { MemoryStatusResponse } from "../memory.js";
-import type { SetupStatusResponse, SetupDetectResponse, SetupConfigureRequest, SetupConfigureResponse } from "../setup.js";
+import type {
+	SetupStatusResponse,
+	SetupDetectResponse,
+	SetupConfigureRequest,
+	SetupConfigureResponse,
+} from "../setup.js";
 import type { EmbedderHealthResponse } from "../embedder-health.js";
 import type {
 	RagSettingsResponse,
@@ -25,6 +33,7 @@ import type {
 	RagSettingsResponsePost,
 } from "../rag-settings.js";
 import type { RagMetricsResponse } from "../rag-metrics.js";
+import type { ModelThresholdsResponse } from "../model-thresholds.js";
 import type {
 	TurnsResponse,
 	ConversationTurnsResponse,
@@ -192,7 +201,11 @@ export const ENDPOINTS = {
 		path: "/api/perf/samples",
 		description:
 			"Raw perf_samples for one kind (time-series drill-down across any perf metric).",
-	} as const satisfies EndpointDef<"GET", PerfSamplesQuery, PerfSamplesResponse>,
+	} as const satisfies EndpointDef<
+		"GET",
+		PerfSamplesQuery,
+		PerfSamplesResponse
+	>,
 
 	/** GET /api/achievements — Achievement tiles with unlock state. */
 	achievements: {
@@ -329,8 +342,7 @@ export const ENDPOINTS = {
 	topicTimeline: {
 		method: "GET",
 		path: "/api/wiki/topic/:topicId/timeline",
-		description:
-			"Per-topic memory-assignment timeline buckets for charts.",
+		description: "Per-topic memory-assignment timeline buckets for charts.",
 	} as const satisfies EndpointDef<"GET", undefined, TopicTimelineResponse>,
 
 	/** GET /api/wiki/evolution — node/edge D3 evolution graph. */
@@ -380,16 +392,15 @@ export const ENDPOINTS = {
 			"Lifetime provider prompt cache hit-rate aggregates + dollar savings estimate.",
 	} as const satisfies EndpointDef<"GET", undefined, ProviderCacheResponse>,
 
+	// ─── A3 Cache Stripes (PLAN_V2 Phase 4) ───────────────────────────
 
-		// ─── A3 Cache Stripes (PLAN_V2 Phase 4) ───────────────────────────
-
-		/** GET /api/cache-stripes — Per-stripe distribution + health score. */
-		cacheStripes: {
-			method: "GET",
-			path: "/api/cache-stripes",
-			description:
-				"Per-stripe distribution counts, average stability scores, and composite cache health.",
-		} as const satisfies EndpointDef<"GET", undefined, CacheStripesResponse>,
+	/** GET /api/cache-stripes — Per-stripe distribution + health score. */
+	cacheStripes: {
+		method: "GET",
+		path: "/api/cache-stripes",
+		description:
+			"Per-stripe distribution counts, average stability scores, and composite cache health.",
+	} as const satisfies EndpointDef<"GET", undefined, CacheStripesResponse>,
 	// ─── Memory Effectiveness (S53B) ───────────────────────────────────────
 
 	/** GET /api/memory-status — Memory store aggregate statistics. */
@@ -422,7 +433,11 @@ export const ENDPOINTS = {
 		path: "/api/setup-configure",
 		description:
 			"Write the chosen embedder configuration to .mega-compact.env (loaded at next startup). Returns whether a restart is required.",
-	} as const satisfies EndpointDef<"POST", SetupConfigureRequest, SetupConfigureResponse>,
+	} as const satisfies EndpointDef<
+		"POST",
+		SetupConfigureRequest,
+		SetupConfigureResponse
+	>,
 
 	// ─── RAPTOR tree (Part B) ───────────────────────────────────────
 
@@ -440,7 +455,11 @@ export const ENDPOINTS = {
 		path: "/api/raptor-build-history",
 		description:
 			"RAPTOR build history rows (node/leaf count, depth, coherence score, timed_out) for a session; defaults to the latest session with builds.",
-	} as const satisfies EndpointDef<"GET", undefined, RaptorBuildHistoryResponse>,
+	} as const satisfies EndpointDef<
+		"GET",
+		undefined,
+		RaptorBuildHistoryResponse
+	>,
 
 	/** GET /api/embedder-health — Round-trip a test embed through the active embedder. */
 	embedderHealth: {
@@ -466,7 +485,11 @@ export const ENDPOINTS = {
 		path: "/api/rag-settings",
 		description:
 			"Update RAG feature flag states by writing _DISABLED env vars to .mega-compact.env.",
-	} as const satisfies EndpointDef<"POST", RagSettingsRequest, RagSettingsResponsePost>,
+	} as const satisfies EndpointDef<
+		"POST",
+		RagSettingsRequest,
+		RagSettingsResponsePost
+	>,
 
 	// ─── RAG Metrics (Sprint H2) ──────────────────────────────────────
 
@@ -477,4 +500,14 @@ export const ENDPOINTS = {
 		description:
 			"HyDE invocation + recall-quality telemetry: flags, totals, recent turns, and daily series.",
 	} as const satisfies EndpointDef<"GET", undefined, RagMetricsResponse>,
+
+	// ─── Per-model compaction thresholds (S52 / v0.16.1) ───────────────
+
+	/** GET /api/model-thresholds — List known models + their thresholds. */
+	modelThresholds: {
+		method: "GET",
+		path: "/api/model-thresholds",
+		description:
+			"Every known model (from model_snapshots) with its per-model threshold override (or defaults).",
+	} as const satisfies EndpointDef<"GET", undefined, ModelThresholdsResponse>,
 } as const;

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

@@ -230,7 +230,14 @@ export type {
 export type { MemoryStatusResponse, MemoryStatsTopMemory } from "./memory.js";
 
 // Setup wizard — embedder configuration + backend detection
-export type { SetupStatusResponse, SetupDetectResponse, SetupConfigureRequest, SetupConfigureResponse, DetectResult, OllamaDetectResult } from "./setup.js";
+export type {
+	SetupStatusResponse,
+	SetupDetectResponse,
+	SetupConfigureRequest,
+	SetupConfigureResponse,
+	DetectResult,
+	OllamaDetectResult,
+} from "./setup.js";
 
 // Embedder health probe
 export type { EmbedderHealthResponse } from "./embedder-health.js";
@@ -245,7 +252,12 @@ export type {
 } from "./memory-map.js";
 
 // Part B — RAPTOR tree + build history
-export type { RaptorNodeDTO, RaptorTreeResponse, RaptorBuildHistoryDTO, RaptorBuildHistoryResponse } from "./raptor.js";
+export type {
+	RaptorNodeDTO,
+	RaptorTreeResponse,
+	RaptorBuildHistoryDTO,
+	RaptorBuildHistoryResponse,
+} from "./raptor.js";
 
 // A3 — cache stripe distribution + health
 export type {
@@ -288,4 +300,17 @@ export type {
 	SseWikiTopicSplit,
 	WikiSseEvent,
 } from "./wiki.js";
-export type { CurationResult, OverrideKind, WikiCurationStore } from "../../../src/wiki/curation.js";
+export type {
+	CurationResult,
+	OverrideKind,
+	WikiCurationStore,
+} from "../../../src/wiki/curation.js";
+export type {
+	ModelThresholdDTO,
+	KnownModel,
+	ModelThresholdsResponse,
+	ModelThresholdPutRequest,
+	ModelThresholdPutResponse,
+	ModelThresholdDeleteResponse,
+	ModelThresholdsError,
+} from "./model-thresholds.js";