pi-mega-compact 0.13.0 → 0.13.2

package/extensions/mega-commands/dataCommands.ts

@@ -0,0 +1,169 @@
+/**
+ * mega-commands/dataCommands.ts — the data/inspection slash commands (data group).
+ *
+ * Extracted from mega-commands.ts (delegate-shell split). Registers
+ * /mega-compact, /mega-recall, and /mega-status.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { normalizeSessionId } from "../../src/store.js";
+import { latestModelSnapshot, countInjectedGlobal, listRepoRegistry } from "../../src/store/sqlite.js";
+import { loadMetrics, fpRate, p95, defaultMetricsPath } from "../../src/monitoring.js";
+import { type MegaRuntime, C, recentUserQuery } from "../mega-runtime.js";
+import { runCompact, doRecall, doRecallAsync } from "../mega-pipeline.js";
+import { vectorStats, vectorRepoStats, vectorDataInvariant } from "../../src/vectorStore.js";
+import type { MegaConfig } from "../mega-config.js";
+
+/** Register the data/inspection commands (data group). */
+export function registerDataCommands(
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): void {
+	pi.registerCommand("mega-compact", {
+		description: "Compress current session context into the local vector store.",
+		handler: async (args: string, ctx: ExtensionContext) => {
+		 try {
+		  const sessionEntries = ctx.sessionManager.getEntries();
+		  // Project entries (branch-aware) into the message view.
+		  const messages = sessionEntries.flatMap((e) => sessionEntryToContextMessages(e));
+		  const summaryArg = args.trim();
+		  const ran = runCompact(pi, runtime, config, ctx, messages, summaryArg ? { summary: summaryArg } : {});
+		  if ("skipped" in ran && ran.skipped) {
+		    ctx.ui.notify("[mega-compact] Nothing to compact (session too small).");
+		    return;
+		  }
+		  const r = (ran as { result: { deduped: boolean; checkpointId?: string; tokenEstimate: number } }).result;
+		  ctx.ui.notify(
+		    `[mega-compact] ${r.deduped ? "region already compacted (deduped)" : `persisted ${r.checkpointId}`} · ` +
+		      `${r.tokenEstimate} tok · ${runtime.currentStateDir}`,
+		  );
+		 } catch (e) {
+		   ctx.ui.notify(`[mega-compact] /mega-compact failed: ${String(e)}`);
+		 }
+		},
+	});
+
+	pi.registerCommand("mega-recall", {
+		description: "Recall relevant compacted context from the vector store and inline it. Use --cross-repo to search all repos.",
+		handler: async (args: string, ctx: ExtensionContext) => {
+		 try {
+		  // S17: --cross-repo (or --cross repo) runs the async path over every repo's
+		  // PGlite HNSW index (stricter cosine floor + source labels).
+		  const crossRepo = /--cross[- ]repo\b/.test(args);
+		  const query = args.replace(/--cross[- ]repo\b/, "").trim() || recentUserQuery(ctx);
+		  if (!query) {
+		    ctx.ui.notify("[mega-compact] /mega-recall needs a query or a prior user message.");
+		    return;
+		  }
+		  const r = crossRepo
+		    ? await doRecallAsync(runtime, config, ctx, query, "command", { crossRepo: true })
+		    : doRecall(runtime, config, ctx, query, "command");
+		  if (r.empty) {
+		    runtime.logger.info("recall-empty", { query, crossRepo });
+		    ctx.ui.notify(`[mega-compact] recall found nothing new for "${query}".`);
+		    return;
+		  }
+		  // Stage the block so the next before_agent_start prepends it (actual
+		  // injection). Report what was selected now for immediate feedback.
+		  runtime.pendingRecallBlock = r.block;
+		  const list = r.report.map((l) => l).join("\n");
+		  runtime.logger.info("recall", { query, crossRepo, injected: r.toInject.map((h) => h.checkpoint.checkpointId) });
+		  runtime.setStatus(ctx, `mega-compact: recalled ${r.toInject.length} chkpt${crossRepo ? " (cross-repo)" : ""}`);
+		  ctx.ui.notify(
+		    `[mega-compact] recall staged ${r.toInject.length} checkpoint(s) for "${query}"${crossRepo ? " (cross-repo)" : ""}:\n${list}\n` +
+		      `(injected at the tail of the next turn's context)`,
+		  );
+		 } catch (e) {
+		   ctx.ui.notify(`[mega-compact] /mega-recall failed: ${String(e)}`);
+		 }
+		},
+	});
+
+	pi.registerCommand("mega-status", {
+		description: "Show mega-compact config, context usage, and the data-safety invariant.",
+		handler: async (_args: string, ctx: ExtensionContext) => {
+		 try {
+		  runtime.bindRepo(ctx.cwd);
+		  const usage = ctx.getContextUsage();
+		  const pct = usage?.percent != null ? `${usage.percent}%` : "n/a";
+		  const tokens = usage?.tokens != null ? `${usage.tokens} tok` : "n/a";
+		  const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+		  const st = vectorStats(runtime.store, sid);
+		  const repo = vectorRepoStats(runtime.store);
+		  const di = vectorDataInvariant(runtime.store);
+		  const fmtB = (b: number) =>
+		    b >= 1_048_576 ? `${(b / 1_048_576).toFixed(1)} MiB` :
+		      b >= 1024 ? `${(b / 1024).toFixed(1)} KiB` : `${b} B`;
+		  // Real cost: tokens saved × the captured model's input rate (USD/token),
+		  // read from the model_snapshots table (Phase 5b schema). Falls back to 0
+		  // when no model has been captured yet. contextWindow ÷ savedRate = context
+		  // windows extended (how much "extra" conversation the freed space buys).
+		  const model = latestModelSnapshot(runtime.currentStateDir);
+		  const rate = model?.inputRate ?? 0;
+		  const usd = ((repo.tokensSaved ?? 0) * rate).toFixed(4);
+		  const ctxWindow = usage?.contextWindow ?? 0;
+		  const daysExtended = ctxWindow > 0 && repo.tokensSaved > 0
+		    ? (repo.tokensSaved / ctxWindow).toFixed(1)
+		    : "0";
+		  // Identified model/provider (captured on model_select / session_start).
+		  // Shows the human model name + provider so the user knows WHICH model's
+		  // pricing drives the cost figure. Falls back when none captured yet.
+		  const modelStr = model
+		    ? `${model.modelName ?? model.modelId ?? "?"} · ${model.providerName ?? model.provider ?? "?"}`
+		    : "unknown (no model captured)";
+		  const costStr = `≈ $${usd} saved · ${daysExtended} context-windows extended`;
+		  // Recall-quality badge (Phase 4): trust score from monitoring metrics.
+		  // H1 fix: loadMetrics expects a *file* path (dashboard.json), not the
+		  // state dir — passing the dir made existsSync() true (dirs exist) then
+		  // readFileSync() threw EISDIR, silently caught → metrics always zero.
+		  const m = loadMetrics(defaultMetricsPath(runtime.currentStateDir));
+		  const fp = fpRate(m, "L2");
+		  const p95L2 = p95(m.latency.L2 ?? []);
+		  const relPct = (st.dedupHitRate * 100).toFixed(0);
+		  const qualityStr = `recall ${relPct}% relevant · FP ${(fp * 100).toFixed(1)}% · L2 p95 ${p95L2.toFixed(0)}ms`;
+		  // S18: cross-repo stats from the machine-wide index (best-effort; the
+		  // index dir may be unset → 0/empty, never throws).
+		  let crossRepoInjections = 0;
+		  let repoCount = 0;
+		  try {
+		    crossRepoInjections = countInjectedGlobal(process.env.MEGACOMPACT_INDEX_DIR);
+		    repoCount = listRepoRegistry(process.env.MEGACOMPACT_INDEX_DIR).length;
+		  } catch { /* non-fatal */ }
+		  const crossRepoStr = `${crossRepoInjections} cross-repo injections recorded · ${repoCount} repos indexed`;
+		  // Effective compaction threshold = tierPct × model context window (kept
+		  // BELOW pi's native ~80% auto-compact for any model size). Falls back to
+		  // the boot token value when the window is unknown (custom tier / pre-
+		  // model-select). Display matches the dashboard's percentage-based view.
+		  const effThreshold = config.tierPct != null && ctxWindow > 0
+		    ? Math.round(config.tierPct * ctxWindow)
+		    : config.thresholdTokens;
+		  const winStr = ctxWindow > 0
+		    ? (ctxWindow >= 1_000_000 ? `${Math.round(ctxWindow / 1_000_000)}M` : `${Math.round(ctxWindow / 1_000)}k`)
+		    : "?";
+		  const tierPctStr = config.tierPct != null ? `${Math.round(config.tierPct * 100)}%` : "n/a";
+		  ctx.ui.notify(
+		    `[mega-compact] pct=${pct} tokens=${tokens} tier=${runtime.pressureBand} (live) preset=${config.tier} ` +
+		      `pressure=${Math.round(runtime.pressure * 100)}% fastGate=${config.fastGatePct}% ` +
+		      `threshold=${effThreshold.toLocaleString()} (${tierPctStr} of ${winStr} window) tierPct=${config.tierPct != null ? config.tierPct.toFixed(2) : "n/a"} auto=${config.auto} autoInline=${config.autoInline}\n` +
+		      `[mega-compact] store: ${st.checkpointCount} chkpt · ` +
+		      `${st.totalTokenEstimate} tok · last=${st.lastCheckpointId ?? "—"} · ` +
+		      `injected=${st.injectedCount} · dedup=${(st.dedupHitRate * 100).toFixed(0)}%\n` +
+		      `[mega-compact] anchor=${config.anchorUserMessages} preserveRecent=${config.preserveRecent} ` +
+		      `autoInlineK=${config.autoInlineK} dedupSim=${config.dedupSim} debug=${config.debug}\n` +
+		      `[mega-compact] 🛡 data-safe: ${di.regionsRetained} regions retained ` +
+		      `(${fmtB(di.compressedOriginalBytes)} compressed-original) · ` +
+		      `${di.duplicatesCollapsed} dedup-duplicates collapsed · ` +
+		      `${C.green}0 bytes permanently deleted${C.reset}\n` +
+		      `[mega-compact] 💰 ${costStr}\n` +
+		      `[mega-compact] 🤖 model: ${modelStr}\n` +
+		      `[mega-compact] 🎯 ${qualityStr}\n` +
+		      `[mega-compact] 🌐 ${crossRepoStr}\n` +
+		      `[mega-compact] stateDir=${runtime.currentStateDir}`,
+		  );
+		 } catch (e) {
+		   ctx.ui.notify(`[mega-compact] /mega-status error: ${String(e)}`);
+		 }
+		},
+	});
+}

