@unerr-ai/unerr 0.2.0 → 0.2.2

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

@@ -1,211 +0,0 @@
-/**
- * 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

@@ -1,197 +0,0 @@
-/**
- * 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

@@ -1,218 +0,0 @@
-/**
- * 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;
-}