pi-mega-compact 0.11.4 → 0.11.6

package/extensions/mega-events/separated-prompt.ts

@@ -0,0 +1,329 @@
+/**
+ * extensions/mega-events/separated-prompt.ts — A1+A2 PLAN_V2 Phase 2+3
+ * Message Separation + Cache-Optimized Prompt Builder:
+ *   - buildSeparatedPrompt(): Basic 4-layer message separation (Phase 2).
+ *   - buildCacheOptimizedPrompt(): Insert Layer 2 (vector-optimized stable
+ *     context) between summary (Layer 1) and thread (Layer 3), ordered by
+ *     stripe stability DESC (Phase 3).
+ *   - detectTopicShift(): Cosine-similarity-based topic-shift detection.
+ *   - cosineSimilarity(): cosine similarity of two Float32Array embeddings.
+ *
+ * Layer order (Phase 3): 0 (system) -> 1 (summary) -> 2 (cache stripes) ->
+ * 3 (thread: user/assistant turns) -> 4 (tool results at tail).
+ *
+ * Feature-gated by MEGACOMPACT_CACHE_STRIPING (default OFF).
+ * MEGACOMPACT_MESSAGE_SEPARATION must also be ON for any layering to occur.
+ * Flag-OFF = byte-identical to pre-sprint — returns messages unchanged.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { openStore } from "../../src/store/sqlite/utils.js";
+import { getStateDir } from "../../src/store.js";
+
+// ─── Exported types ──────────────────────────────────────────────────────────
+
+export interface SeparatedPromptOptions {
+  /** Path to the SQLite store directory. Defaults to getStateDir(). */
+  stateDir?: string;
+  /** Conversation/agent ID for stripe lookups. Defaults to 'main'. */
+  conversationId?: string;
+  /** Current turn index for embedding_cache lookups. Defaults to 0. */
+  turnIndex?: number;
+}
+
+export interface CacheStripeRow {
+  chunk_id: string;
+  stripe: number;
+  stability: number;
+  assigned_at: number;
+  epoch_id: string | null;
+}
+
+export interface EmbeddingCacheRow {
+  content_hash: string;
+  embedding: Buffer;
+  computed_at: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Default stripe limit: top 10 most stable chunks. */
+const DEFAULT_STRIPE_LIMIT = 10;
+
+/** Topic-shift threshold: similarity below this triggers a stripe refresh. */
+const TOPIC_SHIFT_THRESHOLD = 0.7;
+
+// ─── Build separated prompt (Phase 2) ────────────────────────────────────────
+
+/**
+ * Reorganize messages into stable layers for better prompt caching.
+ *
+ * Layer order: 0 (system) -> 1 (summary) -> 3 (thread: user/assistant turns) ->
+ * 4 (tool results at tail).
+ *
+ * Feature gate: MEGACOMPACT_MESSAGE_SEPARATION env var.  When OFF (default),
+ * returns `messages` unchanged (byte-identical to pre-sprint).
+ */
+export function buildSeparatedPrompt(
+  messages: AgentMessage[],
+  _opts?: SeparatedPromptOptions,
+): AgentMessage[] {
+  const flag = process.env.MEGACOMPACT_MESSAGE_SEPARATION;
+  if (flag === "0" || flag === "false" || flag === undefined || flag === "") {
+    return messages;
+  }
+
+  // pi's AgentMessage union has no "system" role — the system prompt lives in
+  // AgentState.systemPrompt, separate from this array. The cache-relevant,
+  // low-risk transformation is moving volatile tool results/executions to the
+  // tail so the stable prefix (user/assistant/summaries/custom) stays contiguous.
+  // Discriminate by role only — never reach into `.content`/`.tool_calls`,
+  // which are variant-specific and require narrowing.
+  const main: AgentMessage[] = [];
+  const tail: AgentMessage[] = [];
+  for (const m of messages) {
+    if (m.role === "toolResult" || m.role === "bashExecution") {
+      tail.push(m);
+    } else {
+      main.push(m);
+    }
+  }
+  if (tail.length === 0) return messages; // nothing to reorder — byte-identical
+  return [...main, ...tail];
+}
+
+// ─── Cosine similarity ───────────────────────────────────────────────────────
+
+/**
+ * Compute cosine similarity between two Float32Array embeddings.
+ * Returns a value in [0, 1] where 1 = identical direction.
+ * Returns 0 if either vector is zero or inputs are mismatched.
+ */
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denom === 0) return 0;
+
+  return dot / denom;
+}
+
+// ─── Buffer ↔ Float32Array helpers ───────────────────────────────────────────
+
+/**
+ * Decode a Float32Array from a Buffer (little-endian float32 blob).
+ * Returns null on empty/undefined input.
+ */
+export function decodeEmbeddingBlob(buf: Buffer | undefined | null): Float32Array | null {
+  if (!buf || buf.length === 0) return null;
+  return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+
+/**
+ * Encode a Float32Array into a Buffer for DB storage.
+ */
+export function encodeEmbeddingBlob(vec: Float32Array): Buffer {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+
+// ─── Topic-shift detection ───────────────────────────────────────────────────
+
+/**
+ * Detect whether the conversation topic has shifted between the current turn
+ * and the previous turn. Uses cosine similarity between topic embeddings.
+ *
+ * Returns `true` when similarity < TOPIC_SHIFT_THRESHOLD (0.7), meaning the
+ * stable cache prefix may need reordering.
+ *
+ * Returns `false` (no shift) when either embedding is missing.
+ */
+export function detectTopicShift(
+  currentEmb: Float32Array | null | undefined,
+  previousEmb: Float32Array | null | undefined,
+): boolean {
+  if (!currentEmb || !previousEmb) return false;
+  return cosineSimilarity(currentEmb, previousEmb) < TOPIC_SHIFT_THRESHOLD;
+}
+
+// ─── Load embeddings from store ──────────────────────────────────────────────
+
+/**
+ * Load the topic embedding for a given turn from the embedding_cache table.
+ * Returns null if no embedding is stored for that turn.
+ */
+export function loadTopicEmbedding(
+  stateDir: string,
+  conversationId: string,
+  turnIndex: number,
+): Float32Array | null {
+  const db = openStore(stateDir);
+  try {
+    const row = db.prepare(
+      `SELECT embedding FROM embedding_cache WHERE content_hash = ?`,
+    ).get(`topic:${conversationId}:${turnIndex}`) as { embedding: Buffer } | undefined;
+
+    if (!row) return null;
+    return decodeEmbeddingBlob(row.embedding);
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Store a topic embedding for a given turn in the embedding_cache table.
+ * Idempotent (INSERT OR REPLACE).
+ */
+export function storeTopicEmbedding(
+  stateDir: string,
+  conversationId: string,
+  turnIndex: number,
+  embedding: Float32Array,
+): void {
+  const db = openStore(stateDir);
+  try {
+    const contentHash = `topic:${conversationId}:${turnIndex}`;
+    const blob = encodeEmbeddingBlob(embedding);
+    db.prepare(
+      `INSERT OR REPLACE INTO embedding_cache (content_hash, embedding, computed_at) VALUES (?, ?, ?)`,
+    ).run(contentHash, blob, Date.now());
+  } finally {
+    db.close();
+  }
+}
+
+// ─── Cache stripe management ─────────────────────────────────────────────────
+
+/**
+ * Refresh cache stripe assignments from the cache_stripes table for a given
+ * conversation/epoch. Returns rows ordered by stability DESC.
+ *
+ * This is called at the start of each turn (or on topic-shift) to ensure the
+ * stripe assignments reflect the latest stability scores.
+ */
+export function refreshStripeAssignments(
+  stateDir: string,
+  epochId: string,
+  limit = DEFAULT_STRIPE_LIMIT,
+): CacheStripeRow[] {
+  const db = openStore(stateDir);
+  try {
+    const rows = db.prepare(
+      `SELECT chunk_id, stripe, stability, assigned_at, epoch_id
+       FROM cache_stripes
+       WHERE epoch_id = ?
+       ORDER BY stability DESC
+       LIMIT ?`,
+    ).all(epochId, limit) as unknown as CacheStripeRow[];
+
+    return rows;
+  } finally {
+    db.close();
+  }
+}
+
+// ─── Build cache-optimized prompt (Phase 3) ──────────────────────────────────
+
+/**
+ * Build a cache-optimized prompt with 5 layers:
+ *   0 (system) -> 1 (summary) -> 2 (cache stripes) -> 3 (thread) -> 4 (tool)
+ *
+ * Feature gate: MEGACOMPACT_CACHE_STRIPING (default OFF). When OFF, delegates
+ * to buildSeparatedPrompt (byte-identical to Phase 2 behavior).
+ *
+ * When ON but MEGACOMPACT_MESSAGE_SEPARATION is OFF, also delegates to
+ * buildSeparatedPrompt (which returns messages unchanged).
+ */
+export function buildCacheOptimizedPrompt(
+  messages: AgentMessage[],
+  opts?: SeparatedPromptOptions,
+): AgentMessage[] {
+  const flag = process.env.MEGACOMPACT_CACHE_STRIPING;
+  if (flag === "0" || flag === "false" || flag === undefined || flag === "") {
+    // Flag OFF: delegate to buildSeparatedPrompt (byte-identical).
+    return buildSeparatedPrompt(messages, opts);
+  }
+
+  // Build the base 4-layer structure first.
+  const base = buildSeparatedPrompt(messages, opts);
+
+  // If base equals messages, separation is OFF — return unchanged.
+  if (base === messages) return base;
+
+  const stateDir = opts?.stateDir ?? getStateDir();
+
+  // Layer 1 = leading branch/compaction summaries (the stable summary layer).
+  // There is no "system" role in pi's AgentMessage union, so Layer 0 is empty.
+  // Count leading summaries to find where to insert the cache-stripe layer.
+  let layer1End = 0;
+  for (let i = 0; i < base.length; i++) {
+    const r = base[i].role;
+    if (r === "branchSummary" || r === "compactionSummary") {
+      layer1End = i + 1;
+    } else {
+      break;
+    }
+  }
+
+  // Lay out the result: Layer 1 (summaries) first.
+  const result: AgentMessage[] = base.slice(0, layer1End);
+
+  // Insert Layer 2: cache stripes (stable context ordered by stability DESC).
+  // Try to find the most recent epoch.
+  const db = openStore(stateDir);
+  let epochId: string | null = null;
+  try {
+    const epoch = db.prepare(
+      `SELECT epoch_id FROM checkpoint_epochs ORDER BY created_at DESC LIMIT 1`,
+    ).get() as { epoch_id: string } | undefined;
+    epochId = epoch?.epoch_id ?? null;
+  } finally {
+    db.close();
+  }
+
+  if (epochId) {
+    const stripes = refreshStripeAssignments(stateDir, epochId);
+    if (stripes.length > 0) {
+      // Build a single user message with concatenated stripe content.
+      const stripeBlocks: string[] = [];
+      for (const s of stripes) {
+        // Load chunk content from context_chunks table.
+        const db2 = openStore(stateDir);
+        try {
+          const chunk = db2.prepare(
+            `SELECT normalized_text FROM context_chunks WHERE id = ?`,
+          ).get(s.chunk_id) as { normalized_text: string } | undefined;
+          if (chunk?.normalized_text) {
+            stripeBlocks.push(chunk.normalized_text);
+          }
+        } finally {
+          db2.close();
+        }
+      }
+
+      if (stripeBlocks.length > 0) {
+        result.push({
+          role: "user",
+          content: stripeBlocks.join("\n\n---\n\n"),
+          timestamp: Date.now(),
+        } as AgentMessage);
+      }
+    }
+  }
+
+  // Append remaining layers (3: thread, 4: tool results).
+  for (let i = layer1End; i < base.length; i++) {
+    result.push(base[i]);
+  }
+
+  return result;
+}

package/extensions/mega-events/session-handlers.ts

@@ -169,13 +169,20 @@ export function registerSessionHandlers(
 		} catch {
 			/* non-fatal: intent polling never breaks the agent loop */
 		}
-		const cpBlock = runtime.pendingRecallBlock;
-		const memBlock = runtime.pendingMemoryRecallBlock;
-		if (!cpBlock && !memBlock) return;
-		runtime.pendingRecallBlock = undefined;
-		runtime.pendingMemoryRecallBlock = undefined;
-		const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
-		return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
+		// S53: when recallTailInject is ON, the staged blocks are injected as a
+		// user-role tail message by the context handler (recall-tail.ts), NOT
+		// here. This prepend path is the legacy behavior (flag OFF = byte-
+		// identical pre-sprint). captureModel + rewind-intent consumption above
+		// stay unconditional regardless of the flag.
+		if (!config.recallTailInject) {
+			const cpBlock = runtime.pendingRecallBlock;
+			const memBlock = runtime.pendingMemoryRecallBlock;
+			if (!cpBlock && !memBlock) return;
+			runtime.pendingRecallBlock = undefined;
+			runtime.pendingMemoryRecallBlock = undefined;
+			const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
+			return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
+		}
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {

package/extensions/mega-runtime/env-loader.ts

@@ -0,0 +1,55 @@
+/**
+ * mega-runtime/env-loader.ts — load `.mega-compact.env` from the state dir.
+ *
+ * The /mega-setup wizard and the dashboard Setup tab write a `.mega-compact.env`
+ * file with the user's chosen embedder configuration. Without a loader, that
+ * file is write-only dead weight — config is read from process.env at startup
+ * (mega-config.ts:loadConfig), so the file was never applied.
+ *
+ * This loader runs BEFORE loadConfig in the extension entry. It parses the
+ * file (KEY=VALUE lines, # comments, quoted values) and applies each key to
+ * process.env ONLY if it is not already set — so shell profile / inline env
+ * vars always win over the file (the user can override without editing it).
+ *
+ * Non-fatal: a missing or malformed file never breaks the extension.
+ *
+ * PREVENT-PI-004: reads a local file only — no network.
+ * PREVENT-001: no JSON here; line parser is null/empty-safe.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Load `.mega-compact.env` from `stateDir` into `process.env`.
+ * Keys already set in the environment win (file does not override shell).
+ */
+export function loadMegaEnv(stateDir: string): void {
+	const envPath = join(stateDir, ".mega-compact.env");
+	if (!existsSync(envPath)) return;
+	let content: string;
+	try {
+		content = readFileSync(envPath, "utf-8");
+	} catch {
+		return; // unreadable — non-fatal
+	}
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eq = trimmed.indexOf("=");
+		if (eq < 0) continue;
+		const key = trimmed.slice(0, eq).trim();
+		if (!key) continue;
+		let val = trimmed.slice(eq + 1).trim();
+		if (
+			(val.startsWith('"') && val.endsWith('"')) ||
+			(val.startsWith("'") && val.endsWith("'"))
+		) {
+			val = val.slice(1, -1);
+		}
+		// Shell / inline env vars win over the file.
+		if (process.env[key] === undefined) {
+			process.env[key] = val;
+		}
+	}
+}

package/extensions/mega-runtime/helpers.ts

@@ -37,6 +37,13 @@ export interface SessionRuntime {
 	dedupAttempts: number; // total compaction attempts (for hit-rate denominator)
 	tokensSaved: number; // this session-instance only: reset on session_start
 	lastCompactAt: number | null; // wall-clock ms of the last compaction this session
+	// S53A: prefix-break classification timestamps (wall-clock ms).
+	lastRecallAt: number | null; // last recall injection this session
+	lastInjectAt: number | null; // last tail injection this session
+	// S53A: previous cache_hit_pct for drop detection.
+	_prevCacheHitPct: number | null;
+	// A3: rolling cache health score (0-1) cached between turns for trend detection.
+	_lastCacheHealthScore: number | undefined;
 	lastNativeCompactAt: number | null; // COMPACT-DEDUP FIX: wall-clock ms of the last NATIVE pi compaction (session_compact event) — used by the agent_end/legacy race guard to skip a redundant ctx.compact() that would throw "Already compacted".
 	// S25: live dashboard counters (reset on session_start, mirrored to SQLite).
 	compactCount: number; // compactions performed this session-instance
@@ -72,8 +79,15 @@ export interface SessionRuntime {
 	// R3c: one guarded compact per error signature (avoids re-compacting the
 	// same poisoned region repeatedly).
 	poisonedCompactSignatures: Set<string>; // signatures already attempted a compact for
+	// S53: recall tail injection state — tracks whether a tail was injected this turn.
+	recallInjectedThisTurn: boolean;
 	// R7: poisoned-context event counter for the dashboard.
 	poisonedCount: number;
+	// R13: set when the extension sends a nudge (error-retry, resume, compact)
+	// that will trigger the next turn. The turn_end handler checks this flag and
+	// skips error classification for extension-initiated turns — prevents the
+	// feedback loop where our own nudges get misclassified as errors.
+	extensionInitiatedTurn: boolean;
 }
 
 // ── ownVersion ─────────────────────────────────────────────────────────────

package/extensions/mega-runtime/reset-runtime.ts

@@ -54,6 +54,10 @@ export function resetRuntimeImpl(
 		dedupAttempts: 0,
 		tokensSaved: 0,
 		lastCompactAt: null,
+		lastRecallAt: null,
+		lastInjectAt: null,
+		_prevCacheHitPct: null,
+		_lastCacheHealthScore: undefined,
 		lastNativeCompactAt: null,
 		compactCount: 0,
 		recallInjections: 0,
@@ -70,7 +74,9 @@ export function resetRuntimeImpl(
 		poisonedAdviseSent: false,
 		providerOutageAdvised: false,
 		poisonedCompactSignatures: new Set(),
+		recallInjectedThisTurn: false,
 		poisonedCount: 0,
+		extensionInitiatedTurn: false,
 	};
 	self.trimCache = null; // v0.8.6: never replay a stale trim into a new session
 	self.statusKey = undefined;

package/extensions/mega-runtime/runtime-snapshot.ts

@@ -267,6 +267,7 @@ export function snapshotImpl(
 			armed,
 			modelSnap,
 			providerCachePct,
+			perTurnCacheHitPct: self.rt._prevCacheHitPct ?? undefined,
 		});
 		self.widgetData = _snapResult.widgetData;
 		// S33: consume the flare after copying it into widgetData so it fires

package/extensions/mega-runtime/runtime.ts

@@ -87,6 +87,10 @@ export class MegaRuntime {
 		dedupAttempts: 0,
 		tokensSaved: 0,
 		lastCompactAt: null,
+		lastRecallAt: null,
+		lastInjectAt: null,
+		_prevCacheHitPct: null,
+		_lastCacheHealthScore: undefined,
 		lastNativeCompactAt: null,
 		compactCount: 0,
 		recallInjections: 0,
@@ -103,7 +107,10 @@ export class MegaRuntime {
 		poisonedAdviseSent: false,
 		providerOutageAdvised: false,
 		poisonedCompactSignatures: new Set(),
+		// S53: tracks whether withRecallTail injected this turn (consumed at turn_end).
+		recallInjectedThisTurn: false,
 		poisonedCount: 0,
+		extensionInitiatedTurn: false,
 	};
 	// v0.8.6 cache-stability: the cached live-trim view for the current
 	// compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and

package/extensions/mega-runtime/snapshot.ts

@@ -106,6 +106,11 @@ export interface SnapshotInput {
 	} | null;
 
 	lastActivityAt: number;
+
+	/** A3: per-turn cache hit percentage (most recent turn's ratio, separate
+	 *  from providerCachePct which is the running average). Optional — when null
+	 *  the cache-hit line is omitted from the widget. */
+	perTurnCacheHitPct?: number;
 }
 
 export interface SnapshotResult {
@@ -220,6 +225,7 @@ export function computeMegaSnapshot(p: SnapshotInput): SnapshotResult {
 		cachePct,
 		megaCacheFlare: p.megaCacheFlare,
 		megaCacheFlarePct: p.megaCacheFlarePct,
+		perTurnCacheHitPct: p.perTurnCacheHitPct ?? cachePct,
 		levelUpFlare: p.levelUpFlare,
 		achievementFlare: p.achievementFlare,
 		achievementFlareTitles: p.achievementFlareTitles,

package/extensions/mega-runtime/widget-types.ts

@@ -77,4 +77,7 @@ export interface WidgetData {
 		startedAt: number;
 		durationMs: number;
 	} | null;
+	/** A3: per-turn cache hit percentage (most recent turn's hit/miss ratio,
+	 *  0–100). Separate from cachePct (running average) for trend visibility. */
+	perTurnCacheHitPct?: number;
 }

package/extensions/mega-runtime/widget.ts

@@ -131,6 +131,11 @@ export function buildWidgetLines(
 		`${C.gray}mem${C.reset} ${wd.embedderName} · ${wd.chk} chunks · ${C.blue}comp ${wd.compStr}${C.reset}`,
 		`${C.gray}drift${C.reset} ${wd.driftStatus === "ok" ? C.green : C.amber}${wd.driftStatus}${C.reset}`,
 		`${C.gray}compact${C.reset} ${sinceCompactStr(wd.sinceCompact)}`,
+		...(wd.perTurnCacheHitPct != null
+			? [
+					`${C.gray}cache hit${C.reset} this turn ${C.green}${Math.round(wd.perTurnCacheHitPct)}%${C.reset}`,
+				]
+			: []),
 	].join(sep);
 	// Wrap to terminal width and pad each line
 	const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -28,7 +28,10 @@
     "extensions/dashboard-client/dist",
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!**/*.test.ts"
   ],
   "pi": {
     "extensions": [