pi-observational-memory 2.4.2 → 3.0.0

package/src/debug-log.ts

@@ -0,0 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const DEBUG_LOG_MAX_BYTES = 10 * 1024 * 1024;
+export const DEBUG_LOG_RELATIVE_PATH = join("observational-memory", "debug.ndjson");
+
+interface DebugLogContext {
+	enabled: boolean;
+	cwd?: string;
+	runId?: string;
+}
+
+const storage = new AsyncLocalStorage<DebugLogContext>();
+
+export function withDebugLogContext<T>(context: DebugLogContext, fn: () => T): T {
+	const parent = storage.getStore();
+	return storage.run({ ...parent, ...context }, fn);
+}
+
+export function debugLog(event: string, data: Record<string, unknown> = {}): void {
+	const context = storage.getStore();
+	if (context?.enabled !== true) return;
+
+	try {
+		const path = join(getAgentDir(), DEBUG_LOG_RELATIVE_PATH);
+		mkdirSync(dirname(path), { recursive: true });
+		rotateIfNeeded(path);
+		const payload = {
+			ts: new Date().toISOString(),
+			event,
+			cwd: context.cwd,
+			runId: context.runId,
+			data,
+		};
+		appendFileSync(path, `${JSON.stringify(payload)}\n`, "utf-8");
+	} catch {
+		// Debug logging must never affect memory behavior.
+	}
+}
+
+function rotateIfNeeded(path: string): void {
+	if (!existsSync(path)) return;
+	if (statSync(path).size < DEBUG_LOG_MAX_BYTES) return;
+	const backupPath = `${path}.1`;
+	if (existsSync(backupPath)) unlinkSync(backupPath);
+	renameSync(path, backupPath);
+}

package/src/hooks/compaction-hook.ts

@@ -1,207 +1,51 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import {
-	collectObservationsByCoverage,
-	findLastCompactionIndex,
-	gapRawEntries,
-	getMemoryState,
-} from "../branch.js";
-import { migrateLegacyReflections, observationPoolTokens, renderSummary, runPruner, runReflector } from "../compaction.js";
-import { observationsToPromptLines, runObserver } from "../observer.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
 import type { Runtime } from "../runtime.js";
-import { serializeSourceAddressedBranchEntries } from "../serialize.js";
-import { estimateStringTokens } from "../tokens.js";
-import {
-	OBSERVATION_CUSTOM_TYPE,
-	reflectionToPromptLine,
-	type MemoryDetailsV4,
-	type MemoryReflection,
-	type ObservationEntryData,
-	type ObservationRecord,
-} from "../types.js";
+import { buildCompactionProjection, renderSummary, type Entry } from "../session-ledger/index.js";
+
+const DEFAULT_OBSERVATIONS_POOL_MAX_TOKENS = 20_000;
+
+function observationsPoolMaxTokens(runtime: Runtime): number {
+	const value = (runtime.config as { observationsPoolMaxTokens?: unknown }).observationsPoolMaxTokens;
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? value
+		: DEFAULT_OBSERVATIONS_POOL_MAX_TOKENS;
+}
 
 export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
