pi-blackhole 0.2.0

package/src/commands/memory.ts

@@ -0,0 +1,191 @@
+/**
+ * /memory command — shows memory pipeline status and content.
+ *
+ * Created by pi-vcc-om. Replaces OM's standalone /om-status and /om-view.
+ * Usage: /memory (status), /memory view, /memory full.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { copyTextToClipboard } from "../om/clipboard.js";
+import type { Runtime } from "../om/runtime.js";
+import {
+	diffProjection,
+	foldLedger,
+	fullProjection,
+	observationToSummaryLine,
+	rawTokensSinceDropCoverage,
+	rawTokensSinceLastCompaction,
+	rawTokensSinceObservationCoverage,
+	rawTokensSinceReflectionCoverage,
+	reflectionToSummaryLine,
+	visibleProjection,
+	type Entry,
+	type Projection,
+} from "../om/ledger/index.js";
+import { readPendingState } from "../om/pending.js";
+
+function firstArg(args: unknown): string | undefined {
+	if (Array.isArray(args)) return typeof args[0] === "string" ? args[0] : undefined;
+	if (typeof args === "string") return args.trim().split(/\s+/)[0];
+	if (args && typeof args === "object" && "mode" in args) {
+		const mode = (args as { mode?: unknown }).mode;
+		return typeof mode === "string" ? mode : undefined;
+	}
+	return undefined;
+}
+
+function pct(current: number, total: number): number {
+	return total > 0 ? Math.min(100, Math.round((current / total) * 100)) : 0;
+}
+
+function tokenSum(items: { tokenCount: number }[]): number {
+	return items.reduce((sum, item) => sum + item.tokenCount, 0);
+}
+
+function addedSuffix(count: number): string | undefined {
+	return count > 0 ? `+${count.toLocaleString()}` : undefined;
+}
+
+function removedSuffix(count: number): string | undefined {
+	return count > 0 ? `-${count.toLocaleString()}` : undefined;
+}
+
+function appendSuffixes(line: string, suffixes: (string | undefined)[]): string {
+	const rendered = suffixes.filter((s): s is string => s !== undefined);
+	return rendered.length > 0 ? `${line} ${rendered.join(" ")}` : line;
+}
+
+function renderList<T>(items: T[], render: (item: T) => string, empty: string): string {
+	return items.length > 0 ? items.map(render).join("\n") : empty;
+}
+
+function renderContentOnlyProjection(projection: Projection, emptyScope: "visible" | "recorded"): string {
+	return [
+		"── Reflections ──",
+		renderList(projection.reflections, reflectionToSummaryLine, `No ${emptyScope} reflections.`),
+		"",
+		"── Observations ──",
+		renderList(projection.observations, observationToSummaryLine, `No ${emptyScope} observations.`),
+	].join("\n");
+}
+
+export function registerMemoryCommand(pi: ExtensionAPI, runtime: Runtime): void {
+	pi.registerCommand("blackhole-memory", {
+		description: "Show memory pipeline status & token counters. /blackhole-memory for overview, /blackhole-memory view for visible observations & reflections, /blackhole-memory full for complete recorded memory (copies to clipboard).",
+		handler: async (args, ctx) => {
+			runtime.ensureConfig(ctx.cwd);
+			const entries = ctx.sessionManager.getBranch() as Entry[];
+			const sessionId = ctx.sessionManager.getSessionId();
+			const mode = firstArg(args);
+
+			// /memory full — show full recorded memory + copy to clipboard
+			if (mode === "full") {
+				const projection = fullProjection(entries);
+				const output = renderContentOnlyProjection(projection, "recorded");
+				const copied = await copyTextToClipboard(output).catch(() => false);
+				ctx.ui.notify(
+					copied ? `${output}\n\nCopied to clipboard.` : `${output}\n\nFailed to copy to clipboard.`,
+					"info",
+				);
+				return;
+			}
+
+			// /memory view — show visible memory + copy to clipboard
+			if (mode === "view") {
+				const projection = visibleProjection(entries);
+				const output = renderContentOnlyProjection(projection, "visible");
+				const copied = await copyTextToClipboard(output).catch(() => false);
+				ctx.ui.notify(
+					copied ? `${output}\n\nCopied to clipboard.` : `${output}\n\nFailed to copy to clipboard.`,
+					"info",
+				);
+				return;
+			}
+
+			// /memory (no args) — show status
+			if (mode && mode !== "status") {
+				ctx.ui.notify("Usage: /blackhole-memory [status|view|full]", "info");
+				return;
+			}
+
+			const folded = foldLedger(entries);
+			const visible = visibleProjection(entries);
+			const full = fullProjection(entries);
+			const drift = diffProjection(visible, full);
+
+			const visibleObservationTokens = tokenSum(visible.observations);
+			const visibleReflectionTokens = tokenSum(visible.reflections);
+			const observationLine = appendSuffixes(
+				`Observations: ${folded.observations.length} recorded / ${folded.droppedObservationIds.size} dropped / ${visible.observations.length} visible`,
+				[
+					addedSuffix(drift.observationsOnlyInFull.length),
+					removedSuffix(drift.droppedOnlyInFull.length),
+				],
+			);
+			const reflectionLine = appendSuffixes(
+				`Reflections:  ${folded.reflections.length} recorded / ${visible.reflections.length} visible`,
+				[addedSuffix(drift.reflectionsOnlyInFull.length)],
+			);
+			const obsProgress = rawTokensSinceObservationCoverage(entries);
+			const reflectionProgress = rawTokensSinceReflectionCoverage(entries);
+			const dropProgress = rawTokensSinceDropCoverage(entries);
+			const compactionProgress = rawTokensSinceLastCompaction(entries);
+
+			const passiveLines = runtime.config.passive === true
+				? [
+					"── Mode ──",
+					"Passive: automatic memory workers and auto-compaction disabled",
+					"",
+				]
+				: [];
+
+			const lines = [
+				...passiveLines,
+				"── Memory ──",
+				observationLine,
+				reflectionLine,
+				"",
+				"── Activity ──",
+				`Observer:       ~${obsProgress.toLocaleString()} / ${runtime.config.observeAfterTokens.toLocaleString()} tokens (${pct(obsProgress, runtime.config.observeAfterTokens)}%)`,
+				`Reflector:      ~${reflectionProgress.toLocaleString()} / ${runtime.config.reflectAfterTokens.toLocaleString()} tokens (${pct(reflectionProgress, runtime.config.reflectAfterTokens)}%)`,
+				`Dropper:        ~${dropProgress.toLocaleString()} / ${runtime.config.reflectAfterTokens.toLocaleString()} tokens (${pct(dropProgress, runtime.config.reflectAfterTokens)}%)`,
+				`Compaction:     ~${compactionProgress.toLocaleString()} / ${runtime.config.compactAfterTokens.toLocaleString()} tokens (${pct(compactionProgress, runtime.config.compactAfterTokens)}%)`,
+				`Obs pool:       ~${visibleObservationTokens.toLocaleString()} / ${runtime.config.observationsPoolMaxTokens.toLocaleString()} tokens (${pct(visibleObservationTokens, runtime.config.observationsPoolMaxTokens)}%)`,
+				`Reflect pool:   ~${visibleReflectionTokens.toLocaleString()} tokens`,
+			];
+
+			// Show pending data when noAutoCompact is active
+			if (runtime.config.noAutoCompact) {
+				const pending = readPendingState(sessionId);
+				const hasObs = !!pending.observation;
+				const hasRef = !!pending.reflection;
+				const hasDrop = !!pending.dropped;
+				if (hasObs || hasRef || hasDrop) {
+					lines.push("", "── Pending (noAutoCompact) ──");
+					if (hasObs) lines.push("Observation:  waiting in pending.json");
+					if (hasRef) lines.push("Reflection:   waiting in pending.json");
+					if (hasDrop) lines.push("Dropper:      waiting in pending.json");
+					lines.push("Run /blackhole to flush and compact.");
+				}
+			}
+
+			if (runtime.consolidationInFlight || runtime.compactInFlight || runtime.compactHookInFlight) {
+				lines.push("", "── In flight ──");
+				if (runtime.consolidationInFlight) {
+					const phase = runtime.consolidationPhase ? ` (${runtime.consolidationPhase})` : "";
+					lines.push(`Consolidation: running${phase}`);
+				}
+				if (runtime.compactInFlight) lines.push("Auto-compaction: running");
+				if (runtime.compactHookInFlight) lines.push("Compaction hook: running");
+			}
+
+			if (runtime.lastObserverError || runtime.lastReflectorError || runtime.lastDropperError) {
+				lines.push("", "── Last error ──");
+				if (runtime.lastObserverError) lines.push(`Observer: ${runtime.lastObserverError}`);
+				if (runtime.lastReflectorError) lines.push(`Reflector: ${runtime.lastReflectorError}`);
+				if (runtime.lastDropperError) lines.push(`Dropper: ${runtime.lastDropperError}`);
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/src/commands/pi-vcc.ts

@@ -0,0 +1,94 @@
+/**
+ * /pi-vcc command — triggers pi-vcc compaction.
+ *
+ * Upstream: https://github.com/sting8k/pi-vcc (src/commands/pi-vcc.ts)
+ * Modified by pi-vcc-om:
+ * - Flushes pending OM state (observations/reflections/dropped) when noAutoCompact is active
+ *   before triggering compaction, so the compaction summary includes all accumulated memory.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Runtime } from "../om/runtime.js";
+import { getLastCompactionStats, PI_VCC_COMPACT_INSTRUCTION } from "../hooks/before-compact";
+import { saveUnifiedConfig } from "../core/unified-config.js";
+import { readPendingState, clearPendingState, hasPendingData } from "../om/pending.js";
+import {
+	OM_OBSERVATIONS_DROPPED,
+	OM_OBSERVATIONS_RECORDED,
+	OM_REFLECTIONS_RECORDED,
+} from "../om/ledger/index.js";
+
+const formatTokens = (n: number): string => {
+	if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+	return String(n);
+};
+
+export const registerPiVccCommand = (pi: ExtensionAPI, runtime: Runtime) => {
+	pi.registerCommand("blackhole", {
+		description:
+			"Compact conversation — structured summary (with observational memory when enabled). " +
+			"Subcommands: /blackhole om-off (disable memory), /blackhole om-on (re-enable memory).",
+		handler: async (args, ctx) => {
+			const sessionId = ctx.sessionManager.getSessionId();
+
+			// Handle om-off / om-on subcommands
+			const trimmed = (typeof args === "string" ? args : "").trim();
+			if (trimmed === "om-off") {
+				const saved = saveUnifiedConfig({ memory: false });
+				runtime.config.memory = false;
+				ctx.ui.notify(
+					saved ? "Observational memory disabled. Use /blackhole om-on to re-enable." : "Failed to save config.",
+					"info",
+				);
+				return;
+			}
+			if (trimmed === "om-on") {
+				const saved = saveUnifiedConfig({ memory: true });
+				runtime.config.memory = true;
+				ctx.ui.notify(
+					saved ? "Observational memory enabled." : "Failed to save config.",
+					"info",
+				);
+				return;
+			}
+
+			// If noAutoCompact: flush pending OM entries into the branch
+			// before compacting so the summary includes accumulated memory.
+			if (runtime.config.noAutoCompact && hasPendingData(sessionId)) {
+				const pending = readPendingState(sessionId);
+				if (pending.observation) {
+					pi.appendEntry(OM_OBSERVATIONS_RECORDED, pending.observation.data);
+				}
+				if (pending.reflection) {
+					pi.appendEntry(OM_REFLECTIONS_RECORDED, pending.reflection.data);
+				}
+				if (pending.dropped) {
+					pi.appendEntry(OM_OBSERVATIONS_DROPPED, pending.dropped.data);
+				}
+				clearPendingState(sessionId);
+				ctx.ui.notify("Observational memory: pending entries flushed", "info");
+			}
+
+			ctx.compact({
+				customInstructions: PI_VCC_COMPACT_INSTRUCTION,
+				onComplete: () => {
+					const stats = getLastCompactionStats();
+					if (stats) {
+						ctx.ui.notify(
+							`blackhole: ${stats.summarized} source entries processed; tail kept ${stats.kept} (~${formatTokens(stats.keptTokensEst)} tok).`,
+							"info",
+						);
+					} else {
+						ctx.ui.notify("Compacted with blackhole", "info");
+					}
+				},
+				onError: (err) => {
+					if (err.message === "Compaction cancelled" || err.message === "Already compacted") {
+						ctx.ui.notify("Nothing to compact", "warning");
+					} else {
+						ctx.ui.notify(`Compaction failed: ${err.message}`, "error");
+					}
+				},
+			});
+		},
+	});
+};

package/src/commands/vcc-recall.ts

@@ -0,0 +1,112 @@
+/**
+ * /blackhole-recall command — search session history.
+ *
+ * Upstream: https://github.com/sting8k/pi-vcc (src/commands/vcc-recall.ts)
+ * Ported and renamed to /blackhole-recall for blackhole.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadAllMessages } from "../core/load-messages.js";
+import { searchEntries } from "../core/search-entries.js";
+import { formatRecallOutput } from "../core/format-recall.js";
+import { getActiveLineageEntryIds } from "../core/lineage.js";
+import { parseRecallScope } from "../core/recall-scope.js";
+import {
+	findObservationsForEntryIds,
+	findReflectionsForEntryIds,
+	formatRelatedObservations,
+} from "../om/reverse-recall.js";
+import type { Entry } from "../om/ledger/recall.js";
+
+const PAGE_SIZE = 5;
+const DEFAULT_RECENT = 25;
+
+async function augmentWithObservations(
+	output: string,
+	rendered: { id: string }[],
+	ctx: any,
+): Promise<string> {
+	const ids = rendered.map((e) => e.id).filter(Boolean);
+	if (ids.length === 0) return output;
+	try {
+		const branchEntries = ctx.sessionManager.getBranch() as Entry[];
+		const obs = findObservationsForEntryIds(branchEntries, ids);
+		const refs = findReflectionsForEntryIds(branchEntries, ids);
+		if (obs.length > 0 || refs.length > 0) {
+			return output + "\n\n" + formatRelatedObservations(obs, refs);
+		}
+	} catch { /* branch may not be available */ }
+	return output;
+}
+
+export const registerVccRecallCommand = (pi: ExtensionAPI) => {
+	pi.registerCommand("blackhole-recall", {
+		description:
+			"Search session history. Defaults to active lineage; add scope:all for off-lineage branches. Usage: /blackhole-recall <query> [page:N] [scope:all]",
+		handler: async (args: string, ctx) => {
+			const sessionFile = ctx.sessionManager.getSessionFile();
+			if (!sessionFile) {
+				ctx.ui.notify("No session file available.", "error");
+				return;
+			}
+
+			const raw = args.trim();
+			const parsed = parseRecallScope(raw);
+			const lineageEntryIds =
+				parsed.scope === "lineage"
+					? getActiveLineageEntryIds(ctx.sessionManager)
+					: undefined;
+
+			if (!parsed.text) {
+				// No query: show recent entries
+				const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+				const recent = rendered.slice(-DEFAULT_RECENT);
+				const base = (parsed.scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
+				const output = await augmentWithObservations(base, recent, ctx);
+				pi.sendMessage(
+					{ customType: "blackhole-recall", content: output, display: true },
+					{ triggerTurn: true },
+				);
+				return;
+			}
+
+			// Parse page:N from args
+			const pageMatch = parsed.text.match(/\bpage:(\d+)\b/i);
+			const page = pageMatch ? Math.max(1, parseInt(pageMatch[1], 10)) : 1;
+			const query = parsed.text.replace(/\bpage:\d+\b/i, "").trim();
+
+			if (!query) {
+				const { rendered } = loadAllMessages(sessionFile, false, lineageEntryIds);
+				const recent = rendered.slice(-DEFAULT_RECENT);
+				const base = (parsed.scope === "all" ? "Scope: all\n\n" : "") + formatRecallOutput(recent);
+				const output = await augmentWithObservations(base, recent, ctx);
+				pi.sendMessage(
+					{ customType: "blackhole-recall", content: output, display: true },
+					{ triggerTurn: true },
+				);
+				return;
+			}
+
+			const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
+			const allResults = searchEntries(rendered, rawMessages, query);
+
+			const start = (page - 1) * PAGE_SIZE;
+			const pageResults = allResults.slice(start, start + PAGE_SIZE);
+			const totalPages = Math.ceil(allResults.length / PAGE_SIZE);
+			const scopeSuffix = parsed.scope === "all" ? " (scope: all)" : "";
+			const header =
+				totalPages > 1
+					? `Page ${page}/${totalPages} (${allResults.length} total matches${scopeSuffix})`
+					: `${allResults.length} matches${scopeSuffix}`;
+			const footer =
+				page < totalPages
+					? `\n--- /blackhole-recall ${query}${parsed.scope === "all" ? " scope:all" : ""} page:${page + 1} ---`
+					: "";
+			const base = formatRecallOutput(pageResults, query, header) + footer;
+			const output = await augmentWithObservations(base, pageResults, ctx);
+			pi.sendMessage(
+				{ customType: "blackhole-recall", content: output, display: true },
+				{ triggerTurn: true },
+			);
+		},
+	});
+};