@aexol/spectral 0.3.6 → 0.3.8

package/dist/memory/config.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+export const DEFAULTS = {
+    observationThresholdTokens: 1_000,
+    compactionThresholdTokens: 50_000,
+    reflectionThresholdTokens: 30_000,
+    passive: false,
+    debugLog: false,
+};
+const SETTINGS_KEY = "observational-memory";
+const PASSIVE_ENV = "PI_OBSERVATIONAL_MEMORY_PASSIVE";
+const DEFAULT_MAX_TURNS = 16;
+function positiveIntegerOrUndefined(value) {
+    return Number.isInteger(value) && typeof value === "number" && value > 0 ? value : undefined;
+}
+function normalizeTurnLimit(normalized, key) {
+    if (!(key in normalized))
+        return;
+    const value = positiveIntegerOrUndefined(normalized[key]);
+    if (value === undefined) {
+        delete normalized[key];
+    }
+    else {
+        normalized[key] = value;
+    }
+}
+function normalizeSettingsConfig(value) {
+    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");
+    return normalized;
+}
+export function resolveTurnLimits(config) {
+    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 = process.env) {
+    const rawPassive = env[PASSIVE_ENV];
+    if (rawPassive === undefined)
+        return {};
+    const passive = rawPassive.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(passive))
+        return { passive: true };
+    if (["0", "false", "no", "off"].includes(passive))
+        return { passive: false };
+    return {};
+}
+function readNamespacedConfig(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        const nested = raw[SETTINGS_KEY];
+        return nested && typeof nested === "object" ? normalizeSettingsConfig(nested) : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function loadConfig(cwd, env = process.env) {
+    const globalPath = join(getAgentDir(), "settings.json");
+    const projectPath = join(cwd, ".pi", "settings.json");
+    return {
+        ...DEFAULTS,
+        ...readNamespacedConfig(globalPath),
+        ...readNamespacedConfig(projectPath),
+        ...readEnvConfig(env),
+    };
+}

package/dist/memory/debug-log.js

@@ -0,0 +1,45 @@
+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");
+const storage = new AsyncLocalStorage();
+export function withDebugLogContext(context, fn) {
+    const parent = storage.getStore();
+    return storage.run({ ...parent, ...context }, fn);
+}
+export function isDebugLogEnabled() {
+    return storage.getStore()?.enabled === true;
+}
+export function debugLog(event, data = {}) {
+    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) {
+    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/dist/memory/hooks/compaction-hook.js

@@ -0,0 +1,319 @@
+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 { REFLECTOR_MAX_PASSES, coverageTagCounts, migrateLegacyReflections, observationPoolTokens, renderSummary, runPruner, runReflector, } from "../compaction.js";
+import { observationsToPromptLines, runObserver } from "../observer.js";
+import { CompactionProgressTracker } from "../progress.js";
+import { serializeSourceAddressedBranchEntries } from "../serialize.js";
+import { estimateStringTokens } from "../tokens.js";
+import { OBSERVATION_CUSTOM_TYPE, reflectionToPromptLine, } from "../types.js";
+function plural(count, singular, pluralForm = `${singular}s`) {
+    return `${count.toLocaleString()} ${count === 1 ? singular : pluralForm}`;
+}
+function formatCoverageCounts(counts) {
+    return `${counts.uncited.toLocaleString()}/${counts.cited.toLocaleString()}/${counts.reinforced.toLocaleString()} uncited/cited/reinforced`;
+}
+function formatReflectorStats(stats) {
+    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) {
+    return `pruner dropped ${plural(result.droppedIds.length, "observation")} in ${plural(result.passes.length, "pass", "passes")}, stop: ${result.stopReason}`;
+}
+export function registerCompactionHook(pi, runtime) {
+    pi.on("session_before_compact", async (event, ctx) => {
+        if (runtime.compactHookInFlight) {
+            if (ctx.hasUI)
+                ctx.ui.notify("Observational memory: another compaction is already in progress; cancelling duplicate", "warning");
+            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;
+                // 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 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);
+                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.", "error");
+                    return { cancel: true };
+                }
+                runtime.resolveFailureNotified = false;
+                const updateWidget = () => {
+                    if (!hasUI || !ui)
+                        return;
+                    if (!progress.getPhase()) {
+                        ui.setWidget(WIDGET_NAME, undefined);
+                        return;
+                    }
+                    ui.setWidget(WIDGET_NAME, (_tui, theme) => {
+                        return new Text(progress.formatWidget(theme), 0, 0);
+                    });
+                };
+                clearWidget = () => {
+                    if (hasUI && ui)
+                        ui.setWidget(WIDGET_NAME, undefined);
+                };
+                let entries = branchEntries;
+                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();
+                }
+                const memoryState = getMemoryState(entries);
+                debugLog("compaction.memory_state", {
+                    committedObservations: memoryState.committedObs.length,
+                    pendingObservations: memoryState.pendingObs.length,
+                    reflections: memoryState.reflections.length,
+                });
+                let gapObservationData = 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);
+                        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,
+                            apiKey: resolved.apiKey,
+                            headers: resolved.headers,
+                            priorReflections: memoryState.reflections.map(reflectionToPromptLine),
+                            priorObservations: priorObservationLines,
+                            chunk: gapChunk,
+                            allowedSourceEntryIds: sourceEntryIds,
+                            signal,
+                            maxTurns: turnLimits.observerMaxTurnsPerRun,
+                        });
+                        const gapPromise = 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,
+                                };
+                                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");
+                            }
+                        }
+                        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");
+                            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);
+                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) {
+                    // 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 = migrateLegacyReflections(memoryState.reflections);
+                    debugLog("compaction.no_delta_carry_forward", {
+                        observations: memoryState.committedObs.length,
+                        reflections: workingReflections.length,
+                    });
+                    const summary = renderSummary(workingReflections, memoryState.committedObs);
+                    const details = {
+                        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 = migrateLegacyReflections(memoryState.reflections);
+                const workingObservations = [
+                    ...memoryState.committedObs,
+                    ...deltaObservationData.flatMap((d) => d.records),
+                ];
+                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) {
+                    try {
+                        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, apiKey: resolved.apiKey, headers: resolved.headers, signal, onEvent: (event) => { progress.onEvent(event); updateWidget(); }, maxTurns: turnLimits.reflectorMaxTurnsPerPass }, 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, apiKey: resolved.apiKey, headers: resolved.headers, signal, onEvent: (event) => { progress.onEvent(event); updateWidget(); }, maxTurns: turnLimits.prunerMaxTurnsPerPass }, 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", "warning");
+                        }
+                    }
+                    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");
+                    }
+                }
+                const summary = renderSummary(finalReflections, finalObservations);
+                if (finalObservations.length === 0) {
+                    throw new Error("invariant violated: finalObservations empty after delta guard");
+                }
+                const details = {
+                    type: "observational-memory",
+                    version: 4,
+                    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"}`, "info");
+                return {
+                    compaction: {
+                        summary,
+                        firstKeptEntryId,
+                        tokensBefore,
+                        details,
+                    },
+                };
+            });
+        }
+        finally {
+            runtime.compactHookInFlight = false;
+            progress.clear();
+            clearWidget();
+        }
+    });
+}