package/extensions/mega-commands/helpers.ts

@@ -0,0 +1,62 @@
+/**
+ * mega-commands/helpers.ts — shared helpers for the data/inspection commands.
+ *
+ * Extracted from mega-commands.ts (delegate-shell split). findCheckpoint
+ * resolves a checkpoint by id (or "recent"/"last"); checkRecallQuality peeks at
+ * recent events.log / mega-compact.log for low recall-quality signals.
+ */
+import type { MegaRuntime } from "../mega-runtime.js";
+import { listCheckpoints } from "../../src/store/sqlite.js";
+import { defaultEventsPath } from "../../src/monitoring.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/** Resolve a checkpoint by id (or "recent"/"last") from this session's store. */
+export function findCheckpoint(runtime: MegaRuntime, sid: string, ref: string) {
+  const all = listCheckpoints(sid, runtime.currentStateDir);
+  if (all.length === 0) return undefined;
+  if (!ref || ref === "recent" || ref === "last") return all[all.length - 1];
+  return all.find((c) => c.checkpointId === ref) ?? all.find((c) => c.checkpointId.endsWith(ref));
+}
+
+/**
+ * Try to peek at recent events.log and mega-compact.log for low recall quality signals.
+ * Best-effort, non-fatal — returns true if a low-quality signal was found.
+ */
+export function checkRecallQuality(stateDir: string): boolean {
+  const eventPaths = [
+    defaultEventsPath(stateDir),
+    path.join(stateDir, "mega-compact.log"),
+  ];
+  for (const fp of eventPaths) {
+    try {
+      if (!existsSync(fp)) continue;
+      const buf = readFileSync(fp, { encoding: "utf-8" });
+      // Only scan last 64 KiB of the file
+      const tail = buf.length > 65536 ? buf.slice(buf.length - 65536) : buf;
+      const lines = tail.split("\n").filter(Boolean);
+      for (const line of lines) {
+        try {
+          // guardrails-allow PREVENT-001: JSON.parse with null check
+          const parsed = JSON.parse(line);
+          if (typeof parsed !== "object" || parsed === null) continue;
+          // Check for recall_metrics_low_quality event (latest format)
+          if (parsed.event === "recall_metrics_low_quality" && parsed.score !== undefined) {
+            if (typeof parsed.score === "number" && parsed.score < 0.4) return true;
+          }
+          // Check for recall_metrics with low relevanceScore
+          if (parsed.event === "recall_metrics" && parsed.relevanceScore !== undefined) {
+            if (typeof parsed.relevanceScore === "number" && parsed.relevanceScore < 0.4) return true;
+          }
+          // Check for RecallQualityEvent format from monitoring.ts
+          if (parsed.score !== undefined && typeof parsed.score === "number" && parsed.score < 0.4) return true;
+        } catch {
+          // skip unparseable lines
+        }
+      }
+    } catch {
+      // non-fatal: skip if can't read
+    }
+  }
+  return false;
+}

