@unerr-ai/unerr 0.2.0 → 0.2.2

package/dist/proxy/compression-quality-monitor.js

@@ -1,160 +0,0 @@
-/**
- * Compression Quality Feedback Loop — detects when compression causes agent retries.
- *
- * Monitors agent behavior AFTER compression events. If retry rate spikes
- * within 60s, automatically reduces compression aggressiveness.
- *
- * Adaptive logic:
- *   - Track (compression event) → (next 60s behavior)
- *   - Agent retries same entity OR re-requests same content → "over-compressed"
- *   - 3+ over-compression signals on same content type → increase retention by 20%
- *   - Hard floor: never compress below 40% retention
- *   - Reset: 10+ good compressions → cautiously reduce retention
- *
- * Layer 6 FE-E: per-tool Layer 6 tier (columnar → minified JSON → expanded JSON) after repeated retries.
- */
-const DEFAULT_RETENTION = {
-    git_diff: 0.3,
-    test_output: 0.4,
-    directory: 0.2,
-    file_content: 0.35,
-    generic: 0.25,
-    layer6_columnar: 0.35,
-    shell_tabular: 0.32,
-    shell_structured: 0.3,
-    shell_log_text: 0.34,
-    shell_diff: 0.28,
-    shell_tree_paths: 0.32,
-    shell_key_value: 0.35,
-    shell_error_diagnostic: 0.33,
-    shell_test_results: 0.34,
-    shell_progress_streaming: 0.3,
-    shell_yaml: 0.32,
-};
-const HARD_FLOOR = 0.4;
-const OVER_COMPRESSION_THRESHOLD = 3;
-const RETENTION_INCREASE = 0.2;
-const GOOD_STREAK_THRESHOLD = 10;
-const RETENTION_DECREASE = 0.05;
-const FEEDBACK_WINDOW_MS = 60_000;
-/** FE-E.8 — downgrade Layer 6 wire format after sustained retries per tool name. */
-const LAYER6_TIER_MINIFIED_RETRY = 3;
-const LAYER6_TIER_EXPANDED_RETRY = 6;
-export function createCompressionQualityMonitor() {
-    const recentCompressions = [];
-    const signals = [];
-    const overCompressionCounts = {
-        git_diff: 0,
-        test_output: 0,
-        directory: 0,
-        file_content: 0,
-        generic: 0,
-        layer6_columnar: 0,
-        shell_tabular: 0,
-        shell_structured: 0,
-        shell_log_text: 0,
-        shell_diff: 0,
-        shell_tree_paths: 0,
-        shell_key_value: 0,
-        shell_error_diagnostic: 0,
-        shell_test_results: 0,
-        shell_progress_streaming: 0,
-        shell_yaml: 0,
-    };
-    const goodStreaks = {
-        git_diff: 0,
-        test_output: 0,
-        directory: 0,
-        file_content: 0,
-        generic: 0,
-        layer6_columnar: 0,
-        shell_tabular: 0,
-        shell_structured: 0,
-        shell_log_text: 0,
-        shell_diff: 0,
-        shell_tree_paths: 0,
-        shell_key_value: 0,
-        shell_error_diagnostic: 0,
-        shell_test_results: 0,
-        shell_progress_streaming: 0,
-        shell_yaml: 0,
-    };
-    const adapted = { ...DEFAULT_RETENTION };
-    const layer6RetriesByTool = new Map();
-    function recordCompression(id, contentType, ratio) {
-        recentCompressions.push({ id, contentType, ratio, timestamp: Date.now() });
-        if (recentCompressions.length > 100)
-            recentCompressions.shift();
-    }
-    function recordAgentAction(entityKey, isRetry, isReRequest) {
-        const now = Date.now();
-        const cutoff = now - FEEDBACK_WINDOW_MS;
-        const recentForEntity = recentCompressions.filter((c) => c.timestamp > cutoff);
-        if (recentForEntity.length === 0)
-            return;
-        for (const compression of recentForEntity) {
-            const ct = compression.contentType;
-            if (isRetry || isReRequest) {
-                signals.push({
-                    compressionId: compression.id,
-                    contentType: ct,
-                    compressionRatio: compression.ratio,
-                    followedByRetry: isRetry,
-                    followedByReRequest: isReRequest,
-                    timestamp: now,
-                });
-                overCompressionCounts[ct] = (overCompressionCounts[ct] ?? 0) + 1;
-                goodStreaks[ct] = 0;
-                if ((overCompressionCounts[ct] ?? 0) >= OVER_COMPRESSION_THRESHOLD) {
-                    adapted[ct] = Math.min(1.0, (adapted[ct] ?? DEFAULT_RETENTION[ct]) + RETENTION_INCREASE);
-                    overCompressionCounts[ct] = 0;
-                }
-            }
-            else {
-                goodStreaks[ct] = (goodStreaks[ct] ?? 0) + 1;
-                if ((goodStreaks[ct] ?? 0) >= GOOD_STREAK_THRESHOLD) {
-                    adapted[ct] = Math.max(DEFAULT_RETENTION[ct], (adapted[ct] ?? DEFAULT_RETENTION[ct]) - RETENTION_DECREASE);
-                    goodStreaks[ct] = 0;
-                }
-            }
-        }
-    }
-    function getRetention(contentType) {
-        return Math.max(HARD_FLOOR, adapted[contentType] ?? DEFAULT_RETENTION[contentType]);
-    }
-    function getAdaptiveConfig() {
-        const totalSignals = signals.length;
-        return {
-            minRetention: { ...DEFAULT_RETENTION },
-            adaptedRetention: { ...adapted },
-            confidence: Math.min(1.0, totalSignals * 0.05),
-        };
-    }
-    function getSignalCount() {
-        return signals.length;
-    }
-    function recordLayer6Retry(toolName) {
-        layer6RetriesByTool.set(toolName, (layer6RetriesByTool.get(toolName) ?? 0) + 1);
-    }
-    function getLayer6RetryCount(toolName) {
-        return layer6RetriesByTool.get(toolName) ?? 0;
-    }
-    function getLayer6Tier(toolName) {
-        const n = layer6RetriesByTool.get(toolName) ?? 0;
-        if (n >= LAYER6_TIER_EXPANDED_RETRY)
-            return "expanded";
-        if (n >= LAYER6_TIER_MINIFIED_RETRY)
-            return "minified";
-        return "columnar";
-    }
-    return {
-        recordCompression,
-        recordAgentAction,
-        recordLayer6Retry,
-        getLayer6Tier,
-        getLayer6RetryCount,
-        getAdaptiveConfig,
-        getRetention,
-        getSignalCount,
-    };
-}

