@unerr-ai/unerr 0.2.0 → 0.2.2

package/dist/server/routes/reasoning-quality.js

@@ -1,444 +0,0 @@
-/**
- * Reasoning Quality API routes for the dashboard.
- *
- * Derives quality/reasoning metrics from existing token flow data.
- * No new tracking infrastructure — all computed from TokenFlowEvent records.
- *
- * GET /api/reasoning-quality/global    → Cross-session quality metrics
- * GET /api/reasoning-quality/session   → Single session quality metrics
- * GET /api/reasoning-quality/sessions  → Per-session quality scores for list view
- */
-import { Hono } from "hono";
-import { readSessionHistory } from "../../tracking/session-history.js";
-import { readTokenFlowEvents, } from "../../tracking/token-flow.js";
-/** Mechanisms that indicate graph-backed precision queries */
-const GRAPH_MECHANISMS = new Set(["graph_query", "file_read"]);
-/** Mechanisms that indicate shell/exec compression */
-const SHELL_MECHANISMS = new Set(["shell_compression"]);
-/** Mechanisms that prevent breakages */
-const SAFETY_MECHANISMS = new Set(["behavior_automation"]);
-/** Mechanism that carries persistent-memory effectiveness verdicts */
-const PERSISTENT_MEMORY_MECHANISM = "persistent_memory";
-function computeQualityMetrics(events) {
-    if (events.length === 0) {
-        return {
-            signal_to_noise_ratio: 0,
-            noise_removed_pct: 0,
-            context_density: 0,
-            entities_resolved: 0,
-            graph_tokens_delivered: 0,
-            attention_multiplier: 1,
-            first_call_resolution_rate: 0,
-            graph_calls: 0,
-            total_tool_calls: 0,
-            turns_saved: 0,
-            exploration_loops_prevented: 0,
-            blast_radius_warnings: 0,
-            circuit_breaker_activations: 0,
-            convention_injections: 0,
-            prevention_score: 0,
-            reasoning_quality_multiplier: 0,
-            total_sessions: 0,
-            total_turns: 0,
-            total_events: 0,
-            facts_surfaced: 0,
-            facts_recalled: 0,
-            facts_recorded: 0,
-            conventions_surfaced: 0,
-            resume_hits: 0,
-            negative_warnings: 0,
-            memory_signals_fired: 0,
-            verdicts_reinforced: 0,
-            verdicts_acted_on: 0,
-            verdicts_ignored: 0,
-            verdicts_corrected: 0,
-            verdicts_caught: 0,
-            memory_verdicts_total: 0,
-            memory_effectiveness_pct: 0,
-        };
-    }
-    let totalWithout = 0;
-    let totalWith = 0;
-    let graphCalls = 0;
-    let graphTokensDelivered = 0;
-    let shellCompressionEvents = 0;
-    let behaviorEvents = 0;
-    let blastRadiusWarnings = 0;
-    let circuitBreakerActivations = 0;
-    let conventionInjections = 0;
-    let explorationLoopsPrevented = 0;
-    let dedupEvents = 0;
-    // Persistent-memory counters
-    let factsSurfaced = 0;
-    let factsRecalled = 0;
-    let factsRecorded = 0;
-    let conventionsSurfaced = 0;
-    let resumeHits = 0;
-    let negativeWarnings = 0;
-    let memorySignalsFired = 0;
-    let verdictsReinforced = 0;
-    let verdictsActedOn = 0;
-    let verdictsIgnored = 0;
-    let verdictsCorrected = 0;
-    let verdictsCaught = 0;
-    const sessions = new Set();
-    const turns = new Set();
-    for (const e of events) {
-        totalWithout += e.tokens_without;
-        totalWith += e.tokens_with;
-        sessions.add(e.session_id);
-        turns.add(`${e.session_id}:${e.turn}`);
-        if (GRAPH_MECHANISMS.has(e.mechanism)) {
-            graphCalls++;
-            graphTokensDelivered += e.tokens_with;
-        }
-        if (SHELL_MECHANISMS.has(e.mechanism)) {
-            shellCompressionEvents++;
-        }
-        if (SAFETY_MECHANISMS.has(e.mechanism)) {
-            behaviorEvents++;
-        }
-        // Extract detail-based counts
-        const d = e.detail;
-        if (d) {
-            // Blast radius warnings: file_read events with callers/references injected
-            if (d.counterfactual === "blast_radius" || d.blast_radius) {
-                blastRadiusWarnings++;
-            }
-            // Circuit breaker activations
-            if (d.circuit_breaker || d.counterfactual === "circuit_breaker") {
-                circuitBreakerActivations++;
-            }
-            // Convention injections: file_read with conventions injected
-            if (d.conventions_injected ||
-                d.counterfactual === "convention_injection") {
-                conventionInjections++;
-            }
-            // Hook redirects (exploration loop prevention)
-            if (d.hook_redirect || d.counterfactual === "hook_redirect") {
-                explorationLoopsPrevented++;
-            }
-        }
-        if (e.mechanism === "session_dedup") {
-            dedupEvents++;
-        }
-        if (e.mechanism === PERSISTENT_MEMORY_MECHANISM && d) {
-            const kind = d.kind;
-            const verdict = d.verdict;
-            if (verdict === "fired") {
-                memorySignalsFired++;
-                switch (kind) {
-                    case "fact_injected":
-                        factsSurfaced++;
-                        break;
-                    case "fact_recalled":
-                        factsRecalled++;
-                        break;
-                    case "fact_recorded":
-                        factsRecorded++;
-                        break;
-                    case "convention_injected":
-                        conventionsSurfaced++;
-                        break;
-                    case "resume_injected":
-                        resumeHits++;
-                        break;
-                    case "negative_warned":
-                        negativeWarnings++;
-                        break;
-                }
-            }
-            else {
-                switch (verdict) {
-                    case "reinforced":
-                        verdictsReinforced++;
-                        break;
-                    case "acted_on":
-                        verdictsActedOn++;
-                        break;
-                    case "ignored":
-                        verdictsIgnored++;
-                        break;
-                    case "corrected":
-                        verdictsCorrected++;
-                        break;
-                    case "caught":
-                        verdictsCaught++;
-                        break;
-                }
-            }
-        }
-    }
-    const totalSaved = totalWithout - totalWith;
-    const totalToolCalls = events.length;
-    // ── Category 1: Context Quality ──
-    // SNR: what fraction of original content was signal (delivered / original)
-    const snr = totalWithout > 0 ? totalWith / totalWithout : 0;
-    const noiseRemovedPct = totalWithout > 0
-        ? Math.round(((totalWithout - totalWith) / totalWithout) * 100)
-        : 0;
-    // Context density: graph events per 1K tokens delivered
-    const contextDensity = graphTokensDelivered > 0
-        ? Math.round((graphCalls / (graphTokensDelivered / 1000)) * 10) / 10
-        : 0;
-    // Attention multiplier: based on the insight that removing N tokens from a
-    // context of size C improves attention quality by approximately C/(C-N).
-    // Conservative estimate: sqrt of compression ratio.
-    const compressionRatio = totalWith > 0 ? totalWithout / totalWith : 1;
-    const attentionMultiplier = Math.round(Math.sqrt(compressionRatio) * 100) / 100;
-    // ── Category 2: Fewer Turns ──
-    const firstCallRate = totalToolCalls > 0 ? Math.round((graphCalls / totalToolCalls) * 100) : 0;
-    // Each graph call saves ~2.5 turns on average (vs grep→read→grep→read cycle)
-    const turnsSaved = Math.round(graphCalls * 2.5);
-    // ── Category 3: Fewer Breakages ──
-    // Also count behavior_automation events as convention injections if not
-    // otherwise categorized
-    const totalConventionInjections = conventionInjections + behaviorEvents;
-    const preventionScore = blastRadiusWarnings +
-        circuitBreakerActivations * 10 +
-        totalConventionInjections;
-    // ── Category 4: Compound ──
-    const firstCallRateDecimal = firstCallRate / 100;
-    const reasoningMultiplier = compressionRatio > 0 && firstCallRateDecimal > 0
-        ? Math.round(compressionRatio * (1 + firstCallRateDecimal) * 100) / 100
-        : 0;
-    // ── Category 5: Persistent Memory ──
-    const verdictsTotal = verdictsReinforced +
-        verdictsActedOn +
-        verdictsIgnored +
-        verdictsCorrected +
-        verdictsCaught;
-    const loadBearing = verdictsReinforced + verdictsActedOn + verdictsCaught;
-    const memoryEffectivenessPct = verdictsTotal > 0 ? Math.round((loadBearing / verdictsTotal) * 100) : 0;
-    return {
-        signal_to_noise_ratio: Math.round(snr * 1000) / 1000,
-        noise_removed_pct: noiseRemovedPct,
-        context_density: contextDensity,
-        entities_resolved: graphCalls,
-        graph_tokens_delivered: graphTokensDelivered,
-        attention_multiplier: attentionMultiplier,
-        first_call_resolution_rate: firstCallRate,
-        graph_calls: graphCalls,
-        total_tool_calls: totalToolCalls,
-        turns_saved: turnsSaved,
-        exploration_loops_prevented: explorationLoopsPrevented,
-        blast_radius_warnings: blastRadiusWarnings,
-        circuit_breaker_activations: circuitBreakerActivations,
-        convention_injections: totalConventionInjections,
-        prevention_score: preventionScore,
-        reasoning_quality_multiplier: reasoningMultiplier,
-        total_sessions: sessions.size,
-        total_turns: turns.size,
-        total_events: events.length,
-        facts_surfaced: factsSurfaced,
-        facts_recalled: factsRecalled,
-        facts_recorded: factsRecorded,
-        conventions_surfaced: conventionsSurfaced,
-        resume_hits: resumeHits,
-        negative_warnings: negativeWarnings,
-        memory_signals_fired: memorySignalsFired,
-        verdicts_reinforced: verdictsReinforced,
-        verdicts_acted_on: verdictsActedOn,
-        verdicts_ignored: verdictsIgnored,
-        verdicts_corrected: verdictsCorrected,
-        verdicts_caught: verdictsCaught,
-        memory_verdicts_total: verdictsTotal,
-        memory_effectiveness_pct: memoryEffectivenessPct,
-    };
-}
-export function createReasoningQualityRoutes(deps) {
-    const app = new Hono();
-    // ── /global — Cross-session quality metrics ─────────────────────
-    app.get("/global", (c) => {
-        const start = performance.now();
-        const fromTs = c.req.query("from_ts");
-        const toTs = c.req.query("to_ts");
-        const events = readTokenFlowEvents(deps.unerrDir, {
-            from_ts: fromTs || undefined,
-            to_ts: toTs || undefined,
-        });
-        const metrics = computeQualityMetrics(events);
-        return c.json({
-            data: metrics,
-            _meta: {
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    // ── /session — Single session quality metrics ───────────────────
-    app.get("/session", (c) => {
-        const start = performance.now();
-        const querySessionId = c.req.query("session_id");
-        const writer = deps.getTokenFlowWriter();
-        const allEvents = readTokenFlowEvents(deps.unerrDir);
-        if (allEvents.length === 0) {
-            return c.json({ data: null, _meta: { latency_ms: 0 } });
-        }
-        let sessionId = querySessionId || writer?.sessionId;
-        if (!sessionId) {
-            sessionId = allEvents[allEvents.length - 1]?.session_id;
-        }
-        if (!sessionId) {
-            return c.json({ data: null, _meta: { latency_ms: 0 } });
-        }
-        const sessionEvents = querySessionId
-            ? allEvents.filter((e) => e.session_id === sessionId)
-            : allEvents.filter((e) => e.session_id === sessionId || e.session_id === "unknown");
-        const metrics = computeQualityMetrics(sessionEvents);
-        // Per-turn quality trajectory (for session health chart)
-        const turnGroups = new Map();
-        for (const e of sessionEvents) {
-            const group = turnGroups.get(e.turn) ?? [];
-            group.push(e);
-            turnGroups.set(e.turn, group);
-        }
-        const trajectory = [];
-        let cumWithout = 0;
-        let cumWith = 0;
-        for (const [turn, turnEvents] of [...turnGroups.entries()].sort(([a], [b]) => a - b)) {
-            let turnGraphCalls = 0;
-            let turnGraphDelivered = 0;
-            for (const e of turnEvents) {
-                cumWithout += e.tokens_without;
-                cumWith += e.tokens_with;
-                if (GRAPH_MECHANISMS.has(e.mechanism)) {
-                    turnGraphCalls++;
-                    turnGraphDelivered += e.tokens_with;
-                }
-            }
-            trajectory.push({
-                turn,
-                snr: cumWithout > 0 ? Math.round((cumWith / cumWithout) * 1000) / 1000 : 0,
-                cumulative_noise_removed_pct: cumWithout > 0
-                    ? Math.round(((cumWithout - cumWith) / cumWithout) * 100)
-                    : 0,
-                graph_calls_this_turn: turnGraphCalls,
-                context_density: turnGraphDelivered > 0
-                    ? Math.round((turnGraphCalls / (turnGraphDelivered / 1000)) * 10) /
-                        10
-                    : 0,
-            });
-        }
-        return c.json({
-            data: {
-                ...metrics,
-                session_id: sessionId,
-                trajectory,
-            },
-            _meta: {
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    // ── /sessions — Quality scores per session for list view ────────
-    app.get("/sessions", (c) => {
-        const start = performance.now();
-        const fromTs = c.req.query("from_ts");
-        const toTs = c.req.query("to_ts");
-        const limit = Math.min(Number(c.req.query("limit") ?? 50), 200);
-        const offset = Math.max(Number(c.req.query("offset") ?? 0), 0);
-        const allEvents = readTokenFlowEvents(deps.unerrDir, {
-            from_ts: fromTs || undefined,
-            to_ts: toTs || undefined,
-        });
-        // Build agent lookup
-        const historyEntries = readSessionHistory(deps.unerrDir);
-        const agentBySession = new Map();
-        for (const h of historyEntries) {
-            if (h.agentName)
-                agentBySession.set(h.sessionId, h.agentName);
-        }
-        // Group events by session
-        const sessionMap = new Map();
-        for (const e of allEvents) {
-            const group = sessionMap.get(e.session_id) ?? [];
-            group.push(e);
-            sessionMap.set(e.session_id, group);
-        }
-        const allSessions = [...sessionMap.entries()]
-            .map(([sessionId, events]) => {
-            const m = computeQualityMetrics(events);
-            const lastTs = events.reduce((max, e) => (e.ts > max ? e.ts : max), events[0].ts);
-            const firstTs = events.reduce((min, e) => (e.ts < min ? e.ts : min), events[0].ts);
-            return {
-                session_id: sessionId,
-                first_ts: firstTs,
-                last_ts: lastTs,
-                agent_name: agentBySession.get(sessionId) ??
-                    deps.getAgentName?.(sessionId) ??
-                    null,
-                noise_removed_pct: m.noise_removed_pct,
-                first_call_resolution_rate: m.first_call_resolution_rate,
-                prevention_score: m.prevention_score,
-                reasoning_quality_multiplier: m.reasoning_quality_multiplier,
-                context_density: m.context_density,
-                turns_saved: m.turns_saved,
-                total_events: m.total_events,
-                total_turns: m.total_turns,
-                memory_effectiveness_pct: m.memory_effectiveness_pct,
-                memory_signals_fired: m.memory_signals_fired,
-                memory_verdicts_total: m.memory_verdicts_total,
-            };
-        })
-            .sort((a, b) => (b.last_ts ?? "").localeCompare(a.last_ts ?? ""));
-        const paginated = allSessions.slice(offset, offset + limit);
-        return c.json({
-            data: paginated,
-            total: allSessions.length,
-            limit,
-            offset,
-            _meta: {
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    // ── /trend — Quality metrics over time (per-session chronological) ─
-    // Powers the "Quality Over Time" temporal chart in the global view.
-    app.get("/trend", (c) => {
-        const start = performance.now();
-        const fromTs = c.req.query("from_ts");
-        const toTs = c.req.query("to_ts");
-        const allEvents = readTokenFlowEvents(deps.unerrDir, {
-            from_ts: fromTs || undefined,
-            to_ts: toTs || undefined,
-        });
-        // Group by session
-        const sessionMap = new Map();
-        for (const e of allEvents) {
-            const group = sessionMap.get(e.session_id) ?? [];
-            group.push(e);
-            sessionMap.set(e.session_id, group);
-        }
-        // Build chronological trend — one data point per session, ordered by time
-        const trend = [...sessionMap.entries()]
-            .map(([sessionId, events]) => {
-            const m = computeQualityMetrics(events);
-            const firstTs = events.reduce((min, e) => (e.ts < min ? e.ts : min), events[0].ts);
-            const lastTs = events.reduce((max, e) => (e.ts > max ? e.ts : max), events[0].ts);
-            return {
-                session_id: sessionId,
-                first_ts: firstTs,
-                last_ts: lastTs,
-                noise_removed_pct: m.noise_removed_pct,
-                first_call_resolution_rate: m.first_call_resolution_rate,
-                prevention_score: m.prevention_score,
-                reasoning_quality_multiplier: m.reasoning_quality_multiplier,
-                context_density: m.context_density,
-                attention_multiplier: m.attention_multiplier,
-                turns_saved: m.turns_saved,
-                total_events: m.total_events,
-                memory_effectiveness_pct: m.memory_effectiveness_pct,
-                memory_signals_fired: m.memory_signals_fired,
-            };
-        })
-            .sort((a, b) => a.first_ts.localeCompare(b.first_ts));
-        return c.json({
-            data: trend,
-            total: trend.length,
-            _meta: {
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    return app;
-}

package/dist/server/routes/session.js

@@ -1,86 +0,0 @@
-/**
- * Layer 7: Session API — live counters, efficiency, intents, shadow ledger.
- */
-import { Hono } from "hono";
-import { computePercentiles, totalCaughtEvents, } from "../../proxy/session-stats.js";
-function parseLimit(raw, fallback, max) {
-    const n = Number.parseInt(raw ?? "", 10);
-    if (Number.isNaN(n) || n < 1)
-        return fallback;
-    return Math.min(n, max);
-}
-export function createSessionRoutes(deps) {
-    const app = new Hono();
-    app.get("/stats", async (c) => {
-        const start = performance.now();
-        const s = deps.stats;
-        const localP = computePercentiles(s.latency.localSamples, s.latency.localTotalSamples);
-        return c.json({
-            data: {
-                tool_calls: s.toolCallsLocal,
-                estimated_tokens_saved: s.estimatedTokensSaved,
-                violations_caught: s.violationsCaught,
-                risk_warnings_issued: s.riskWarningsIssued,
-                session_started_at: new Date(s.sessionStartedAt).toISOString(),
-                is_resumed_session: s.isResumedSession,
-                previous_session: s.previousSession,
-                caught_events: {
-                    ...s.events,
-                    total: totalCaughtEvents(s.events),
-                },
-                latency_ms: localP
-                    ? {
-                        p50: localP.p50,
-                        p95: localP.p95,
-                        p99: localP.p99,
-                        min: localP.min,
-                        max: localP.max,
-                        count: localP.count,
-                    }
-                    : null,
-                local_mode: s.localMode,
-            },
-            _meta: {
-                source: "local",
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    app.get("/efficiency", async (c) => {
-        const start = performance.now();
-        const snap = deps.getEfficiencySnapshot();
-        return c.json({
-            data: snap,
-            _meta: {
-                source: "local",
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    app.get("/intents", async (c) => {
-        const start = performance.now();
-        const groups = deps.getIntentGroups();
-        return c.json({
-            data: groups,
-            _meta: {
-                source: "local",
-                count: groups.length,
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    app.get("/ledger", async (c) => {
-        const start = performance.now();
-        const limit = parseLimit(c.req.query("limit"), 50, 200);
-        const entries = deps.getRecentLedgerEntries(limit);
-        return c.json({
-            data: entries,
-            _meta: {
-                source: "local",
-                count: entries.length,
-                latency_ms: Math.round((performance.now() - start) * 100) / 100,
-            },
-        });
-    });
-    return app;
-}

package/dist/server/routes/stream.js

@@ -1,120 +0,0 @@
-/**
- * Layer 7: SSE endpoint for real-time dashboard updates.
- *
- * GET /api/stream — Server-Sent Events transport.
- *
- * Lifecycle:
- *   1. Send backfill (last 20 events from circular buffer)
- *   2. Subscribe to EventBus for live events
- *   3. Send keepalive ping every 25s
- *   4. On disconnect: unsubscribe, cleanup
- */
-import { Hono } from "hono";
-import { streamSSE } from "hono/streaming";
-import { totalCaughtEvents, } from "../../proxy/session-stats.js";
-import { eventBus } from "../event-bus.js";
-export function createStreamRoutes(deps) {
-    const app = new Hono();
-    app.get("/", (c) => {
-        return streamSSE(c, async (stream) => {
-            let id = 0;
-            let aborted = false;
-            stream.onAbort(() => {
-                aborted = true;
-            });
-            // 1. Send initial session stats
-            await stream.writeSSE({
-                id: String(++id),
-                event: "session_stats",
-                data: JSON.stringify({
-                    tool_calls: deps.stats.toolCallsLocal,
-                    tokens_saved: deps.stats.estimatedTokensSaved,
-                    violations_caught: deps.stats.violationsCaught,
-                    risk_warnings: deps.stats.riskWarningsIssued,
-                    duration_s: Math.round((Date.now() - deps.stats.sessionStartedAt) / 1000),
-                    session_events: deps.stats.events,
-                    caught_total: totalCaughtEvents(deps.stats.events),
-                }),
-            });
-            // 2. Backfill recent events
-            const recent = eventBus.getRecentEvents(20);
-            for (const event of recent) {
-                if (aborted)
-                    return;
-                await stream.writeSSE({
-                    id: String(++id),
-                    event: event.type,
-                    data: JSON.stringify(event.data),
-                });
-            }
-            // 3. Subscribe to live events
-            const unsubscribe = eventBus.subscribe(async (event) => {
-                if (aborted)
-                    return;
-                try {
-                    await stream.writeSSE({
-                        id: String(++id),
-                        event: event.type,
-                        data: JSON.stringify(event.data),
-                    });
-                }
-                catch {
-                    aborted = true;
-                }
-            });
-            // 4. Keepalive ping every 25s
-            const pingInterval = setInterval(async () => {
-                if (aborted) {
-                    clearInterval(pingInterval);
-                    return;
-                }
-                try {
-                    await stream.writeSSE({
-                        id: String(++id),
-                        event: "ping",
-                        data: JSON.stringify({}),
-                    });
-                }
-                catch {
-                    aborted = true;
-                    clearInterval(pingInterval);
-                }
-            }, 25_000);
-            // 5. Session stats tick every 30s
-            const statsInterval = setInterval(async () => {
-                if (aborted) {
-                    clearInterval(statsInterval);
-                    return;
-                }
-                try {
-                    await stream.writeSSE({
-                        id: String(++id),
-                        event: "session_stats",
-                        data: JSON.stringify({
-                            tool_calls: deps.stats.toolCallsLocal,
-                            tokens_saved: deps.stats.estimatedTokensSaved,
-                            violations_caught: deps.stats.violationsCaught,
-                            risk_warnings: deps.stats.riskWarningsIssued,
-                            duration_s: Math.round((Date.now() - deps.stats.sessionStartedAt) / 1000),
-                            session_events: deps.stats.events,
-                            caught_total: totalCaughtEvents(deps.stats.events),
-                        }),
-                    });
-                }
-                catch {
-                    aborted = true;
-                    clearInterval(statsInterval);
-                }
-            }, 30_000);
-            // Block until client disconnects
-            while (!aborted) {
-                await new Promise((resolve) => setTimeout(resolve, 1000));
-            }
-            // Cleanup
-            clearInterval(pingInterval);
-            clearInterval(statsInterval);
-            unsubscribe();
-        });
-    });
-    return app;
-}