package/extensions/mega-commands/historyCommands.ts

@@ -0,0 +1,117 @@
+/**
+ * mega-commands/historyCommands.ts — the checkpoint history/inspection commands.
+ *
+ * Extracted from mega-commands.ts (delegate-shell split). Registers
+ * /mega-restore, /mega-history, /mega-view, and /mega-help.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { normalizeSessionId } from "../../src/store.js";
+import { listCheckpoints } from "../../src/store/sqlite.js";
+import { decompressSmart } from "../../src/store/compression.js";
+import { type MegaRuntime, C } from "../mega-runtime.js";
+import { findCheckpoint } from "./helpers.js";
+
+/** Register the checkpoint history/inspection commands. */
+export function registerHistoryCommands(
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+): void {
+	pi.registerCommand("mega-restore", {
+		description: "Re-inject a checkpoint's verbatim original region into context. Usage: /mega-restore <chkpt|recent>",
+		handler: async (args: string, ctx: ExtensionContext) => {
+		 try {
+		  runtime.bindRepo(ctx.cwd);
+		  const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+		  const cp = findCheckpoint(runtime, sid, args.trim());
+		  if (!cp) {
+		    ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""} in this session. Try /mega-history.`);
+		    return;
+		  }
+		  if (!cp.compressedOriginal) {
+		    ctx.ui.notify(`[mega-compact] ${cp.checkpointId} has no recoverable original (pre-blob or direct add). Cannot restore verbatim.`);
+		    return;
+		  }
+		  const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+		  // Re-inject verbatim via before_agent_start (PREVENT-PI-003) — never
+		  // touches live messages, only prepends the restored region to systemPrompt.
+		  runtime.pendingRecallBlock = `The following compacted context was RESTORED from checkpoint ${cp.checkpointId} (verbatim original region):\n\n${original}`;
+		  const files = cp.filesModified?.length ? cp.filesModified.join(", ") : "(no files captured)";
+		  ctx.ui.notify(
+		    `[mega-compact] ♻ restored ${cp.checkpointId} — ${original.length} chars re-injected on next turn.\n` +
+		    `[mega-compact] files: ${files}`,
+		  );
+		  runtime.dashboard.event("restore", { checkpointId: cp.checkpointId, chars: original.length });
+		 } catch (e) {
+		   ctx.ui.notify(`[mega-compact] /mega-restore failed (checkpoint may be corrupt): ${String(e)}`);
+		 }
+		},
+	});
+
+	pi.registerCommand("mega-history", {
+		description: "List this session's checkpoints (id, date, files, tokens). Usage: /mega-history",
+		handler: async (_args: string, ctx: ExtensionContext) => {
+		  runtime.bindRepo(ctx.cwd);
+		  const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+		  const all = listCheckpoints(sid, runtime.currentStateDir);
+		  if (all.length === 0) {
+		    ctx.ui.notify("[mega-compact] no checkpoints in this session yet.");
+		    return;
+		  }
+		  const rows = all.map((c) => {
+		    const when = c.timestamp ? new Date(c.timestamp).toISOString().slice(0, 16).replace("T", " ") : "—";
+		    const files = c.filesModified?.length ? c.filesModified.map((f) => f.split("/").pop() ?? f).join(", ") : "—";
+		    const orig = c.originalTokenEstimate ?? 0;
+		    const stored = c.tokenEstimate ?? 0;
+		    const saved = Math.max(0, orig - stored);
+		    return `  ${c.checkpointId}  ${when}  ${C.cyan}${saved}t saved${C.reset}  ${files}`;
+		  });
+		  ctx.ui.notify(
+		    `[mega-compact] ${all.length} checkpoint(s) in this session:\n` + rows.join("\n") +
+		    `\n[mega-compact] /mega-view <chkpt> to see the original region · /mega-restore <chkpt> to re-inject it`,
+		  );
+		},
+	});
+
+	pi.registerCommand("mega-view", {
+		description: "Show a checkpoint's verbatim original region. Usage: /mega-view <chkpt|recent>",
+		handler: async (args: string, ctx: ExtensionContext) => {
+		 try {
+		  runtime.bindRepo(ctx.cwd);
+		  const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+		  const cp = findCheckpoint(runtime, sid, args.trim());
+		  if (!cp) {
+		    ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""}. Try /mega-history.`);
+		    return;
+		  }
+		  if (!cp.compressedOriginal) {
+		    ctx.ui.notify(`[mega-compact] ${cp.checkpointId} summary:\n${cp.summary.slice(0, 500)}${cp.summary.length > 500 ? "…" : ""}\n(no verbatim original stored)`);
+		    return;
+		  }
+		  const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+		  ctx.ui.notify(
+		    `[mega-compact] ${cp.checkpointId} — original region (${original.length} chars):\n` +
+		    `${original.slice(0, 1500)}${original.length > 1500 ? "\n…(truncated)" : ""}`,
+		  );
+		 } catch (e) {
+		   ctx.ui.notify(`[mega-compact] /mega-view failed (checkpoint may be corrupt): ${String(e)}`);
+		 }
+		},
+	});
+
+	pi.registerCommand("mega-help", {
+		description: "Plain-language glossary of what mega-compact's stats mean.",
+		handler: async (_args: string, ctx: ExtensionContext) => {
+		  ctx.ui.notify(
+		    `[mega-compact] glossary — what the numbers mean:\n` +
+		    `• token — a chunk of text (~4 chars). Context window = how much text fits in memory at once.\n` +
+		    `• space freed — how much conversation we've compressed away to make room (the win).\n` +
+		    `• memory held — how much compact summary we're currently keeping as your 'notes'.\n` +
+		    `• saved checkpoint — a compact summary of an old conversation chunk we stored.\n` +
+		    `• repeat-skipped — how often new text matched something we already had, so we didn't store a duplicate.\n` +
+		    `• injected — times we pasted an old saved note back into the chat because it was relevant.\n` +
+		    `• recall relevance — of those, how often the note was actually on-topic.\n` +
+		    `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`,
+		  );
+		},
+	});
+}

