pi-mega-compact 0.11.4 → 0.11.6

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

@@ -0,0 +1,27 @@
+/**
+ * api-contracts/memory.ts — Memory effectiveness stats contract (S53B).
+ *
+ * Response shape for GET /api/memory-status: aggregate memory-store statistics
+ * including total count, 30-day window, top-N stable memories by recall, and
+ * average recall score.
+ */
+
+export interface MemoryStatsTopMemory {
+	readonly id: number;
+	readonly text: string;
+	/** Number of times the memory was injected at a turn (turn_recall.source='memory'). */
+	readonly recallCount: number;
+	/** Unix timestamp (seconds) of last recall, or null if never. */
+	readonly lastRecalledAt: number | null;
+}
+
+/** Response body for GET /api/memory-status. */
+export interface MemoryStatusResponse {
+	readonly totalMemories: number;
+	/** Memories created within the last 30 days. */
+	readonly memoriesInLast30Days: number;
+	/** Top-N memories sorted by recallCount descending. */
+	readonly topStableMemories: MemoryStatsTopMemory[];
+	/** Mean recallCount across all recalled memories (0 when none). */
+	readonly avgRecallScore: number;
+}

package/extensions/dashboard-server/api-contracts/multi-repo.ts

@@ -15,18 +15,18 @@
  * Represents a single repository in the multi-repo index list.
  */
 export interface RepoListItem {
-  /** Unique repository identifier. */
-  id: string;
-  /** Filesystem path to the repository root. */
-  path: string;
-  /** Human-readable repository display name. */
-  name: string;
-  /** Number of sessions recorded for this repository. */
-  sessionCount: number;
-  /** Total token count across all sessions for this repository (tokens). */
-  tokenTotal: number;
-  /** Epoch timestamp of the last activity for this repository (milliseconds since Unix epoch). */
-  lastSeen: number;
+	/** Unique repository identifier. */
+	id: string;
+	/** Filesystem path to the repository root. */
+	path: string;
+	/** Human-readable repository display name. */
+	name: string;
+	/** Number of sessions recorded for this repository. */
+	sessionCount: number;
+	/** Total token count across all sessions for this repository (tokens). */
+	tokenTotal: number;
+	/** Epoch timestamp of the last activity for this repository (milliseconds since Unix epoch). */
+	lastSeen: number;
 }
 
 // ─── /api/repo-snapshot ────────────────────────────────────────────────────