-	pi.on("session_before_compact", async (event, ctx) => {
+	pi.on("session_before_compact", async (event: any, ctx: any) => {
 		if (runtime.compactHookInFlight) {
-			if (ctx.hasUI) ctx.ui.notify(
-				"Observational memory: another compaction is already in progress; cancelling duplicate",
-				"warning",
-			);
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					"Observational memory: another compaction is already in progress; cancelling duplicate",
+					"warning",
+				);
+			}
 			return { cancel: true };
 		}
+
 		runtime.compactHookInFlight = true;
 		try {
 			runtime.ensureConfig(ctx.cwd);
-			const { preparation, branchEntries, signal } = event;
+			const { preparation, branchEntries } = event;
 			const { firstKeptEntryId, tokensBefore } = preparation;
-
-			// Capture ctx properties synchronously — after multiple awaits below,
-			// the extension ctx may become stale (e.g. after session replacement/reload).
-			const hasUI = ctx.hasUI;
-			const ui = ctx.ui;
-
-			const resolved = await runtime.resolveModel(ctx as any);
-			if (!resolved.ok) {
-				if (hasUI) ui?.notify(
-					`Observational memory: cannot compact — ${resolved.reason}. ` +
-					"Fix the model/API key and try /compact manually.",
-					"error",
-				);
-				return { cancel: true };
-			}
-			runtime.resolveFailureNotified = false;
-
-			let entries = branchEntries as Parameters<typeof getMemoryState>[0];
-
-			if (runtime.observerPromise) {
-				try { await runtime.observerPromise; } catch { /* already notified via launchObserverTask */ }
-				// In-flight observer may have appended a new observation entry during the await;
-				// refresh from sessionManager so gap computation and coverage collection see it
-				entries = ctx.sessionManager.getBranch() as typeof entries;
-			}
-
-			const memoryState = getMemoryState(entries);
-
-			let gapObservationData: ObservationEntryData | null = null;
-			const gap = gapRawEntries(entries, firstKeptEntryId);
-			if (gap.length > 0) {
-				const { text: gapChunk, sourceEntryIds } = serializeSourceAddressedBranchEntries(gap);
-				if (gapChunk.trim() && sourceEntryIds.length > 0) {
-					const gapFromId = gap[0].id;
-					const gapUpToId = gap[gap.length - 1].id;
-					const priorObservationLines = observationsToPromptLines([
-						...memoryState.committedObs,
-						...memoryState.pendingObs,
-					]);
-					const gapTokenEstimate = estimateStringTokens(gapChunk);
-					if (hasUI) ui?.notify(
-						`Observational memory: sync catch-up observer running on ~${gapTokenEstimate.toLocaleString()}-token gap`,
-						"info",
-					);
-					runtime.observerInFlight = true;
-					const gapCall = runObserver({
-						model: resolved.model as any,
-						apiKey: resolved.apiKey,
-						headers: resolved.headers,
-						priorReflections: memoryState.reflections.map(reflectionToPromptLine),
-						priorObservations: priorObservationLines,
-						chunk: gapChunk,
-						allowedSourceEntryIds: sourceEntryIds,
-						signal,
-					});
-					const gapPromise: Promise<void> = gapCall.then(() => undefined, () => undefined);
-					runtime.observerPromise = gapPromise;
-					try {
-						const records = await gapCall;
-						if (records && records.length > 0) {
-							const observationTokens = records.reduce((sum, r) => sum + estimateStringTokens(r.content), 0);
-							gapObservationData = {
-								records,
-								coversFromId: gapFromId,
-								coversUpToId: gapUpToId,
-								tokenCount: observationTokens,
-							};
-							pi.appendEntry(OBSERVATION_CUSTOM_TYPE, gapObservationData);
-							if (hasUI && ui) ui.notify(
-								`Observational memory: sync catch-up recorded ${records.length} observation${records.length === 1 ? "" : "s"} (~${observationTokens.toLocaleString()} tokens)`,
-								"info",
-							);
-						} else if (hasUI && ui) {
-							ui.notify(
-								"Observational memory: sync catch-up observer returned empty — proceeding with compaction",
-								"warning",
-							);
-						}
-					} catch (error) {
-						const msg = error instanceof Error ? error.message : String(error);
-						if (hasUI && ui) ui.notify(
-							`Observational memory: sync catch-up observer failed: ${msg}. Cancelling compaction — ${gap.length} unobserved raw entries would be pruned without coverage. Try /compact again.`,
-							"warning",
-						);
-						return { cancel: true };
-					} finally {
-						runtime.observerInFlight = false;
-						if (runtime.observerPromise === gapPromise) runtime.observerPromise = null;
-					}
-				}
-			}
-
-			const priorCompactionIdx = findLastCompactionIndex(entries);
-			const priorFirstKeptEntryId = priorCompactionIdx >= 0 ? entries[priorCompactionIdx].firstKeptEntryId : undefined;
-			const deltaObservationData = collectObservationsByCoverage(entries, priorFirstKeptEntryId, firstKeptEntryId);
-			if (gapObservationData) deltaObservationData.push(gapObservationData);
-
-			if (deltaObservationData.length === 0) {
-				if (hasUI) ui?.notify("Observational memory: nothing to compact yet", "warning");
-				return { cancel: true };
-			}
-
-			const workingReflections: MemoryReflection[] = migrateLegacyReflections(memoryState.reflections);
-			const workingObservations: ObservationRecord[] = [
-				...memoryState.committedObs,
-				...deltaObservationData.flatMap((d) => d.records),
-			];
-
-			const observationTokens = observationPoolTokens(workingObservations);
-
-			let finalReflections = workingReflections;
-			let finalObservations = workingObservations;
-
-			if (observationTokens >= runtime.config.reflectionThresholdTokens) {
-				if (hasUI) ui?.notify("Observational memory: running reflector + pruner...", "info");
-				try {
-					finalReflections = await runReflector(
-						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal },
-						workingReflections,
-						workingObservations,
-					);
-
-					const prunerResult = await runPruner(
-						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal },
-						finalReflections,
-						workingObservations,
-						runtime.config.reflectionThresholdTokens,
-					);
-					finalObservations = prunerResult.observations;
-					if (prunerResult.fellBack && hasUI) {
-						ui?.notify(
-							"Observational memory: pruner run failed; kept observation set unchanged",
-							"warning",
-						);
-					}
-				} catch (error) {
-					const msg = error instanceof Error ? error.message : String(error);
-					if (hasUI) ui?.notify(`Observational memory: reflect/prune failed: ${msg}`, "warning");
-				}
-			}
-
-			const summary = renderSummary(finalReflections, finalObservations);
-
-			if (finalObservations.length === 0) {
-				throw new Error("invariant violated: finalObservations empty after delta guard");
-			}
-
-			const details: MemoryDetailsV4 = {
-				type: "observational-memory",
-				version: 4,
-				observations: finalObservations,
-				reflections: finalReflections,
-			};
-
-			if (hasUI) ui?.notify(
-				`Observational memory: compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}`,
-				"info",
+			const projection = buildCompactionProjection(
+				branchEntries as Entry[],
+				firstKeptEntryId,
+				{ observationsPoolMaxTokens: observationsPoolMaxTokens(runtime) },
 			);
+			const summary = renderSummary(projection.reflections, projection.observations);
 
 			return {
 				compaction: {
 					summary,
 					firstKeptEntryId,
 					tokensBefore,
-					details,
+					details: projection.details,
 				},
 			};
 		} finally {
 			runtime.compactHookInFlight = false;
 		}
 	});