package/dist/proxy/compression-stats.js

@@ -1,51 +0,0 @@
-/**
- * Compression Metrics Collector — tracks per-compression stats for the session.
- *
- * Records: content type, original size, compressed size, sections preserved/omitted,
- * annotations added, duration. Feeds into token accounting and the quality feedback loop.
- */
-let eventCounter = 0;
-export function createCompressionStatsCollector() {
-    const events = [];
-    function record(event) {
-        const id = `comp-${++eventCounter}-${Date.now()}`;
-        events.push({ ...event, id, timestamp: Date.now() });
-        return id;
-    }
-    function getEvent(id) {
-        return events.find((e) => e.id === id) ?? null;
-    }
-    function getRecentEvents(count = 20) {
-        return events.slice(-count);
-    }
-    function getSessionStats() {
-        const stats = {
-            totalEvents: events.length,
-            totalOriginalTokens: 0,
-            totalCompressedTokens: 0,
-            totalSaved: 0,
-            avgCompressionRatio: 0,
-            byContentType: {},
-        };
-        for (const event of events) {
-            stats.totalOriginalTokens += event.originalTokens;
-            stats.totalCompressedTokens += event.compressedTokens;
-            const saved = event.originalTokens - event.compressedTokens;
-            stats.totalSaved += saved;
-            const ct = event.contentType;
-            if (!stats.byContentType[ct])
-                stats.byContentType[ct] = { count: 0, saved: 0 };
-            stats.byContentType[ct].count++;
-            stats.byContentType[ct].saved += saved;
-        }
-        stats.avgCompressionRatio =
-            stats.totalOriginalTokens > 0
-                ? Math.round((stats.totalSaved / stats.totalOriginalTokens) * 100) / 100
-                : 0;
-        return stats;
-    }
-    function reset() {
-        events.length = 0;
-    }
-    return { record, getEvent, getRecentEvents, getSessionStats, reset };
-}

package/dist/proxy/context-rot-detector.js

