@unerr-ai/unerr 0.1.0 → 0.1.1

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

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

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

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