pi-observational-memory 2.4.2 → 2.4.3

package/src/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import type { ModelThinkingLevel } from "@mariozechner/pi-ai";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 export interface Config {
@@ -7,7 +8,20 @@ export interface Config {
 	compactionThresholdTokens: number;
 	reflectionThresholdTokens: number;
 	passive: boolean;
+	debugLog: boolean;
 	compactionModel?: { provider: string; id: string };
+	observerMaxTurnsPerRun?: number;
+	reflectorMaxTurnsPerPass?: number;
+	prunerMaxTurnsPerPass?: number;
+	thinkingLevel: ModelThinkingLevel;
+	/** @deprecated Use reflectorMaxTurnsPerPass and prunerMaxTurnsPerPass. */
+	compactionMaxToolCalls?: number;
+}
+
+export interface EffectiveTurnLimits {
+	observerMaxTurnsPerRun: number;
+	reflectorMaxTurnsPerPass: number;
+	prunerMaxTurnsPerPass: number;
 }
 
 export const DEFAULTS: Config = {
@@ -15,17 +29,59 @@ export const DEFAULTS: Config = {
 	compactionThresholdTokens: 50_000,
 	reflectionThresholdTokens: 30_000,
 	passive: false,
+	debugLog: false,
+	thinkingLevel: "low",
 };
 
+export const THINKING_LEVEL_VALUES: readonly ModelThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
 const SETTINGS_KEY = "observational-memory";
 const PASSIVE_ENV = "PI_OBSERVATIONAL_MEMORY_PASSIVE";
+const DEFAULT_MAX_TURNS = 16;
+
+function positiveIntegerOrUndefined(value: unknown): number | undefined {
+	return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : undefined;
+}
+
+function normalizeTurnLimit<K extends keyof Config>(normalized: Partial<Config>, key: K): void {
+	if (!(key in normalized)) return;
+	const value = positiveIntegerOrUndefined(normalized[key]);
+	if (value === undefined) {
+		delete normalized[key];
+	} else {
+		(normalized as Record<K, number>)[key] = value;
+	}
+}
+
+function isThinkingLevel(value: unknown): value is ModelThinkingLevel {
+	return typeof value === "string" && (THINKING_LEVEL_VALUES as readonly string[]).includes(value);
+}
+
+function normalizeThinkingLevel(normalized: Partial<Config>): void {
+	if (!("thinkingLevel" in normalized)) return;
+	if (!isThinkingLevel(normalized.thinkingLevel)) delete normalized.thinkingLevel;
+}
 
 function normalizeSettingsConfig(value: Partial<Config>): Partial<Config> {
 	const normalized = { ...value };
 	if ("passive" in normalized && typeof normalized.passive !== "boolean") delete normalized.passive;
+	if ("debugLog" in normalized && typeof normalized.debugLog !== "boolean") delete normalized.debugLog;
+	normalizeTurnLimit(normalized, "observerMaxTurnsPerRun");
+	normalizeTurnLimit(normalized, "reflectorMaxTurnsPerPass");
+	normalizeTurnLimit(normalized, "prunerMaxTurnsPerPass");
+	normalizeTurnLimit(normalized, "compactionMaxToolCalls");
+	normalizeThinkingLevel(normalized);
 	return normalized;
 }
 
+export function resolveTurnLimits(config: Config): EffectiveTurnLimits {
+	return {
+		observerMaxTurnsPerRun: config.observerMaxTurnsPerRun ?? DEFAULT_MAX_TURNS,
+		reflectorMaxTurnsPerPass: config.reflectorMaxTurnsPerPass ?? config.compactionMaxToolCalls ?? DEFAULT_MAX_TURNS,
+		prunerMaxTurnsPerPass: config.prunerMaxTurnsPerPass ?? config.compactionMaxToolCalls ?? DEFAULT_MAX_TURNS,
+	};
+}
+
 export function readEnvConfig(env: NodeJS.ProcessEnv = process.env): Partial<Config> {
 	const rawPassive = env[PASSIVE_ENV];
 	if (rawPassive === undefined) return {};

package/src/debug-log.ts

@@ -0,0 +1,53 @@
+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 "@mariozechner/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 isDebugLogEnabled(): boolean {
+	return storage.getStore()?.enabled === true;
+}
+
+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,12 +1,27 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { debugLog, withDebugLogContext } from "../debug-log.js";
+import { resolveTurnLimits } from "../config.js";
 import {
 	collectObservationsByCoverage,
 	findLastCompactionIndex,
 	gapRawEntries,
 	getMemoryState,
 } from "../branch.js";
-import { migrateLegacyReflections, observationPoolTokens, renderSummary, runPruner, runReflector } from "../compaction.js";
+import {
+	REFLECTOR_MAX_PASSES,
+	coverageTagCounts,
+	migrateLegacyReflections,
+	observationPoolTokens,
+	renderSummary,
+	runPruner,
+	runReflector,
+	type CoverageTagCounts,
+	type PrunerResult,
+	type ReflectorStats,
+} from "../compaction.js";
 import { observationsToPromptLines, runObserver } from "../observer.js";
+import { CompactionProgressTracker } from "../progress.js";
 import type { Runtime } from "../runtime.js";
 import { serializeSourceAddressedBranchEntries } from "../serialize.js";
 import { estimateStringTokens } from "../tokens.js";
@@ -19,6 +34,23 @@ import {
 	type ObservationRecord,
 } from "../types.js";
 
+function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
+	return `${count.toLocaleString()} ${count === 1 ? singular : pluralForm}`;
+}
+
+function formatCoverageCounts(counts: CoverageTagCounts): string {
+	return `${counts.uncited.toLocaleString()}/${counts.cited.toLocaleString()}/${counts.reinforced.toLocaleString()} uncited/cited/reinforced`;
+}
+
+function formatReflectorStats(stats: ReflectorStats): string {
+	const failed = stats.failedPass === undefined ? "" : `, failed pass ${stats.failedPass}`;
+	return `reflector ${plural(stats.toolCalls, "tool call")}, +${stats.added.toLocaleString()} added, ${stats.merged.toLocaleString()} merged, ${stats.promoted.toLocaleString()} promoted, ${stats.duplicates.toLocaleString()} duplicate/no-op, ${stats.unsupported.toLocaleString()} unsupported${failed}`;
+}
+
+function formatPrunerStats(result: PrunerResult): string {
+	return `pruner dropped ${plural(result.droppedIds.length, "observation")} in ${plural(result.passes.length, "pass", "passes")}, stop: ${result.stopReason}`;
+}
+
 export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void {
 	pi.on("session_before_compact", async (event, ctx) => {
 		if (runtime.compactHookInFlight) {
@@ -29,8 +61,13 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			return { cancel: true };
 		}
 		runtime.compactHookInFlight = true;
+		const progress = new CompactionProgressTracker();
+		const WIDGET_NAME = "om_compact_progress";
+		let clearWidget = () => {};
 		try {
 			runtime.ensureConfig(ctx.cwd);
+			const runId = `compaction-${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 8)}`;
+			return await withDebugLogContext({ enabled: runtime.config.debugLog === true, cwd: ctx.cwd, runId }, async () => {
 			const { preparation, branchEntries, signal } = event;
 			const { firstKeptEntryId, tokensBefore } = preparation;
 
@@ -38,9 +75,19 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			// the extension ctx may become stale (e.g. after session replacement/reload).
 			const hasUI = ctx.hasUI;
 			const ui = ctx.ui;
+			const turnLimits = resolveTurnLimits(runtime.config);
+			debugLog("compaction.start", {
+				firstKeptEntryId,
+				tokensBefore,
+				branchEntryCount: branchEntries.length,
+				reflectionThresholdTokens: runtime.config.reflectionThresholdTokens,
+				turnLimits,
+				legacyCompactionMaxToolCalls: runtime.config.compactionMaxToolCalls,
+			});
 
 			const resolved = await runtime.resolveModel(ctx as any);
 			if (!resolved.ok) {
+				debugLog("compaction.model_unavailable", { reason: resolved.reason });
 				if (hasUI) ui?.notify(
 					`Observational memory: cannot compact — ${resolved.reason}. ` +
 					"Fix the model/API key and try /compact manually.",
@@ -50,6 +97,23 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			}
 			runtime.resolveFailureNotified = false;
 
+			const updateWidget = () => {
+				if (!hasUI || !ui) return;
+				if (!progress.getPhase()) {
+					ui.setWidget(WIDGET_NAME, undefined);
+					return;
+				}
+				ui.setWidget(WIDGET_NAME, (_tui: any, theme: any) => {
+					return new Text(
+						progress.formatWidget(theme),
+						0, 0,
+					);
+				});
+			};
+			clearWidget = () => {
+				if (hasUI && ui) ui.setWidget(WIDGET_NAME, undefined);
+			};
+
 			let entries = branchEntries as Parameters<typeof getMemoryState>[0];
 
 			if (runtime.observerPromise) {
@@ -60,6 +124,11 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			}
 
 			const memoryState = getMemoryState(entries);
+			debugLog("compaction.memory_state", {
+				committedObservations: memoryState.committedObs.length,
+				pendingObservations: memoryState.pendingObs.length,
+				reflections: memoryState.reflections.length,
+			});
 
 			let gapObservationData: ObservationEntryData | null = null;
 			const gap = gapRawEntries(entries, firstKeptEntryId);
@@ -73,10 +142,19 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 						...memoryState.pendingObs,
 					]);
 					const gapTokenEstimate = estimateStringTokens(gapChunk);
+					debugLog("compaction.sync_catchup.start", {
+						gapEntryCount: gap.length,
+						sourceEntryIds,
+						gapFromId,
+						gapUpToId,
+						tokenEstimate: gapTokenEstimate,
+					});
 					if (hasUI) ui?.notify(
 						`Observational memory: sync catch-up observer running on ~${gapTokenEstimate.toLocaleString()}-token gap`,
 						"info",
 					);
+					progress.setPhase("observer", 1, 1);
+					updateWidget();
 					runtime.observerInFlight = true;
 					const gapCall = runObserver({
 						model: resolved.model as any,
@@ -87,6 +165,8 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 						chunk: gapChunk,
 						allowedSourceEntryIds: sourceEntryIds,
 						signal,
+						maxTurns: turnLimits.observerMaxTurnsPerRun,
+						thinkingLevel: runtime.config.thinkingLevel,
 					});
 					const gapPromise: Promise<void> = gapCall.then(() => undefined, () => undefined);
 					runtime.observerPromise = gapPromise;
@@ -100,12 +180,20 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 								coversUpToId: gapUpToId,
 								tokenCount: observationTokens,
 							};
+							debugLog("compaction.sync_catchup.records", {
+								count: records.length,
+								observationTokens,
+								coversFromId: gapFromId,
+								coversUpToId: gapUpToId,
+								records,
+							});
 							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) {
+							debugLog("compaction.sync_catchup.empty", { gapEntryCount: gap.length });
 							ui.notify(
 								"Observational memory: sync catch-up observer returned empty — proceeding with compaction",
 								"warning",
@@ -113,6 +201,7 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 						}
 					} catch (error) {
 						const msg = error instanceof Error ? error.message : String(error);
+						debugLog("compaction.sync_catchup.error", { gapEntryCount: gap.length, errorMessage: msg });
 						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",
@@ -129,10 +218,58 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			const priorFirstKeptEntryId = priorCompactionIdx >= 0 ? entries[priorCompactionIdx].firstKeptEntryId : undefined;
 			const deltaObservationData = collectObservationsByCoverage(entries, priorFirstKeptEntryId, firstKeptEntryId);
 			if (gapObservationData) deltaObservationData.push(gapObservationData);
+			debugLog("compaction.delta", {
+				priorFirstKeptEntryId,
+				firstKeptEntryId,
+				deltaObservationEntries: deltaObservationData.length,
+				deltaObservationRecords: deltaObservationData.reduce((sum, data) => sum + data.records.length, 0),
+				gapObservationRecords: gapObservationData?.records.length ?? 0,
+			});
 
 			if (deltaObservationData.length === 0) {
-				if (hasUI) ui?.notify("Observational memory: nothing to compact yet", "warning");
-				return { cancel: true };
+				// No new observations since last compaction. If we have existing memory,
+				// carry it forward in a no-op compaction so it survives Pi's compaction.
+				// If there is truly nothing (no prior memory either), cancel.
+				if (memoryState.committedObs.length === 0 && memoryState.reflections.length === 0) {
+					debugLog("compaction.no_delta_cancel", {
+						committedObservations: memoryState.committedObs.length,
+						pendingObservations: memoryState.pendingObs.length,
+						reflections: memoryState.reflections.length,
+					});
+					if (hasUI) {
+						ui?.notify(
+							`Observational memory: nothing to compact yet — ${plural(memoryState.committedObs.length, "committed observation")} and ${plural(memoryState.pendingObs.length, "pending observation")}; no eligible delta before compact boundary`,
+							"warning",
+						);
+					}
+					return { cancel: true };
+				}
+
+				// Carry forward existing memory without running reflector/pruner
+				const workingReflections: MemoryReflection[] = migrateLegacyReflections(memoryState.reflections);
+				debugLog("compaction.no_delta_carry_forward", {
+					observations: memoryState.committedObs.length,
+					reflections: workingReflections.length,
+				});
+				const summary = renderSummary(workingReflections, memoryState.committedObs);
+				const details: MemoryDetailsV4 = {
+					type: "observational-memory",
+					version: 4,
+					observations: memoryState.committedObs,
+					reflections: workingReflections,
+				};
+				if (hasUI) ui?.notify(
+					`Observational memory: no new observations — carrying forward ${memoryState.committedObs.length} observation${memoryState.committedObs.length === 1 ? "" : "s"}, ${workingReflections.length} reflection${workingReflections.length === 1 ? "" : "s"}`,
+					"info",
+				);
+				return {
+					compaction: {
+						summary,
+						firstKeptEntryId,
+						tokensBefore,
+						details,
+					},
+				};
 			}
 
 			const workingReflections: MemoryReflection[] = migrateLegacyReflections(memoryState.reflections);
@@ -142,26 +279,68 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 			];
 
 			const observationTokens = observationPoolTokens(workingObservations);
+			debugLog("compaction.reflect_prune.gate", {
+				observationTokens,
+				reflectionThresholdTokens: runtime.config.reflectionThresholdTokens,
+				willRun: observationTokens >= runtime.config.reflectionThresholdTokens,
+				workingObservations: workingObservations.length,
+				workingReflections: workingReflections.length,
+			});
 
 			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 },
+					debugLog("compaction.reflect_prune.start", {
+						workingObservations: workingObservations.length,
+						workingReflections: workingReflections.length,
+						observationTokens,
+					});
+					if (hasUI) ui?.notify("Observational memory: running reflector + pruner...", "info");
+					progress.setPhase("reflector", 1, REFLECTOR_MAX_PASSES);
+					progress.setStartingCounts(workingReflections.length, workingObservations.length);
+					updateWidget();
+					const coverageBefore = coverageTagCounts(workingReflections, workingObservations);
+					const reflectorResult = await runReflector(
+						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal, onEvent: (event) => { progress.onEvent(event); updateWidget(); }, maxTurns: turnLimits.reflectorMaxTurnsPerPass, thinkingLevel: runtime.config.thinkingLevel },
 						workingReflections,
 						workingObservations,
+						(pass, max) => { progress.setPhase("reflector", pass, max); updateWidget(); },
 					);
+					finalReflections = reflectorResult.reflections;
+					const coverageAfter = coverageTagCounts(finalReflections, workingObservations);
+					debugLog("compaction.reflector.result", {
+						stats: reflectorResult.stats,
+						coverageBefore,
+						coverageAfter,
+						beforeReflections: workingReflections.length,
+						afterReflections: finalReflections.length,
+					});
 
 					const prunerResult = await runPruner(
-						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal },
+						{ model: resolved.model as any, apiKey: resolved.apiKey, headers: resolved.headers, signal, onEvent: (event) => { progress.onEvent(event); updateWidget(); }, maxTurns: turnLimits.prunerMaxTurnsPerPass, thinkingLevel: runtime.config.thinkingLevel },
 						finalReflections,
 						workingObservations,
 						runtime.config.reflectionThresholdTokens,
+						(pass, max) => { progress.setPhase("pruner", pass, max); updateWidget(); },
 					);
 					finalObservations = prunerResult.observations;
+					debugLog("compaction.pruner.result", {
+						stopReason: prunerResult.stopReason,
+						fellBack: prunerResult.fellBack,
+						droppedIds: prunerResult.droppedIds,
+						passes: prunerResult.passes,
+						beforeObservations: workingObservations.length,
+						afterObservations: finalObservations.length,
+					});
+					updateWidget();
+					if (hasUI) {
+						ui?.notify(
+							`Observational memory: diagnostics — ${formatReflectorStats(reflectorResult.stats)}; coverage ${formatCoverageCounts(coverageBefore)} → ${formatCoverageCounts(coverageAfter)}; ${formatPrunerStats(prunerResult)}`,
+							"info",
+						);
+					}
 					if (prunerResult.fellBack && hasUI) {
 						ui?.notify(
 							"Observational memory: pruner run failed; kept observation set unchanged",
@@ -170,6 +349,7 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 					}
 				} catch (error) {
 					const msg = error instanceof Error ? error.message : String(error);
+					debugLog("compaction.reflect_prune.error", { errorMessage: msg });
 					if (hasUI) ui?.notify(`Observational memory: reflect/prune failed: ${msg}`, "warning");
 				}
 			}