@@ -38,83 +38,83 @@ export interface RepoListItem {
  * store, compression, and model information.
  */
 export interface RepoSnapshotEntry {
-  /** ISO 8601 timestamp of the last update, or `null` if never updated. */
-  updatedAt: string | null;
-  /** Currently active compaction tier name for this repo. */
-  tier: string;
-  /** Preset (default) compaction tier name for this repo. */
-  presetTier: string;
-  /** Current context pressure for this repo (percent, 0–100). */
-  pressure: number;
-  /** Session state for this repo. */
-  session: {
-    /** Active session ID, or `null` when no session is active. */
-    id: string | null;
-    /** Session lifecycle state (e.g. `'idle'`, `'compacting'`), or `null` when no session is active. */
-    state: string | null;
-  };
-  /** Context window utilization for this repo. */
-  context: {
-    /** Current token count, or `null` if unknown (tokens). */
-    tokens: number | null;
-    /** Context window usage, or `null` if unknown (percent, 0–100). */
-    percent: number | null;
-    /** Maximum context window size for the active model (tokens). */
-    contextWindow: number;
-  };
-  /** Store metrics for this repo. */
-  store: {
-    /** Number of checkpoints for this repo. */
-    checkpointCount: number;
-    /** Tokens saved for this repo (tokens). */
-    tokensSaved: number;
-    /** Number of duplicate chunks collapsed for this repo. */
-    dedupCollapsed: number;
-    /** Storage deduplication rate for this repo (percent, 0–100). */
-    storageDedupRate: number;
-  };
-  /** Compression statistics for this repo. */
-  compression: {
-    /** Session-level compression. */
-    session: {
-      /** Input tokens for the session (tokens). */
-      tokensIn: number;
-      /** Output tokens after compression (tokens). */
-      tokensOut: number;
-      /** Tokens freed by compression (tokens). */
-      tokensFreed: number;
-      /** Compression ratio (percent, 0–100). */
-      compressionPct: number;
-      /** Dedup contribution (percent, 0–100). */
-      dedupPct: number;
-    };
-    /** Repo-level compression. */
-    repo: {
-      /** Input tokens for the repo (tokens). */
-      tokensIn: number;
-      /** Output tokens after compression (tokens). */
-      tokensOut: number;
-      /** Tokens freed by compression (tokens). */
-      tokensFreed: number;
-      /** Compression ratio (percent, 0–100). */
-      compressionPct: number;
-      /** Dedup contribution (percent, 0–100). */
-      dedupPct: number;
-    };
-  };
-  /** Active model information for this repo. Present when a model is configured; absent otherwise. */
-  model?: {
-    /** Model name/identifier. */
-    name: string;
-    /** Machine-readable provider identifier. */
-    provider: string;
-    /** Human-readable provider name. */
-    providerName: string;
-    /** Model input processing rate (tokens per second). */
-    inputRate: number;
-    /** Model output processing rate (tokens per second). */
-    outputRate: number;
-  };
+	/** ISO 8601 timestamp of the last update, or `null` if never updated. */
+	updatedAt: string | null;
+	/** Currently active compaction tier name for this repo. */
+	tier: string;
+	/** Preset (default) compaction tier name for this repo. */
+	presetTier: string;
+	/** Current context pressure for this repo (percent, 0–100). */
+	pressure: number;
+	/** Session state for this repo. */
+	session: {
+		/** Active session ID, or `null` when no session is active. */
+		id: string | null;
+		/** Session lifecycle state (e.g. `'idle'`, `'compacting'`), or `null` when no session is active. */
+		state: string | null;
+	};
+	/** Context window utilization for this repo. */
+	context: {
+		/** Current token count, or `null` if unknown (tokens). */
+		tokens: number | null;
+		/** Context window usage, or `null` if unknown (percent, 0–100). */
+		percent: number | null;
+		/** Maximum context window size for the active model (tokens). */
+		contextWindow: number;
+	};
+	/** Store metrics for this repo. */
+	store: {
+		/** Number of checkpoints for this repo. */
+		checkpointCount: number;
+		/** Tokens saved for this repo (tokens). */
+		tokensSaved: number;
+		/** Number of duplicate chunks collapsed for this repo. */
+		dedupCollapsed: number;
+		/** Storage deduplication rate for this repo (percent, 0–100). */
+		storageDedupRate: number;
+	};
+	/** Compression statistics for this repo. */
+	compression: {
+		/** Session-level compression. */
+		session: {
+			/** Input tokens for the session (tokens). */
+			tokensIn: number;
+			/** Output tokens after compression (tokens). */
+			tokensOut: number;
+			/** Tokens freed by compression (tokens). */
+			tokensFreed: number;
+			/** Compression ratio (percent, 0–100). */
+			compressionPct: number;
+			/** Dedup contribution (percent, 0–100). */
+			dedupPct: number;
+		};
+		/** Repo-level compression. */
+		repo: {
+			/** Input tokens for the repo (tokens). */
+			tokensIn: number;
+			/** Output tokens after compression (tokens). */
+			tokensOut: number;
+			/** Tokens freed by compression (tokens). */
+			tokensFreed: number;
+			/** Compression ratio (percent, 0–100). */
+			compressionPct: number;
+			/** Dedup contribution (percent, 0–100). */
+			dedupPct: number;
+		};
+	};
+	/** Active model information for this repo. Present when a model is configured; absent otherwise. */
+	model?: {
+		/** Model name/identifier. */
+		name: string;
+		/** Machine-readable provider identifier. */
+		provider: string;
+		/** Human-readable provider name. */
+		providerName: string;
+		/** Model input processing rate (tokens per second). */
+		inputRate: number;
+		/** Model output processing rate (tokens per second). */
+		outputRate: number;
+	};
 }
 
 /**
@@ -134,50 +134,50 @@ export type RepoSnapshotMap = Record<string, RepoSnapshotEntry | null>;
  * compression, model, and configuration details.
  */
 export interface IndexesIndexRow {
-  /** Filesystem path to the repository root. */
-  repoRoot: string;
-  /** Human-readable display name for the repository. */
-  displayName: string;
-  /** State directory path for this repo's mega-compact data. */
-  stateDir: string;
-  /** Number of checkpoints stored for this repo. */
-  checkpointCount: number;
-  /** Total tokens saved for this repo (tokens). */
-  tokensSaved: number;
-  /** Original byte size of compressed data (bytes). */
-  compressedOriginalBytes: number;
-  /** Epoch timestamp of the last compaction, or `null` if never compacted (milliseconds since Unix epoch). */
-  lastCompactedAt: number | null;
-  /** Machine-readable provider identifier, or `null` if not configured. */
-  provider: string | null;
-  /** Human-readable provider name, or `null` if not configured. */
-  providerName: string | null;
-  /** Model name/identifier, or `null` if not configured. */
-  modelName: string | null;
-  /** Model input processing rate, or `null` if not configured (tokens per second). */
-  inputRate: number | null;
-  /** Model output processing rate, or `null` if not configured (tokens per second). */
-  outputRate: number | null;
-  /** Epoch timestamp of the last activity (milliseconds since Unix epoch). */
-  lastSeen: number;
-  /** Tokens retained after compaction (tokens). */
-  tokensKept: number;
-  /** Tokens dropped during compaction (tokens). */
-  tokensDropped: number;
-  /** Number of sessions recorded for this repo. */
-  sessions: number;
-  /** Maximum context window size, or `null` if not configured (tokens). */
-  contextWindow: number | null;
-  /** Maximum token limit, or `null` if not configured (tokens). */
-  maxTokens: number | null;
-  /** Whether reasoning/extended-thinking mode is enabled, or `null` if not configured. */
-  reasoning: boolean | null;
-  /** Lifetime provider prompt-cache hit percentage, or `null` if no samples. */
-  providerCachePct: number | null;
-  /** Lifetime provider prompt-cache read tokens, or `null` if no samples. */
-  providerCacheRead: number | null;
-  /** Lifetime provider prompt-cache write tokens, or `null` if no samples. */
-  providerCacheWrite: number | null;
+	/** Filesystem path to the repository root. */
+	repoRoot: string;
+	/** Human-readable display name for the repository. */
+	displayName: string;
+	/** State directory path for this repo's mega-compact data. */
+	stateDir: string;
+	/** Number of checkpoints stored for this repo. */
+	checkpointCount: number;
+	/** Total tokens saved for this repo (tokens). */
+	tokensSaved: number;
+	/** Original byte size of compressed data (bytes). */
+	compressedOriginalBytes: number;
+	/** Epoch timestamp of the last compaction, or `null` if never compacted (milliseconds since Unix epoch). */
+	lastCompactedAt: number | null;
+	/** Machine-readable provider identifier, or `null` if not configured. */
+	provider: string | null;
+	/** Human-readable provider name, or `null` if not configured. */
+	providerName: string | null;
+	/** Model name/identifier, or `null` if not configured. */
+	modelName: string | null;
+	/** Model input processing rate, or `null` if not configured (tokens per second). */
+	inputRate: number | null;
+	/** Model output processing rate, or `null` if not configured (tokens per second). */
+	outputRate: number | null;
+	/** Epoch timestamp of the last activity (milliseconds since Unix epoch). */
+	lastSeen: number;
+	/** Tokens retained after compaction (tokens). */
+	tokensKept: number;
+	/** Tokens dropped during compaction (tokens). */
+	tokensDropped: number;
+	/** Number of sessions recorded for this repo. */
+	sessions: number;
+	/** Maximum context window size, or `null` if not configured (tokens). */
+	contextWindow: number | null;
+	/** Maximum token limit, or `null` if not configured (tokens). */
+	maxTokens: number | null;
+	/** Whether reasoning/extended-thinking mode is enabled, or `null` if not configured. */
+	reasoning: boolean | null;
+	/** Lifetime provider prompt-cache hit percentage, or `null` if no samples. */
+	providerCachePct: number | null;
+	/** Lifetime provider prompt-cache read tokens, or `null` if no samples. */
+	providerCacheRead: number | null;
+	/** Lifetime provider prompt-cache write tokens, or `null` if no samples. */
+	providerCacheWrite: number | null;
 }
 
 /**
@@ -186,18 +186,18 @@ export interface IndexesIndexRow {
  * Provides an aggregated summary of all repos plus a per-repo index row list.
  */
 export interface IndexesSummaryResponse {
-  /** ISO 8601 timestamp of the last index update. */
-  updatedAt: string;
-  /** Total number of repos in the index. */
-  totalRepos: number;
-  /** Total number of checkpoints across all repos. */
-  totalCheckpoints: number;
-  /** Total tokens saved across all repos (tokens). */
-  totalTokensSaved: number;
-  /** Total original compressed byte size across all repos (bytes). */
-  totalCompressedOriginalBytes: number;
-  /** Per-repo index rows. */
-  repos: IndexesIndexRow[];
+	/** ISO 8601 timestamp of the last index update. */
+	updatedAt: string;
+	/** Total number of repos in the index. */
+	totalRepos: number;
+	/** Total number of checkpoints across all repos. */
+	totalCheckpoints: number;
+	/** Total tokens saved across all repos (tokens). */
+	totalTokensSaved: number;
+	/** Total original compressed byte size across all repos (bytes). */
+	totalCompressedOriginalBytes: number;
+	/** Per-repo index rows. */
+	repos: IndexesIndexRow[];
 }
 
 // ─── /api/indexes/diff ─────────────────────────────────────────────────────
@@ -209,26 +209,26 @@ export interface IndexesSummaryResponse {
  * current state.
  */
 export interface IndexesDiffEntry {
-  /** Unique identifier for this diff entry. */
-  id: string;
-  /**
-   * Type of change detected.
-   * Allowed values: `'add'`, `'remove'`, `'change'`.
-   */
-  type: 'add' | 'remove' | 'change';
-  /** Repository involved in the diff. Present when the change is repo-specific; absent otherwise. */
-  repo?: string;
-  /** Field name that changed. Present for `'change'` type; absent otherwise. */
-  field?: string;
-  /** Previous value of the changed field. Present for `'change'` type; absent otherwise. */
-  before?: unknown;
-  /** New value of the changed field. Present for `'change'` and `'add'` types; absent otherwise. */
-  after?: unknown;
-  /**
-   * Severity of the change.
-   * Allowed values: `'info'`, `'warn'`, `'critical'`.
-   */
-  severity: 'info' | 'warn' | 'critical';
+	/** Unique identifier for this diff entry. */
+	id: string;
+	/**
+	 * Type of change detected.
+	 * Allowed values: `'add'`, `'remove'`, `'change'`.
+	 */
+	type: "add" | "remove" | "change";
+	/** Repository involved in the diff. Present when the change is repo-specific; absent otherwise. */
+	repo?: string;
+	/** Field name that changed. Present for `'change'` type; absent otherwise. */
+	field?: string;
+	/** Previous value of the changed field. Present for `'change'` type; absent otherwise. */
+	before?: unknown;
+	/** New value of the changed field. Present for `'change'` and `'add'` types; absent otherwise. */
+	after?: unknown;
+	/**
+	 * Severity of the change.
+	 * Allowed values: `'info'`, `'warn'`, `'critical'`.
+	 */
+	severity: "info" | "warn" | "critical";
 }
 
 /**
@@ -238,13 +238,13 @@ export interface IndexesDiffEntry {
  * comparison, and optionally includes the snapshot itself.
  */
 export interface DiffRequest {
-  /**
-   * Which side is providing the snapshot for comparison.
-   * Allowed values: `'client'`, `'server'`.
-   */
-  side: 'client' | 'server';
-  /** Snapshot to compare against. Present when `side` is `'client'`; absent when `side` is `'server'` (server uses its own). */
-  snapshot?: SnapshotLike;
+	/**
+	 * Which side is providing the snapshot for comparison.
+	 * Allowed values: `'client'`, `'server'`.
+	 */
+	side: "client" | "server";
+	/** Snapshot to compare against. Present when `side` is `'client'`; absent when `side` is `'server'` (server uses its own). */
+	snapshot?: SnapshotLike;
 }
 
 /**
@@ -254,57 +254,57 @@ export interface DiffRequest {
  * for drift detection.
  */
 export interface SnapshotLike {
-  /** ISO 8601 timestamp of the snapshot, or `null`. Absent when not available. */
-  updatedAt?: string | null;
-  /** Store metrics subset. Absent when not available. */
-  store?: {
-    /** Number of checkpoints. Absent when not available. */
-    checkpointCount?: number;
-    /** Tokens saved (tokens). Absent when not available. */
-    tokensSaved?: number;
-  };
-  /** Compression statistics subset. Absent when not available. */
-  compression?: {
-    /** Repo-level compression subset. Absent when not available. */
-    repo?: {
-      /** Input tokens (tokens). Absent when not available. */
-      tokensIn?: number;
-      /** Output tokens (tokens). Absent when not available. */
-      tokensOut?: number;
-      /** Compression ratio (percent, 0–100). Absent when not available. */
-      compressionPct?: number;
-      /** Dedup contribution (percent, 0–100). Absent when not available. */
-      dedupPct?: number;
-    };
-    /** Session-level compression subset. Absent when not available. */
-    session?: {
-      /** Input tokens (tokens). Absent when not available. */
-      tokensIn?: number;
-      /** Output tokens (tokens). Absent when not available. */
-      tokensOut?: number;
-    };
-  };
-  /** Session state subset. Absent when not available. */
-  session?: {
-    /** Active session ID, or `null`. Absent when not available. */
-    id?: string | null;
-    /** Session lifecycle state, or `null`. Absent when not available. */
-    state?: string | null;
-  };
-  /** Model info subset. Absent when not available. */
-  model?: {
-    /** Model name. Absent when not available. */
-    name?: string;
-    /** Provider identifier. Absent when not available. */
-    provider?: string;
-  };
-  /** Trigger state subset. Absent when not available. */
-  trigger?: {
-    /** Whether the trigger is armed. Absent when not available. */
-    armed?: boolean;
-    /** Whether the trigger is ready. Absent when not available. */
-    ready?: boolean;
-  };
+	/** ISO 8601 timestamp of the snapshot, or `null`. Absent when not available. */
+	updatedAt?: string | null;
+	/** Store metrics subset. Absent when not available. */
+	store?: {
+		/** Number of checkpoints. Absent when not available. */
+		checkpointCount?: number;
+		/** Tokens saved (tokens). Absent when not available. */
+		tokensSaved?: number;
+	};
+	/** Compression statistics subset. Absent when not available. */
+	compression?: {
+		/** Repo-level compression subset. Absent when not available. */
+		repo?: {
+			/** Input tokens (tokens). Absent when not available. */
+			tokensIn?: number;
+			/** Output tokens (tokens). Absent when not available. */
+			tokensOut?: number;
+			/** Compression ratio (percent, 0–100). Absent when not available. */
+			compressionPct?: number;
+			/** Dedup contribution (percent, 0–100). Absent when not available. */
+			dedupPct?: number;
+		};
+		/** Session-level compression subset. Absent when not available. */
+		session?: {
+			/** Input tokens (tokens). Absent when not available. */
+			tokensIn?: number;
+			/** Output tokens (tokens). Absent when not available. */
+			tokensOut?: number;
+		};
+	};
+	/** Session state subset. Absent when not available. */
+	session?: {
+		/** Active session ID, or `null`. Absent when not available. */
+		id?: string | null;
+		/** Session lifecycle state, or `null`. Absent when not available. */
+		state?: string | null;
+	};
+	/** Model info subset. Absent when not available. */
+	model?: {
+		/** Model name. Absent when not available. */
+		name?: string;
+		/** Provider identifier. Absent when not available. */
+		provider?: string;
+	};
+	/** Trigger state subset. Absent when not available. */
+	trigger?: {
+		/** Whether the trigger is armed. Absent when not available. */
+		armed?: boolean;
+		/** Whether the trigger is ready. Absent when not available. */
+		ready?: boolean;
+	};
 }
 
 /**
@@ -313,10 +313,10 @@ export interface SnapshotLike {
  * Contains the list of detected diffs and the server's current snapshot.
  */
 export interface DiffResponse {
-  /** List of detected differences between client and server snapshots. */
-  diffs: IndexesDiffEntry[];
-  /** The server's current snapshot used as the comparison baseline. */
-  serverSnapshot: SnapshotLike;
+	/** List of detected differences between client and server snapshots. */
+	diffs: IndexesDiffEntry[];
+	/** The server's current snapshot used as the comparison baseline. */
+	serverSnapshot: SnapshotLike;
 }
 
 // ─── PUT /api/repo-config ─────────────────────────────────────────────────
@@ -327,8 +327,8 @@ export interface DiffResponse {
  * Updates display configuration for a specific repository.
  */
 export interface UpdateRepoConfigRequest {
-  /** Repository identifier to update. */
-  repoId: string;
-  /** New display name for the repository. Absent when the display name should not be changed. */
-  displayName?: string;
+	/** Repository identifier to update. */
+	repoId: string;
+	/** New display name for the repository. Absent when the display name should not be changed. */
+	displayName?: string;
 }

package/extensions/dashboard-server/api-contracts/provider-cache.ts

@@ -3,8 +3,18 @@
  *
  * Response shape for GET /api/provider-cache: lifetime cache hit-rate
  * aggregates plus optional $ savings estimate priced from model snapshots.
+ * F4 adds per-model breakdown (byModel).
  */
 
+/** Per-model cache aggregate (F4). */
+export interface ProviderCacheByModel {
+	readonly model: string;
+	readonly hitPct: number;
+	readonly totalCacheRead: number;
+	readonly totalCacheWrite: number;
+	readonly sampleCount: number;
+}
+
 /** Savings estimate derived from model pricing snapshot. */
 export interface ProviderCacheSavings {
 	readonly cacheReadSaved: number;
@@ -24,7 +34,34 @@ export interface ProviderCacheResponse {
 		readonly totalInput: number;
 		readonly firstTurnAt: string | null;
 		readonly latestTurnAt: string | null;
+		/** Per-model breakdown (F4). Empty when no model-tagged samples exist. */
+		readonly byModel: ProviderCacheByModel[];
 	};
 	readonly savings: ProviderCacheSavings | null;
 	readonly updatedAt: string;
+	/** When non-null, the response is scoped to the last N minutes. */
+	readonly windowMinutes?: number | null;
+	/** Classified prefix-break events in the queried window (S53A). */
+	readonly prefixBreaks: PrefixBreak[];
+}
+
+/** Query parameters for GET /api/provider-cache. */
+export interface ProviderCacheQuery {
+	/** Optional trailing-window minutes. When absent → lifetime. */
+	minutes?: number;
+	/** Optional lower-bound epoch ms (alternative to minutes). */
+	since?: number;
+	/** Optional upper-bound epoch ms. */
+	until?: number;
+}
+
+/** A single classified prefix-break event (S53A). */
+export interface PrefixBreak {
+	readonly id: number;
+	readonly ts: number;
+	readonly cause: "recall" | "compaction" | "inject" | "other";
+	readonly confidence: number;
+	readonly prevHitPct: number;
+	readonly currHitPct: number;
+	readonly breakAt: number;
 }