package/dist/memory/hooks/compaction-trigger.js

@@ -0,0 +1,87 @@
+import { rawTokensSinceLastCompaction } from "../branch.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, runtime) {
+    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.role === "assistant");
+        if (lastAssistant
+            && lastAssistant.stopReason === "error"
+            && lastAssistant.errorMessage
+            && RETRYABLE_ERROR_RE.test(lastAssistant.errorMessage)) {
+            return;
+        }
+        const entries = ctx.sessionManager.getBranch();
+        const tokens = rawTokensSinceLastCompaction(entries);
+        if (tokens < runtime.config.compactionThresholdTokens)
+            return;
+        // Capture ctx properties synchronously — the setTimeout + async work below
+        // may outlive the extension ctx (stale after session replacement/reload).
+        const hasUI = ctx.hasUI;
+        const ui = ctx.ui;
+        if (hasUI)
+            ui?.notify(`Observational memory: compaction threshold reached (~${tokens.toLocaleString()} tokens); triggering compaction`, "info");
+        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.
+            try {
+                if (!ctx.isIdle()) {
+                    runtime.compactInFlight = false;
+                    if (hasUI)
+                        ui?.notify("Observational memory: compaction deferred — agent became busy after observer wait", "info");
+                    return;
+                }
+                const currentEntries = ctx.sessionManager.getBranch();
+                const currentTokens = rawTokensSinceLastCompaction(currentEntries);
+                if (currentTokens < runtime.config.compactionThresholdTokens) {
+                    runtime.compactInFlight = false;
+                    if (hasUI)
+                        ui?.notify("Observational memory: compaction skipped — another compaction already ran during observer wait", "info");
+                    return;
+                }
+                ctx.compact({
+                    onComplete: () => {
+                        runtime.compactInFlight = false;
+                        if (hasUI)
+                            ui?.notify("Observational memory: compaction complete", "info");
+                    },
+                    onError: (error) => {
+                        runtime.compactInFlight = false;
+                        if (error.message === "Compaction cancelled") {
+                            // We already notified the user with the real reason before returning { cancel: true }.
+                            return;
+                        }
+                        if (hasUI)
+                            ui?.notify(`Observational memory: ${error.message}`, "error");
+                    },
+                });
+            }
+            catch (error) {
+                runtime.compactInFlight = false;
+                const msg = error instanceof Error ? error.message : String(error);
+                if (hasUI)
+                    ui?.notify(`Observational memory: compact threw: ${msg}`, "error");
+            }
+        }, 0);
+    });
+}