@@ -186,6 +366,12 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 				observations: finalObservations,
 				reflections: finalReflections,
 			};
+			debugLog("compaction.result", {
+				finalObservations: finalObservations.length,
+				finalReflections: finalReflections.length,
+				firstKeptEntryId,
+				tokensBefore,
+			});
 
 			if (hasUI) ui?.notify(
 				`Observational memory: compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}`,
@@ -200,8 +386,11 @@ export function registerCompactionHook(pi: ExtensionAPI, runtime: Runtime): void
 					details,
 				},
 			};
+			});
 		} finally {
 			runtime.compactHookInFlight = false;
+			progress.clear();
+			clearWidget();
 		}
 	});
 }

package/src/hooks/compaction-trigger.ts

@@ -2,12 +2,35 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { rawTokensSinceLastCompaction } from "../branch.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, ctx) => {
 		runtime.ensureConfig(ctx.cwd);
 		if (runtime.config.passive === true) return;
 		if (runtime.compactInFlight) return;
 
+		// 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 Parameters<typeof rawTokensSinceLastCompaction>[0];
 		const tokens = rawTokensSinceLastCompaction(entries);
 		if (tokens < runtime.config.compactionThresholdTokens) return;

package/src/hooks/observer-trigger.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { debugLog, withDebugLogContext } from "../debug-log.js";
+import { resolveTurnLimits } from "../config.js";
 import {
 	firstRawIdAfter,
 	getMemoryState,
@@ -32,6 +34,7 @@ export function registerObserverTrigger(pi: ExtensionAPI, runtime: Runtime): voi
 
 		const { reflections, committedObs, pendingObs } = getMemoryState(entries);
 		const priorObservationLines = observationsToPromptLines([...committedObs, ...pendingObs]);
+		const turnLimits = resolveTurnLimits(runtime.config);
 
 		const chunkEntries = rawTailEntriesBetween(entries, coversFromId, coversUpToId);
 		if (chunkEntries.length === 0) return;
@@ -42,55 +45,85 @@ export function registerObserverTrigger(pi: ExtensionAPI, runtime: Runtime): voi
 			`Observational memory: observer running on ~${tokens.toLocaleString()}-token chunk`,
 			"info",
 		);