@@ -1,137 +0,0 @@
-/**
- * Context Rot Detector — detects session degradation and injects recovery.
- *
- * U.14: Detects when an ongoing session suffers from context rot:
- *   - Depth threshold: >200K tokens estimated → warning, >300K → critical
- *   - Repeated exploration: agent re-queries delivered entities
- *   - Declining precision: increasing error rate
- *   - Forgotten context: agent requests already-delivered info
- *   - Rule amnesia: convention violated after delivery
- *
- * U.15: Takes corrective action:
- *   - rot 0.4-0.7: inject context refresh
- *   - rot > 0.7: suggest new session
- */
-const DEPTH_WARNING = 200_000;
-const DEPTH_CRITICAL = 300_000;
-const REPEATED_QUERY_THRESHOLD = 3;
-const ERROR_SPIKE_THRESHOLD = 5;
-export function createContextRotDetector() {
-    let estimatedDepth = 0;
-    const queryCountMap = new Map();
-    let recentErrors = 0;
-    const forgottenKeys = [];
-    const amnesiaConventions = [];
-    let lastRefreshContext = null;
-    function recordToolCallTokens(tokens) {
-        estimatedDepth += tokens;
-    }
-    function recordRepeatedQuery(entityKey) {
-        queryCountMap.set(entityKey, (queryCountMap.get(entityKey) ?? 0) + 1);
-    }
-    function recordError() {
-        recentErrors++;
-    }
-    function recordForgottenContext(key, deliveredAt) {
-        forgottenKeys.push({ key, deliveredAt, requeriedAt: Date.now() });
-    }
-    function recordConventionViolationAfterDelivery(convention) {
-        amnesiaConventions.push(convention);
-    }
-    function evaluate() {
-        const signals = [];
-        let rotScore = 0;
-        if (estimatedDepth > DEPTH_CRITICAL) {
-            signals.push({
-                type: "depth_threshold",
-                tokens: estimatedDepth,
-                threshold: DEPTH_CRITICAL,
-            });
-            rotScore += 0.4;
-        }
-        else if (estimatedDepth > DEPTH_WARNING) {
-            signals.push({
-                type: "depth_threshold",
-                tokens: estimatedDepth,
-                threshold: DEPTH_WARNING,
-            });
-            rotScore += 0.2;
-        }
-        for (const [entity, count] of queryCountMap) {
-            if (count >= REPEATED_QUERY_THRESHOLD) {
-                signals.push({
-                    type: "repeated_exploration",
-                    entity,
-                    queryCount: count,
-                });
-                rotScore += 0.15;
-            }
-        }
-        if (recentErrors >= ERROR_SPIKE_THRESHOLD) {
-            signals.push({ type: "declining_precision", recentErrors, window: 10 });
-            rotScore += 0.2;
-        }
-        for (const forgotten of forgottenKeys.slice(-5)) {
-            signals.push({
-                type: "forgotten_context",
-                key: forgotten.key,
-                deliveredAt: forgotten.deliveredAt,
-                requeriedAt: forgotten.requeriedAt,
-            });
-            rotScore += 0.1;
-        }
-        for (const convention of amnesiaConventions.slice(-3)) {
-            signals.push({
-                type: "rule_amnesia",
-                convention,
-                violatedAfterDelivery: true,
-            });
-            rotScore += 0.15;
-        }
-        const rotConfidence = Math.min(1.0, rotScore);
-        let action = "none";
-        if (rotConfidence > 0.7) {
-            action = "suggest_new_session";
-        }
-        else if (rotConfidence > 0.4) {
-            action = "inject_refresh";
-        }
-        if (action === "inject_refresh" || action === "suggest_new_session") {
-            lastRefreshContext = {
-                reason: action === "suggest_new_session"
-                    ? "severe_context_rot"
-                    : "context_degradation",
-                estimated_depth: estimatedDepth,
-                rot_confidence: Math.round(rotConfidence * 100) / 100,
-                repeated_entities: [...queryCountMap.entries()]
-                    .filter(([_, c]) => c >= REPEATED_QUERY_THRESHOLD)
-                    .map(([e]) => e),
-                recommendation: action === "suggest_new_session"
-                    ? "Start a new session. Current context is degraded beyond recovery."
-                    : "Critical context refreshed. Proceed with caution.",
-            };
-        }
-        return { estimatedDepth, rotConfidence, signals, action };
-    }
-    function getRefreshContext() {
-        return lastRefreshContext;
-    }
-    function reset() {
-        estimatedDepth = 0;
-        queryCountMap.clear();
-        recentErrors = 0;
-        forgottenKeys.length = 0;
-        amnesiaConventions.length = 0;
-        lastRefreshContext = null;
-    }
-    return {
-        recordToolCallTokens,
-        recordRepeatedQuery,
-        recordError,
-        recordForgottenContext,
-        recordConventionViolationAfterDelivery,
-        evaluate,
-        getRefreshContext,
-        reset,
-    };
-}

package/dist/proxy/drift-detector.js