-}
+}

package/src/hooks/compaction-trigger.ts

@@ -1,16 +1,39 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { rawTokensSinceLastCompaction } from "../branch.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { rawTokensSinceLastCompaction, type Entry } from "../session-ledger/index.js";
 import type { Runtime } from "../runtime.js";
 
+/**
+ * Regex matching Pi's internal retryable error detection.
+ * When the last assistant message in agent_end has stopReason "error" matching this pattern,
+ * Pi will auto-retry — we must not trigger compaction between attempts.
+ */
+const RETRYABLE_ERROR_RE =
+	/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i;
+
 export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): void {
-	pi.on("agent_end", (_event, ctx) => {
+	pi.on("agent_end", (event: any, ctx: any) => {
 		runtime.ensureConfig(ctx.cwd);
 		if (runtime.config.passive === true) return;
 		if (runtime.compactInFlight) return;
 
-		const entries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastCompaction>[0];
+		// Don't trigger compaction if Pi will auto-retry — the agent hasn't truly finished.
+		// Pi emits agent_end before its own retry check, so we must detect this ourselves.
+		// The next agent_end (after retry succeeds or exhausts attempts) will re-evaluate.
+		const lastAssistant = [...event.messages].reverse().find(
+			(m): m is Extract<typeof m, { role: "assistant" }> => m.role === "assistant",
+		);
+		if (
+			lastAssistant
+			&& lastAssistant.stopReason === "error"
+			&& lastAssistant.errorMessage
+			&& RETRYABLE_ERROR_RE.test(lastAssistant.errorMessage)
+		) {
+			return;
+		}
+
+		const entries = ctx.sessionManager.getBranch() as Entry[];
 		const tokens = rawTokensSinceLastCompaction(entries);
-		if (tokens < runtime.config.compactionThresholdTokens) return;
+		if (tokens < runtime.config.compactAfterTokens) return;
 
 		// Capture ctx properties synchronously — the setTimeout + async work below
 		// may outlive the extension ctx (stale after session replacement/reload).
@@ -23,31 +46,22 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 		);
 
 		runtime.compactInFlight = true;
-		setTimeout(async () => {
-			if (runtime.observerPromise) {
-				try {
-					await runtime.observerPromise;
-				} catch {
-					// errors already surfaced via launchObserverTask
-				}
-			}
-			// After awaiting observerPromise, ctx may be stale.
-			// Use captured hasUI/ui for notification; wrap ctx access in try/catch.
+		setTimeout(() => {
 			try {
 				if (!ctx.isIdle()) {
 					runtime.compactInFlight = false;
 					if (hasUI) ui?.notify(
-						"Observational memory: compaction deferred — agent became busy after observer wait",
+						"Observational memory: compaction deferred — agent became busy before compaction",
 						"info",
 					);
 					return;
 				}
-				const currentEntries = ctx.sessionManager.getBranch() as Parameters<typeof rawTokensSinceLastCompaction>[0];
+				const currentEntries = ctx.sessionManager.getBranch() as Entry[];
 				const currentTokens = rawTokensSinceLastCompaction(currentEntries);
-				if (currentTokens < runtime.config.compactionThresholdTokens) {
+				if (currentTokens < runtime.config.compactAfterTokens) {
 					runtime.compactInFlight = false;
 					if (hasUI) ui?.notify(
-						"Observational memory: compaction skipped — another compaction already ran during observer wait",
+						"Observational memory: compaction skipped — another compaction already ran before deferred compaction",
 						"info",
 					);
 					return;
@@ -57,7 +71,7 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 						runtime.compactInFlight = false;
 						if (hasUI) ui?.notify("Observational memory: compaction complete", "info");
 					},
-					onError: (error) => {
+					onError: (error: { message: string }) => {
 						runtime.compactInFlight = false;
 						if (error.message === "Compaction cancelled") {
 							// We already notified the user with the real reason before returning { cancel: true }.
@@ -73,4 +87,4 @@ export function registerCompactionTrigger(pi: ExtensionAPI, runtime: Runtime): v
 			}
 		}, 0);
 	});
-}
+}