package/dist/memory/hooks/observer-trigger.js

@@ -0,0 +1,108 @@
+import { debugLog, withDebugLogContext } from "../debug-log.js";
+import { resolveTurnLimits } from "../config.js";
+import { firstRawIdAfter, getMemoryState, lastObservationCoverEndIdx, rawTailEntriesBetween, rawTokensSinceLastBound, } from "../branch.js";
+import { observationsToPromptLines, runObserver } from "../observer.js";
+import { serializeSourceAddressedBranchEntries } from "../serialize.js";
+import { estimateStringTokens } from "../tokens.js";
+import { OBSERVATION_CUSTOM_TYPE, reflectionToPromptLine } from "../types.js";
+export function registerObserverTrigger(pi, runtime) {
+    pi.on("turn_end", (_event, ctx) => {
+        runtime.ensureConfig(ctx.cwd);
+        if (runtime.config.passive === true)
+            return;
+        if (runtime.observerInFlight)
+            return;
+        const entries = ctx.sessionManager.getBranch();
+        const tokens = rawTokensSinceLastBound(entries);
+        if (tokens < runtime.config.observationThresholdTokens)
+            return;
+        const lastBoundIdx = lastObservationCoverEndIdx(entries);
+        const coversFromId = firstRawIdAfter(entries, lastBoundIdx);
+        if (!coversFromId)
+            return;
+        const leafId = ctx.sessionManager.getLeafId();
+        if (!leafId)
+            return;
+        const coversUpToId = leafId;
+        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;
+        const { text: chunk, sourceEntryIds } = serializeSourceAddressedBranchEntries(chunkEntries);
+        if (!chunk.trim() || sourceEntryIds.length === 0)
+            return;
+        if (ctx.hasUI)
+            ctx.ui.notify(`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 () => 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,
+                    apiKey: resolved.apiKey,
+                    headers: resolved.headers,
+                    priorReflections: reflections.map(reflectionToPromptLine),
+                    priorObservations: priorObservationLines,
+                    chunk,
+                    allowedSourceEntryIds: sourceEntryIds,
+                    maxTurns: turnLimits.observerMaxTurnsPerRun,
+                });
+                if (!records || records.length === 0) {
+                    debugLog("observer.empty", { coversFromId, coversUpToId });
+                    if (hasUI && ui)
+                        ui.notify("Observational memory: observer returned no observations", "warning");
+                    return;
+                }
+                const observationTokens = records.reduce((sum, r) => sum + estimateStringTokens(r.content), 0);
+                const data = {
+                    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: ${records.length} observation${records.length === 1 ? "" : "s"} recorded (~${observationTokens.toLocaleString()} tokens)`, "info");
+            }
+            catch (error) {
+                debugLog("observer.error", { errorMessage: error instanceof Error ? error.message : String(error) });
+                throw error;
+            }
+        }));
+    });
+}

package/dist/memory/ids.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function hashId(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}

package/dist/memory/index.js

@@ -0,0 +1,16 @@
+import { registerStatusCommand } from "./commands/status.js";
+import { registerViewCommand } from "./commands/view.js";
+import { registerCompactionHook } from "./hooks/compaction-hook.js";
+import { registerCompactionTrigger } from "./hooks/compaction-trigger.js";
+import { registerObserverTrigger } from "./hooks/observer-trigger.js";
+import { Runtime } from "./runtime.js";
+import { registerRecallTool } from "./tools/recall-observation.js";
+export default function observationalMemory(pi) {
+    const runtime = new Runtime();
+    registerObserverTrigger(pi, runtime);
+    registerCompactionTrigger(pi, runtime);
+    registerCompactionHook(pi, runtime);
+    registerStatusCommand(pi, runtime);
+    registerViewCommand(pi, runtime);
+    registerRecallTool(pi);
+}