+		const runId = `observer-${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 8)}`;
 
 		// Capture ctx properties synchronously — the async work below may outlive
 		// the extension ctx (stale after session replacement/reload).
 		const hasUI = ctx.hasUI;
 		const ui = ctx.ui;
+		const model = ctx.model;
+		const modelRegistry = ctx.modelRegistry;
+		const cwd = ctx.cwd;
 
-		void runtime.launchObserverTask(ctx, "observer", async () => {
-			const resolved = await runtime.resolveModel(ctx as any);
-			if (!resolved.ok) {
-				if (!runtime.resolveFailureNotified && hasUI && ui) {
-					ui.notify(
-						`Observational memory: observer skipped — ${resolved.reason}`,
+		void runtime.launchObserverTask(ctx, "observer", async () => withDebugLogContext({ enabled: runtime.config.debugLog === true, cwd, runId }, async () => {
+			try {
+				debugLog("observer.start", {
+					tokens,
+					coversFromId,
+					coversUpToId,
+					sourceEntryIds,
+					sourceEntryCount: sourceEntryIds.length,
+					priorReflections: reflections.length,
+					priorObservations: priorObservationLines.length,
+				});
+				const resolved = await runtime.resolveModel({ model, modelRegistry, hasUI, ui });
+				if (!resolved.ok) {
+					debugLog("observer.model_unavailable", { reason: resolved.reason });
+					if (!runtime.resolveFailureNotified && hasUI && ui) {
+						ui.notify(
+							`Observational memory: observer skipped — ${resolved.reason}`,
+							"warning",
+						);
+						runtime.resolveFailureNotified = true;
+					}
+					return;
+				}
+				runtime.resolveFailureNotified = false;
+
+				const records = await runObserver({
+					model: resolved.model as any,
+					apiKey: resolved.apiKey,
+					headers: resolved.headers,
+					priorReflections: reflections.map(reflectionToPromptLine),
+					priorObservations: priorObservationLines,
+					chunk,
+					allowedSourceEntryIds: sourceEntryIds,
+					maxTurns: turnLimits.observerMaxTurnsPerRun,
+					thinkingLevel: runtime.config.thinkingLevel,
+				});
+				if (!records || records.length === 0) {
+					debugLog("observer.empty", { coversFromId, coversUpToId });
+					if (hasUI && ui) ui.notify(
+						"Observational memory: observer returned no observations",
 						"warning",
 					);
-					runtime.resolveFailureNotified = true;
+					return;
 				}
-				return;
-			}
-			runtime.resolveFailureNotified = false;
 
-			const records = await runObserver({
-				model: resolved.model as any,
-				apiKey: resolved.apiKey,
-				headers: resolved.headers,
-				priorReflections: reflections.map(reflectionToPromptLine),
-				priorObservations: priorObservationLines,
-				chunk,
-				allowedSourceEntryIds: sourceEntryIds,
-			});
-			if (!records || records.length === 0) {
+				const observationTokens = records.reduce((sum, r) => sum + estimateStringTokens(r.content), 0);
+				const data: ObservationEntryData = {
+					records,
+					coversFromId,
+					coversUpToId,
+					tokenCount: observationTokens,
+				};
+				debugLog("observer.records", {
+					count: records.length,
+					observationTokens,
+					coversFromId,
+					coversUpToId,
+					records,
+				});
+				pi.appendEntry(OBSERVATION_CUSTOM_TYPE, data);
+				debugLog("observer.appended", { count: records.length, tokenCount: observationTokens, coversFromId, coversUpToId });
 				if (hasUI && ui) ui.notify(
-					"Observational memory: observer returned no observations",
-					"warning",
+					`Observational memory: ${records.length} observation${records.length === 1 ? "" : "s"} recorded (~${observationTokens.toLocaleString()} tokens)`,
+					"info",
 				);
-				return;
+			} catch (error) {
+				debugLog("observer.error", { errorMessage: error instanceof Error ? error.message : String(error) });
+				throw error;
 			}
-
-			const observationTokens = records.reduce((sum, r) => sum + estimateStringTokens(r.content), 0);
-			const data: ObservationEntryData = {
-				records,
-				coversFromId,
-				coversUpToId,
-				tokenCount: observationTokens,
-			};
-			pi.appendEntry(OBSERVATION_CUSTOM_TYPE, data);
-			if (hasUI && ui) ui.notify(
-				`Observational memory: ${records.length} observation${records.length === 1 ? "" : "s"} recorded (~${observationTokens.toLocaleString()} tokens)`,
-				"info",
-			);
-		});
+		}));
 	});
 }

package/src/model-budget.ts

@@ -0,0 +1,9 @@
+import type { Model } from "@mariozechner/pi-ai";
+
+export const AGENT_LOOP_MAX_TOKENS = 32_000;
+
+export function boundedMaxTokens(model: Model<any>, requested: number = AGENT_LOOP_MAX_TOKENS): number {
+	return typeof model.maxTokens === "number" && model.maxTokens > 0
+		? Math.min(model.maxTokens, requested)
+		: requested;
+}