@@ -1,139 +0,0 @@
-/**
- * Drift-pattern detector for the Tier 1 nudge system (Nudge v2 / N2).
- *
- * Pure function — no I/O, no state. Given a shell command string, returns
- * either null (no drift) or a structured suggestion describing what unerr
- * MCP tool would have been a better choice.
- *
- * Patterns are kept conservative: only fire when the command CLEARLY
- * targets code, so we don't false-positive on log greps or generic file
- * listings.
- */
-const CODE_EXTENSIONS_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|cs|cpp|c|h|hpp|php|scala|ex|exs|lua|dart|zig|sh|bash|zsh)$/i;
-// `/` is included in the prefix class so absolute paths like
-// `/Users/foo/repo/src/proxy/` also match — agents often grep into source
-// trees by absolute path, and those should fire the drift nudge too.
-const CODE_PATH_HINT_RE = /(?:^|[\s'"/])(?:src|lib|app|test|tests|pkg|cmd|internal|packages|apps|components|hooks|utils|services|controllers|models)\b/;
-/**
- * Strip leading shell decorations (env vars, command chains) and return
- * the first executable token plus its tail.
- */
-function splitFirstCommand(cmd) {
-    // Drop leading `VAR=val VAR2=val2 ` env prefixes
-    let s = cmd.trim().replace(/^(?:[A-Z_][A-Z0-9_]*=\S+\s+)+/, "");
-    // Drop leading `time `, `sudo `, `xargs `, `env -- `
-    s = s.replace(/^(?:time|sudo|xargs|env\s+--)\s+/, "");
-    const sp = s.indexOf(" ");
-    if (sp < 0)
-        return { head: s, tail: "" };
-    return { head: s.slice(0, sp), tail: s.slice(sp + 1) };
-}
-/** Does the command look like it's targeting code (paths or extensions)? */
-function looksLikeCodeTarget(tail) {
-    if (CODE_EXTENSIONS_RE.test(tail))
-        return true;
-    if (CODE_PATH_HINT_RE.test(tail))
-        return true;
-    return false;
-}
-/** Extract the search term from `grep PATTERN paths` / `rg PATTERN paths`. */
-function extractGrepPattern(tail) {
-    // Skip leading flags like -r -n -i -E etc.
-    const parts = tail.match(/(?:"[^"]*"|'[^']*'|\S+)/g) ?? [];
-    for (const p of parts) {
-        if (p.startsWith("-"))
-            continue;
-        return p.replace(/^['"]|['"]$/g, "");
-    }
-    return undefined;
-}
-/** Extract the file path from `cat PATH` / `head PATH` etc. */
-function extractReadPath(tail) {
-    const parts = tail.match(/\S+/g) ?? [];
-    for (const p of parts) {
-        if (p.startsWith("-"))
-            continue;
-        return p;
-    }
-    return undefined;
-}
-/**
- * Inspect a shell command. Return a DriftHint if the command represents a
- * code-navigation task that unerr MCP tools would do better; null otherwise.
- */
-export function isDriftCommand(cmd) {
-    if (!cmd || !cmd.trim())
-        return null;
-    const { head, tail } = splitFirstCommand(cmd);
-    // --- code_search: grep/rg/egrep against code paths ---
-    // TRIM (table row #2): why-leads, drop trailing "— graph-ranked, <5ms" tail.
-    if (/^(grep|rg|egrep|fgrep)$/.test(head)) {
-        if (!looksLikeCodeTarget(tail))
-            return null;
-        const pattern = extractGrepPattern(tail);
-        return {
-            kind: "code_search",
-            suggest: pattern
-                ? `search_code({query:${JSON.stringify(pattern)}}) ranks by graph, <5ms vs full-tree grep`
-                : `search_code({query:"..."}) ranks by graph, <5ms vs full-tree grep`,
-            arg: pattern,
-        };
-    }
-    // --- code_search via `find -name` ---
-    if (head === "find") {
-        if (!/-i?name\b/.test(tail))
-            return null;
-        const m = tail.match(/-i?name\s+(['"]?)([^'"\s]+)\1/);
-        const name = m?.[2];
-        if (!name || !CODE_EXTENSIONS_RE.test(name))
-            return null;
-        return {
-            kind: "code_search",
-            suggest: `search_code({query:${JSON.stringify(name.replace(/^\*\.?|\.$/g, ""))}}) returns entities, not just file paths`,
-            arg: name,
-        };
-    }
-    // --- code_read: cat/head/tail/less on a code file ---
-    // TRIM (table row #1): "auto-loads conventions" before the call template.
-    if (/^(cat|head|tail|less|more|bat)$/.test(head)) {
-        const path = extractReadPath(tail);
-        if (!path)
-            return null;
-        if (!CODE_EXTENSIONS_RE.test(path))
-            return null;
-        return {
-            kind: "code_read",
-            suggest: `file_read({file_path:${JSON.stringify(path)}}) auto-loads conventions; faster than cat`,
-            arg: path,
-        };
-    }
-    // --- dir_explore: ls -R on a source dir ---
-    if (head === "ls") {
-        const flags = tail.match(/-\w+/g)?.join(" ") ?? "";
-        if (!/R/.test(flags))
-            return null;
-        const path = tail
-            .replace(/-\w+\s*/g, "")
-            .trim()
-            .split(/\s+/)[0];
-        if (!path)
-            return null;
-        if (!CODE_PATH_HINT_RE.test(path) && !CODE_PATH_HINT_RE.test(` ${path}`))
-            return null;
-        return {
-            kind: "dir_explore",
-            suggest: `file_outline({file_path:${JSON.stringify(path)}}) returns structure without reading bodies`,
-            arg: path,
-        };
-    }
-    return null;
-}
-/**
- * Build a one-line nudge string for a detected drift. Format is intentionally
- * short to keep the byte cost low — drops the internal "drift(<kind>): try"
- * preamble (unerr taxonomy, not useful to the agent) and leads with the
- * paste-ready call template.
- */
-export function formatDriftNudge(hint) {
-    return `[unerr] ${hint.suggest}`;
-}

package/dist/proxy/efficiency-tracker.js

@@ -1,79 +0,0 @@
-/**
- * Efficiency Metric Tracker — session-scoped token efficiency accumulator.
- *
- * Layer 10 supersession: When a TokenFlowWriter is provided, the tracker
- * derives all metrics from the unified token flow event stream instead of
- * maintaining separate counters. This eliminates dual-counting between
- * EfficiencyTracker and ExplorationCost.
- *
- * When no TokenFlowWriter is available (e.g. degraded mode), falls back
- * to the original in-memory counter implementation.
- */
-import { aggregateSession } from "../tracking/token-flow.js";
-/**
- * Create an efficiency tracker backed by TokenFlowWriter.
- * The `record()` method is a no-op — all tracking is done by the token flow
- * instrumentation points (graph_query, format_encoding, etc.).
- * `getSnapshot()` reads from the token flow event stream.
- */
-export function createEfficiencyTracker(tokenFlow) {
-    if (tokenFlow) {
-        return {
-            record: () => { },
-            getSnapshot: () => {
-                const events = tokenFlow.getSessionEvents();
-                const summary = aggregateSession(events, tokenFlow.sessionId);
-                return {
-                    totalCalls: summary.total_turns,
-                    originalTokens: summary.total_tokens_without,
-                    deliveredTokens: summary.total_tokens_with,
-                    savedTokens: summary.total_tokens_saved,
-                    efficiency: summary.efficiency_pct,
-                    avgSavingsPerCall: summary.total_turns > 0
-                        ? Math.round(summary.total_tokens_saved / summary.total_turns)
-                        : 0,
-                };
-            },
-            getEfficiency: () => tokenFlow.getSessionEfficiency(),
-            getSavedTokens: () => tokenFlow.getSessionTokensSaved(),
-            reset: () => { },
-        };
-    }
-    // Fallback: standalone in-memory tracker (no TokenFlow available)
-    let totalCalls = 0;
-    let originalTokens = 0;
-    let deliveredTokens = 0;
-    return {
-        record(original, delivered) {
-            totalCalls++;
-            originalTokens += original;
-            deliveredTokens += delivered;
-        },
-        getSnapshot() {
-            const saved = Math.max(0, originalTokens - deliveredTokens);
-            return {
-                totalCalls,
-                originalTokens,
-                deliveredTokens,
-                savedTokens: saved,
-                efficiency: originalTokens === 0
-                    ? 0
-                    : Math.round(((originalTokens - deliveredTokens) / originalTokens) * 100),
-                avgSavingsPerCall: totalCalls > 0 ? Math.round(saved / totalCalls) : 0,
-            };
-        },
-        getEfficiency() {
-            if (originalTokens === 0)
-                return 0;
-            return Math.round(((originalTokens - deliveredTokens) / originalTokens) * 100);
-        },
-        getSavedTokens() {
-            return Math.max(0, originalTokens - deliveredTokens);
-        },
-        reset() {
-            totalCalls = 0;
-            originalTokens = 0;
-            deliveredTokens = 0;
-        },
-    };
-}