package/extensions/mega-commands/setupCommand.ts

@@ -0,0 +1,235 @@
+/**
+ * mega-commands/setupCommand.ts — the local embedding setup wizard command.
+ *
+ * Extracted from mega-commands.ts (delegate-shell split). Registers
+ * /mega-setup: detects available local embedders and writes the chosen
+ * configuration to .mega-compact.env.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only (no network)
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createRequire } from "node:module";
+import { checkRecallQuality } from "./helpers.js";
+
+/** Register the /mega-setup embedder wizard command. */
+export function registerSetupCommand(
+	pi: ExtensionAPI,
+): void {
+	pi.registerCommand("mega-setup", {
+		description:
+			"Local embedding setup wizard — detect available embedders and configure mega-compact.",
+		handler: async (_args: string, ctx: ExtensionContext) => {
+		 try {
+		  const log = (msg: string) => ctx.ui.notify(msg);
+
+		  // --- 1. Current config ---
+		  const embeddingUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
+		  const minilm = process.env["MEGACOMPACT_MINILM"];
+
+		  let currentEmbedder = "TrigramEmbedder (heuristic, default)";
+		  if (embeddingUrl) currentEmbedder = `httpEmbedder → ${embeddingUrl}`;
+		  else if (minilm) currentEmbedder = "MiniLM (experimental)";
+
+		  // --- 2. Detection ---
+		  let ollamaDetected = false;
+		  let ollamaModels: string[] = [];
+		  let ollamaRunning = false;
+		  let llamaDetected = false;
+		  let onnxDetected = false;
+
+		  try {
+		    const ollamaVer = spawnSync("ollama", ["--version"], {
+		      timeout: 5000,
+		      encoding: "utf-8",
+		      stdio: ["ignore", "pipe", "pipe"],
+		    }); // guardrails-allow PREVENT-PI-004: local subprocess detection only
+		    if (ollamaVer.status === 0) {
+		      ollamaDetected = true;
+		      try {
+		        const listResult = spawnSync("ollama", ["list"], {
+		          timeout: 5000,
+		          encoding: "utf-8",
+		          stdio: ["ignore", "pipe", "pipe"],
+		        }); // guardrails-allow PREVENT-PI-004: local subprocess detection only
+		        if (listResult.status === 0) {
+		          ollamaRunning = true;
+		          const lines = listResult.stdout?.split("\n") ?? [];
+		          for (const line of lines) {
+		            const name = line.split(/\s+/)[0];
+		            if (name && name !== "NAME") ollamaModels.push(name);
+		          }
+		        }
+		      } catch {
+		        // ollama list fails if server not running — that's fine
+		      }
+		    }
+		  } catch {
+		    // ollama not found
+		  }
+
+		  try {
+		    const whichLlama = spawnSync("which", ["llama-server"], {
+		      timeout: 3000,
+		      encoding: "utf-8",
+		      stdio: ["ignore", "pipe", "pipe"],
+		    }); // guardrails-allow PREVENT-PI-004: local subprocess detection only
+		    llamaDetected = whichLlama.status === 0;
+		  } catch {
+		    // not found
+		  }
+
+		  try {
+		    const req = createRequire(import.meta.url);
+		    try {
+		      req.resolve("onnxruntime-node");
+		      onnxDetected = true;
+		    } catch {
+		      // not in node_modules
+		    }
+		  } catch {
+		    // require error
+		  }
+
+		  // --- 2.5 Quality check ---
+		  // Scan recent events for low recall quality (best-effort, non-fatal)
+		  const stateDir = process.env["MEGACOMPACT_STATE_DIR"] ?? path.join(os.homedir(), ".pi", "mega-compact");
+		  const lowRecallQuality = checkRecallQuality(stateDir);
+
+		  // --- 3. Build choices ---
+		  interface Choice {
+		    label: string;
+		    value: string;
+		  }
+		  const choices: Choice[] = [];
+
+		  if (ollamaDetected && ollamaRunning) {
+		    const model = ollamaModels.find(
+		      (m) =>
+		        m.includes("nomic-embed") ||
+		        m.includes("embed") ||
+		        m.includes("mxbai"),
+		    );
+		    const suggestedModel = model ?? "nomic-embed-text";
+		    choices.push({
+		      label: `Use Ollama (${suggestedModel}) at localhost:11434`,
+		      value: `ollama:${suggestedModel}`,
+		    });
+		  } else if (ollamaDetected && !ollamaRunning) {
+		    choices.push({
+		      label: "Ollama detected but server is not running — start it first",
+		      value: "ollama:offline",
+		    });
+		  }
+
+		  if (llamaDetected) {
+		    choices.push({
+		      label: "Use llama.cpp server at localhost:8080",
+		      value: "llama:default",
+		    });
+		  }
+
+		  if (onnxDetected) {
+		    choices.push({
+		      label: "Use ONNX Runtime (experimental, requires config)",
+		      value: "onnx:default",
+		    });
+		  }
+
+		  choices.push({
+		    label: "Keep TrigramEmbedder (default, no setup)",
+		    value: "trigram",
+		  });
+
+		  // --- 4. Prompt user ---
+		  log(`Current embedder: ${currentEmbedder}`);
+		  if (lowRecallQuality) {
+		    log(
+		      "Tap: recent recall quality is low. Consider switching to Ollama or llama.cpp for better results.",
+		    );
+		  }
+		  let selected = "trigram";
+		  if (choices.length > 1) {
+		    try {
+		      const labels = choices.map((c) => c.label);
+		      const picked = await ctx.ui.select("Select an embedder to configure:", labels);
+		      if (picked === undefined) {
+		        log("Setup cancelled by user.");
+		        return;
+		      }
+		      const match = choices.find((c) => c.label === picked);
+		      selected = match?.value ?? "trigram";
+		    } catch {
+		      log("Setup cancelled by user.");
+		      return;
+		    }
+		  } else {
+		    log("No local embedders detected. Keeping TrigramEmbedder default.");
+		  }
+
+		  // --- 5. Apply selection ---
+		  if (selected.startsWith("ollama:")) {
+		    const model = selected.split(":")[1];
+		    const url = `http://localhost:11434/api/embeddings`; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+		    const lines = [
+		      `# Mega-Compact Embedder Configuration — Ollama`,
+		      `# Generated by /megasetup at ${new Date().toISOString()}`,
+		      `export MEGACOMPACT_EMBEDDING_URL="${url}"`,
+		      `# Optional: uncomment to set cache size (default 1000)`,
+		      `# export MEGACOMPACT_EMBED_CACHE=1000`,
+		    ];
+		    const envContent = lines.join("\n") + "\n";
+
+		    // Write .mega-compact.env to state dir
+		    try {
+		      mkdirSync(stateDir, { recursive: true });
+		      writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
+		    } catch {
+		      // non-fatal
+		    }
+
+		    log(
+		      `Configured for Ollama (${model}).\n\nAdd to your shell profile (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):\n\n  source "${path.join(
+		        stateDir,
+		        ".mega-compact.env",
+		      )}"\n\nOr export manually:\n\n  export MEGACOMPACT_EMBEDDING_URL="${url}"\n\nThen restart pi to activate the http embedder.`,
+		    );
+		  } else if (selected.startsWith("llama:")) {
+		    const url = "http://localhost:8080/v1/embeddings"; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+		    const lines = [
+		      `# Mega-Compact Embedder Configuration — llama.cpp`,
+		      `# Generated by /megasetup at ${new Date().toISOString()}`,
+		      `export MEGACOMPACT_EMBEDDING_URL="${url}"`,
+		    ];
+		    const envContent = lines.join("\n") + "\n";
+		    try {
+		      mkdirSync(stateDir, { recursive: true });
+		      writeFileSync(path.join(stateDir, ".mega-compact.env"), envContent, "utf-8");
+		    } catch {
+		      // non-fatal
+		    }
+
+		    log(
+		      `Configured for llama.cpp server.\n\nAdd to your shell profile:\n\n  source "${path.join(
+		        stateDir,
+		        ".mega-compact.env",
+		      )}"\n\nOr export manually:\n\n  export MEGACOMPACT_EMBEDDING_URL="${url}"\n\nThen restart pi to activate the http embedder.`,
+		    );
+		  } else if (selected.startsWith("onnx:")) {
+		    log(
+		      "ONNX Runtime configuration is experimental.\n\nSet MEGACOMPACT_EMBEDDING_URL to your local ONNX server URL, or see docs for manual setup.\nKeeping TrigramEmbedder for now.",
+		    );
+		  } else {
+		    const qualityTip =
+		      lowRecallQuality
+		        ? " Recent recall quality is low — consider running /mega-setup again to switch to Ollama or llama.cpp for better results."
+		        : "";
+		    log(`Keeping TrigramEmbedder (default). No configuration needed.${qualityTip}`);
+		  }
+		 } catch (e) {
+		   ctx.ui.notify(`[mega-compact] /mega-setup failed: ${String(e)}`);
+		 }
+		},
+	});
+}