@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/intelligence/session-health-monitor.js

@@ -0,0 +1,211 @@
+/**
+ * Session Health Monitor — detects session degradation via 6 signal types.
+ *
+ * Tracks tool call patterns, entity targeting, convention violations, and
+ * context depth to produce a composite health score (0.0–1.0) and actionable
+ * recommendations. Designed to detect when an AI agent is struggling and
+ * suggest course corrections before the session spirals.
+ *
+ * Signal types:
+ *   1. repeated_query: same entity queried 3+ times (agent is looping)
+ *   2. low_durability_targeting: targeting entity with durability < 0.3
+ *   3. expanding_blast_radius: blast radius growing across queries
+ *   4. convention_violation_spike: 3+ violations within 5 minutes
+ *   5. tool_call_acceleration: tool call rate exceeding 10/min
+ *   6. context_depth_warning: estimated context tokens exceeding 80K
+ *
+ * Health score: starts at 1.0 (perfect), each signal reduces it.
+ */
+import { createModuleLogger } from "../utils/logger.js";
+const log = createModuleLogger("session-health");
+const REPEATED_QUERY_THRESHOLD = 3;
+const LOW_DURABILITY_THRESHOLD = 0.3;
+const VIOLATION_SPIKE_THRESHOLD = 3;
+const VIOLATION_WINDOW_MS = 5 * 60 * 1000;
+const TOOL_CALL_RATE_THRESHOLD = 10;
+const CONTEXT_TOKEN_WARNING = 80_000;
+const CONTEXT_TOKEN_CRITICAL = 120_000;
+const SIGNAL_WEIGHTS = {
+    repeated_query: 0.1,
+    low_durability_targeting: 0.08,
+    expanding_blast_radius: 0.12,
+    convention_violation_spike: 0.15,
+    tool_call_acceleration: 0.1,
+    context_depth_warning: 0.2,
+};
+const TOKENS_PER_TOOL_CALL = 800;
+/**
+ * Creates a session health monitor that accumulates signals over time
+ * and provides a composite health assessment on demand.
+ */
+export function createSessionHealthMonitor() {
+    let toolCalls = [];
+    let conventionViolations = [];
+    let blastRadiusHistory = [];
+    const entityDurability = new Map();
+    const entityQueryCounts = new Map();
+    function recordToolCall(name, entityKey) {
+        const now = Date.now();
+        toolCalls.push({ name, entityKey, timestamp: now });
+        if (entityKey) {
+            const count = entityQueryCounts.get(entityKey) ?? 0;
+            entityQueryCounts.set(entityKey, count + 1);
+        }
+        pruneOldRecords(now);
+    }
+    function recordConventionViolation() {
+        conventionViolations.push(Date.now());
+    }
+    function recordBlastRadius(entityKey, radius) {
+        blastRadiusHistory.push({
+            entityKey,
+            radius,
+            timestamp: Date.now(),
+        });
+    }
+    function recordDurability(entityKey, durability) {
+        entityDurability.set(entityKey, durability);
+    }
+    function getHealth() {
+        const now = Date.now();
+        const signals = [];
+        detectRepeatedQueries(signals);
+        detectLowDurabilityTargeting(signals);
+        detectExpandingBlastRadius(signals);
+        detectConventionViolationSpike(signals, now);
+        detectToolCallAcceleration(signals, now);
+        detectContextDepthWarning(signals);
+        const health = computeHealthScore(signals);
+        const recommendation = deriveRecommendation(health, signals);
+        return { health, signals, recommendation };
+    }
+    function reset() {
+        toolCalls = [];
+        conventionViolations = [];
+        blastRadiusHistory = [];
+        entityDurability.clear();
+        entityQueryCounts.clear();
+    }
+    function detectRepeatedQueries(signals) {
+        for (const [entity, count] of entityQueryCounts) {
+            if (count >= REPEATED_QUERY_THRESHOLD) {
+                signals.push({ type: "repeated_query", entity, count });
+            }
+        }
+    }
+    function detectLowDurabilityTargeting(signals) {
+        const recentEntities = new Set();
+        const recentCalls = toolCalls.slice(-20);
+        for (const call of recentCalls) {
+            if (call.entityKey)
+                recentEntities.add(call.entityKey);
+        }
+        for (const entity of recentEntities) {
+            const durability = entityDurability.get(entity);
+            if (durability !== undefined && durability < LOW_DURABILITY_THRESHOLD) {
+                signals.push({
+                    type: "low_durability_targeting",
+                    entity,
+                    durability,
+                });
+            }
+        }
+    }
+    function detectExpandingBlastRadius(signals) {
+        if (blastRadiusHistory.length < 2)
+            return;
+        const sorted = [...blastRadiusHistory].sort((a, b) => a.timestamp - b.timestamp);
+        const firstThird = sorted.slice(0, Math.max(1, Math.floor(sorted.length / 3)));
+        const lastThird = sorted.slice(Math.max(0, sorted.length - Math.floor(sorted.length / 3)));
+        const initialAvg = firstThird.reduce((sum, r) => sum + r.radius, 0) / firstThird.length;
+        const currentAvg = lastThird.reduce((sum, r) => sum + r.radius, 0) / lastThird.length;
+        if (currentAvg > initialAvg * 1.5 && currentAvg > 5) {
+            signals.push({
+                type: "expanding_blast_radius",
+                initial: Math.round(initialAvg),
+                current: Math.round(currentAvg),
+            });
+        }
+    }
+    function detectConventionViolationSpike(signals, now) {
+        const windowStart = now - VIOLATION_WINDOW_MS;
+        const recentViolations = conventionViolations.filter((ts) => ts >= windowStart);
+        if (recentViolations.length >= VIOLATION_SPIKE_THRESHOLD) {
+            signals.push({
+                type: "convention_violation_spike",
+                count: recentViolations.length,
+                window_min: VIOLATION_WINDOW_MS / 60_000,
+            });
+        }
+    }
+    function detectToolCallAcceleration(signals, now) {
+        const oneMinuteAgo = now - 60_000;
+        const recentCalls = toolCalls.filter((tc) => tc.timestamp >= oneMinuteAgo);
+        if (recentCalls.length >= TOOL_CALL_RATE_THRESHOLD) {
+            signals.push({
+                type: "tool_call_acceleration",
+                rate_per_min: recentCalls.length,
+            });
+        }
+    }
+    function detectContextDepthWarning(signals) {
+        const estimatedTokens = toolCalls.length * TOKENS_PER_TOOL_CALL;
+        if (estimatedTokens >= CONTEXT_TOKEN_WARNING) {
+            signals.push({
+                type: "context_depth_warning",
+                estimated_tokens: estimatedTokens,
+            });
+        }
+    }
+    function pruneOldRecords(now) {
+        const sessionWindow = 60 * 60 * 1000;
+        const cutoff = now - sessionWindow;
+        toolCalls = toolCalls.filter((tc) => tc.timestamp >= cutoff);
+        conventionViolations = conventionViolations.filter((ts) => ts >= cutoff);
+        blastRadiusHistory = blastRadiusHistory.filter((br) => br.timestamp >= cutoff);
+    }
+    return {
+        recordToolCall,
+        recordConventionViolation,
+        recordBlastRadius,
+        recordDurability,
+        getHealth,
+        reset,
+    };
+}
+function computeHealthScore(signals) {
+    let health = 1.0;
+    const signalsByType = new Map();
+    for (const signal of signals) {
+        const count = signalsByType.get(signal.type) ?? 0;
+        signalsByType.set(signal.type, count + 1);
+    }
+    for (const [type, count] of signalsByType) {
+        const weight = SIGNAL_WEIGHTS[type];
+        const scaledPenalty = weight * Math.min(count, 3);
+        health -= scaledPenalty;
+        if (type === "context_depth_warning") {
+            const contextSignal = signals.find((s) => s.type === "context_depth_warning");
+            if (contextSignal &&
+                contextSignal.estimated_tokens >= CONTEXT_TOKEN_CRITICAL) {
+                health -= 0.15;
+            }
+        }
+    }
+    return Math.round(Math.max(0, Math.min(1, health)) * 100) / 100;
+}
+function deriveRecommendation(health, signals) {
+    if (health >= 0.8)
+        return "continue";
+    const hasContextWarning = signals.some((s) => s.type === "context_depth_warning");
+    const hasRepeatedQueries = signals.some((s) => s.type === "repeated_query");
+    if (health < 0.3)
+        return "suggest_new_session";
+    if (hasContextWarning && health < 0.6)
+        return "inject_context_refresh";
+    if (hasRepeatedQueries && health < 0.6)
+        return "suggest_pause";
+    if (health < 0.5)
+        return "suggest_pause";
+    return "inject_context_refresh";
+}

package/dist/intelligence/session-narrative.js

@@ -0,0 +1,197 @@
+/**
+ * Session Narrative Capture — records what was built, why, and how as episodic facts.
+ *
+ * Works in BOTH `unerr` (daemon) and `unerr --mcp` (headless) modes.
+ * Does NOT depend on the behavior framework (which is daemon-only).
+ *
+ * Two capture points:
+ * 1. After each edit-type tool call → captures the investigation chain leading to the edit
+ * 2. At session shutdown → synthesizes a session summary
+ *
+ * All narratives are stored as episodic facts (decay_rate=0.00, never expires).
+ */
+/** Tool intent classification. */
+const TOOL_INTENT = {
+    file_read: "exploration",
+    file_outline: "exploration",
+    get_entity: "investigation",
+    get_references: "investigation",
+    get_imports: "investigation",
+    search_code: "navigation",
+    get_file: "navigation",
+    get_conventions: "investigation",
+    get_critical_nodes: "analysis",
+    get_cross_boundary_links: "analysis",
+    get_project_stats: "analysis",
+    file_connections: "analysis",
+    get_test_coverage: "analysis",
+};
+/** Edit-type tool names (from agents' built-in tools). */
+const EDIT_TOOLS = new Set([
+    "file_write",
+    "write_file",
+    "edit_file",
+    "str_replace_editor",
+    "Write",
+    "Edit",
+]);
+/** Extract feature area from file path (second directory segment). */
+function extractFeatureArea(filePath) {
+    if (!filePath)
+        return "unknown";
+    const parts = filePath.replace(/^\.?\//, "").split("/");
+    // "src/proxy/foo.ts" → "proxy", "src/intelligence/bar.ts" → "intelligence"
+    return parts.length >= 2 ? (parts[1] ?? "unknown") : (parts[0] ?? "unknown");
+}
+/** Classify tool intent. */
+function classifyToolIntent(toolName) {
+    return (TOOL_INTENT[toolName] ??
+        (EDIT_TOOLS.has(toolName) ? "modification" : "other"));
+}
+/** Summarize a tool call for sequence display. */
+function summarizeToolCall(entry) {
+    const args = entry.args_summary;
+    const key = args.key ??
+        args.entity ??
+        args.file_path ??
+        "";
+    const shortKey = key.length > 40 ? `...${key.slice(-37)}` : key;
+    return shortKey ? `${entry.tool}(${shortKey})` : entry.tool;
+}
+export class SessionNarrativeCapture {
+    factStore;
+    ledger;
+    narratives = [];
+    filesModified = new Set();
+    constructor(factStore, ledger) {
+        this.factStore = factStore;
+        this.ledger = ledger;
+    }
+    /**
+     * Called after each edit-type tool call. Captures the investigation chain
+     * leading to the edit as an episodic fact. Non-blocking (caller should use setImmediate).
+     */
+    async captureEditNarrative(editEntry) {
+        const filePath = editEntry.args_summary.file_path ??
+            editEntry.args_summary.path ??
+            "unknown";
+        this.filesModified.add(filePath);
+        // Get recent entries in the correlation window (30s before this edit)
+        const recent = this.ledger.getRecentEntries(50);
+        const editTs = new Date(editEntry.ts).getTime();
+        const windowMs = 30_000;
+        // Find preceding tool calls in the same correlation window
+        const chain = recent.filter((e) => {
+            if (e.id === editEntry.id)
+                return false;
+            const entryTs = new Date(e.ts).getTime();
+            return entryTs >= editTs - windowMs && entryTs <= editTs;
+        });
+        // Build the narrative from the investigation chain
+        const sequence = chain.map(summarizeToolCall);
+        sequence.push(summarizeToolCall(editEntry));
+        // Derive "what" from the edit target
+        const entity = editEntry.args_summary.entity ??
+            editEntry.args_summary.key ??
+            "";
+        const what = entity
+            ? `Modified ${entity} in ${filePath}`
+            : `Modified ${filePath}`;
+        // Derive "why" from the investigation chain
+        const investigationTools = chain.filter((e) => classifyToolIntent(e.tool) === "investigation");
+        const why = investigationTools.length > 0
+            ? `Investigated via ${investigationTools.map((e) => e.tool).join(" → ")} before modifying`
+            : "Direct modification";
+        // Derive "how" from the sequence
+        const how = sequence.length > 1
+            ? sequence.join(" → ")
+            : `Direct edit: ${summarizeToolCall(editEntry)}`;
+        const changeType = editEntry.change_type ?? "modification";
+        const narrative = {
+            file_path: filePath,
+            what,
+            why,
+            how,
+            sequence,
+            change_type: changeType,
+        };
+        this.narratives.push(narrative);
+        // Store as episodic fact (decay=0.00, never expires)
+        const sessionId = this.ledger.getSessionId();
+        const content = `What: ${what}. Why: ${why}. How: ${how}. Sequence: ${sequence.join(", ")}`;
+        await this.factStore.createFact({
+            fact_type: "episodic",
+            scope: filePath,
+            subject: `edit:${sessionId}:${Date.now()}`,
+            content: content.slice(0, 800),
+            source: "session_analysis",
+            confidence: 0.6,
+        });
+    }
+    /**
+     * Called at session shutdown. Synthesizes a session summary from accumulated narratives.
+     * Works in both `unerr` and `unerr --mcp` modes.
+     */
+    async captureSessionSummary(sessionId) {
+        const files = [...this.filesModified];
+        if (this.narratives.length === 0) {
+            return {
+                narratives: [],
+                filesModified: files,
+                summary: "No modifications captured.",
+            };
+        }
+        // Group narratives by feature area
+        const byArea = new Map();
+        for (const n of this.narratives) {
+            const area = extractFeatureArea(n.file_path);
+            let list = byArea.get(area);
+            if (!list) {
+                list = [];
+                byArea.set(area, list);
+            }
+            list.push(n);
+        }
+        // Build summary
+        const areaSummaries = [...byArea.entries()]
+            .map(([area, entries]) => {
+            const whats = entries.map((e) => e.what).slice(0, 3);
+            return `${area}: ${whats.join("; ")}`;
+        })
+            .slice(0, 5);
+        const summary = `Session modified ${files.length} file(s) across ${byArea.size} area(s). ${areaSummaries.join(". ")}`;
+        // Store session summary as episodic fact
+        await this.factStore.createFact({
+            fact_type: "episodic",
+            scope: "project",
+            subject: `session:${sessionId}`,
+            content: summary.slice(0, 800),
+            source: "session_analysis",
+            confidence: 0.7,
+        });
+        return { narratives: this.narratives, filesModified: files, summary };
+    }
+    /** Get narratives captured so far (for display/API). */
+    getNarratives() {
+        return this.narratives;
+    }
+    /** Get files modified this session. */
+    getFilesModified() {
+        return [...this.filesModified];
+    }
+}
+/**
+ * Populate shadow ledger intent fields before append.
+ * Call this to derive change_type, feature_area, plan_summary from tool call context.
+ */
+export function deriveIntentFields(toolName, args, recentEntries) {
+    const filePath = args.file_path ??
+        args.path ??
+        args.key?.split("::")[0];
+    const change_type = classifyToolIntent(toolName);
+    const feature_area = extractFeatureArea(filePath);
+    // Build plan summary from last 3-5 tool calls in correlation window
+    const lastFew = recentEntries.slice(-5);
+    const plan_summary = lastFew.map(summarizeToolCall).join(" → ");
+    return { change_type, feature_area, plan_summary };
+}

package/dist/intelligence/session-pattern-analyzer.js

@@ -0,0 +1,218 @@
+/**
+ * Sprint 5: Session Pattern Analyzer — auto-detects facts from coding session patterns.
+ *
+ * Runs async (not in hot path) at two trigger points:
+ * 1. Every 20 tool calls (daemon mode only, via setImmediate)
+ * 2. At session shutdown (both unerr and unerr --mcp modes)
+ *
+ * Four sub-analyzers (all heuristic, no LLM):
+ * A. Entity Access Frequency — entities accessed 3+ times → procedural fact
+ * B. File Coupling — files co-occurring in correlation window 3+ times → semantic fact
+ * C. Hot File Detection — files read 5+ times → procedural fact
+ * D. Convention Stability — conventions stable across runs → high-confidence convention fact
+ *
+ * All use existing createFact() dedup: duplicate (fact_type, scope, subject) → reinforceFact().
+ *
+ * ── Content shape is forward-only ──────────────────────────────────────
+ * Fact content strings here are persisted to facts.db. Rewriting the
+ * template strings below (e.g., nudge wording v2.1 → v2.2) does NOT
+ * backfill existing rows — old facts keep their original content until
+ * the underlying signal disappears or is dedup-reinforced with new text.
+ * If a future rewrite needs to migrate stored facts, add an explicit
+ * one-shot migration that rewrites by (fact_type, scope, subject) match.
+ */
+/** Correlation window for grouping related tool calls. */
+const CORRELATION_WINDOW_MS = 30_000;
+/** Minimum access count thresholds (Sprint 7: raised to reduce noise). */
+const ENTITY_ACCESS_THRESHOLD = 5;
+const FILE_COUPLING_THRESHOLD = 3; // Already reasonable — keep
+const HOT_FILE_THRESHOLD = 8;
+/** Sprint 7: Minimum actionability — facts below this confidence are noise. */
+const MIN_FACT_CONFIDENCE = 0.4;
+/**
+ * Analyze session patterns from shadow ledger entries and create/reinforce facts.
+ *
+ * Designed to be called asynchronously — not in the tool-call hot path.
+ * Safe to call multiple times (idempotent via createFact dedup).
+ */
+export async function analyzeSessionPatterns(input) {
+    const { ledgerEntries, factStore, sessionId } = input;
+    const result = {
+        factsCreated: 0,
+        factsReinforced: 0,
+        patternsDetected: [],
+    };
+    if (ledgerEntries.length === 0)
+        return result;
+    // Run all sub-analyzers
+    const [entityResults, couplingResults, hotFileResults] = await Promise.all([
+        analyzeEntityAccess(ledgerEntries, factStore, sessionId),
+        analyzeFileCoupling(ledgerEntries, factStore),
+        analyzeHotFiles(ledgerEntries, factStore),
+    ]);
+    // Aggregate results
+    for (const sub of [entityResults, couplingResults, hotFileResults]) {
+        result.factsCreated += sub.factsCreated;
+        result.factsReinforced += sub.factsReinforced;
+        result.patternsDetected.push(...sub.patternsDetected);
+    }
+    return result;
+}
+/**
+ * Sub-analyzer A: Entity Access Frequency.
+ * Entities accessed >= 3 times → procedural fact about entity importance.
+ */
+async function analyzeEntityAccess(entries, factStore, sessionId) {
+    const result = {
+        factsCreated: 0,
+        factsReinforced: 0,
+        patternsDetected: [],
+    };
+    // Count entity accesses from tool args
+    const entityCounts = new Map();
+    for (const entry of entries) {
+        const entityKey = entry.args_summary.key ??
+            entry.args_summary.entity;
+        const filePath = entry.args_summary.file_path ??
+            entry.args_summary.path;
+        if (entityKey) {
+            const existing = entityCounts.get(entityKey);
+            if (existing) {
+                existing.count++;
+                if (filePath)
+                    existing.file = filePath;
+            }
+            else {
+                entityCounts.set(entityKey, {
+                    count: 1,
+                    file: filePath ?? "unknown",
+                });
+            }
+        }
+    }
+    // Create facts for frequently accessed entities
+    for (const [entityKey, data] of entityCounts) {
+        const confidence = Math.min(0.5 + data.count * 0.05, 0.85);
+        if (data.count >= ENTITY_ACCESS_THRESHOLD &&
+            confidence >= MIN_FACT_CONFIDENCE) {
+            await factStore.createFact({
+                fact_type: "procedural",
+                scope: data.file,
+                subject: entityKey,
+                content: `${entityKey} — key entity (accessed ${data.count}× in session ${sessionId}) — pin via record_fact if it's a stable invariant`,
+                source: "session_analysis",
+                confidence,
+            });
+            result.factsCreated++;
+            result.patternsDetected.push(`entity:${entityKey}(${data.count}x)`);
+        }
+    }
+    return result;
+}
+/**
+ * Sub-analyzer B: File Coupling.
+ * Files co-occurring in correlation windows >= 3 times → semantic fact.
+ */
+async function analyzeFileCoupling(entries, factStore) {
+    const result = {
+        factsCreated: 0,
+        factsReinforced: 0,
+        patternsDetected: [],
+    };
+    // Group entries into correlation windows
+    const windows = [];
+    let currentWindow = [];
+    for (const entry of entries) {
+        const ts = new Date(entry.ts).getTime();
+        if (currentWindow.length === 0 ||
+            ts - new Date(currentWindow[0].ts).getTime() <= CORRELATION_WINDOW_MS) {
+            currentWindow.push(entry);
+        }
+        else {
+            if (currentWindow.length > 0)
+                windows.push(currentWindow);
+            currentWindow = [entry];
+        }
+    }
+    if (currentWindow.length > 0)
+        windows.push(currentWindow);
+    // Count file co-occurrences within windows
+    const coOccurrences = new Map();
+    for (const window of windows) {
+        const filesInWindow = new Set();
+        for (const entry of window) {
+            const filePath = entry.args_summary.file_path ??
+                entry.args_summary.path;
+            if (filePath)
+                filesInWindow.add(filePath);
+        }
+        // Generate sorted pairs
+        const fileList = [...filesInWindow].sort();
+        for (let i = 0; i < fileList.length; i++) {
+            for (let j = i + 1; j < fileList.length; j++) {
+                const pairKey = `${fileList[i]}↔${fileList[j]}`;
+                coOccurrences.set(pairKey, (coOccurrences.get(pairKey) ?? 0) + 1);
+            }
+        }
+    }
+    // Create facts for frequently coupled files
+    for (const [pairKey, count] of coOccurrences) {
+        const confidence = Math.min(0.5 + count * 0.05, 0.85);
+        if (count >= FILE_COUPLING_THRESHOLD && confidence >= MIN_FACT_CONFIDENCE) {
+            const [fileA, fileB] = pairKey.split("↔");
+            await factStore.createFact({
+                fact_type: "semantic",
+                scope: "project",
+                subject: `coupling:${pairKey}`,
+                content: `${fileA} ↔ ${fileB} co-change (${count}×) — open both before editing either`,
+                source: "session_analysis",
+                confidence,
+            });
+            result.factsCreated++;
+            result.patternsDetected.push(`coupling:${shortPath(fileA)}↔${shortPath(fileB)}(${count}x)`);
+        }
+    }
+    return result;
+}
+/**
+ * Sub-analyzer C: Hot File Detection.
+ * Files accessed via file_read >= 5 times → procedural fact about file importance.
+ */
+async function analyzeHotFiles(entries, factStore) {
+    const result = {
+        factsCreated: 0,
+        factsReinforced: 0,
+        patternsDetected: [],
+    };
+    const fileCounts = new Map();
+    for (const entry of entries) {
+        const filePath = entry.args_summary.file_path ??
+            entry.args_summary.path;
+        if (filePath) {
+            fileCounts.set(filePath, (fileCounts.get(filePath) ?? 0) + 1);
+        }
+    }
+    for (const [filePath, count] of fileCounts) {
+        const confidence = Math.min(0.5 + count * 0.03, 0.8);
+        if (count >= HOT_FILE_THRESHOLD && confidence >= MIN_FACT_CONFIDENCE) {
+            await factStore.createFact({
+                fact_type: "procedural",
+                scope: filePath,
+                subject: "hot-file",
+                // Imperative tail so the agent has a concrete follow-up — bare
+                // "hot file (N accesses)" is descriptive only and gets discarded.
+                content: `${filePath} — hot file (${count} accesses) — call get_test_coverage to verify it has coverage`,
+                source: "session_analysis",
+                confidence,
+            });
+            result.factsCreated++;
+            result.patternsDetected.push(`hot-file:${shortPath(filePath)}(${count}x)`);
+        }
+    }
+    return result;
+}
+/** Shorten a file path for display (last 2 segments). */
+function shortPath(filePath) {
+    const parts = filePath.split("/");
+    return parts.length > 2 ? parts.slice(-2).join("/") : filePath;
+}