@unerr-ai/unerr 0.0.1 → 0.1.1

package/dist/server/routes/token-flow.js

@@ -0,0 +1,403 @@
+/**
+ * Layer 10 TF-D.1: Token Flow API routes for the dashboard.
+ *
+ * GET /api/token-flow/session      → Current session summary with mechanism breakdown
+ * GET /api/token-flow/sessions     → All session IDs with summary stats
+ * GET /api/token-flow/history      → Last 20 sessions with tokenFlowSummary
+ * GET /api/token-flow/events       → Events (optional ?turn=N, ?mechanism=X, ?session_id=Y)
+ * GET /api/token-flow/cumulative   → Per-turn cumulative totals for chart rendering
+ *
+ * RC1 fix: All reads come from `.unerr/metrics.db` (readTokenFlowEvents), NOT
+ * the proxy's in-memory buffer. The proxy process never handles tool calls —
+ * `unerr --mcp` does. The proxy's TokenFlowWriter in-memory buffer is always
+ * empty for tool-call events.
+ */
+import { Hono } from "hono";
+import { readSessionHistory } from "../../tracking/session-history.js";
+import { aggregateSession, readTokenFlowEvents, } from "../../tracking/token-flow.js";
+/**
+ * Token-trace surfaces *byte savings* — persistent_memory events carry
+ * effectiveness verdicts (zero saved bytes by design) and belong exclusively
+ * to the /reasoning page. Strip them from every read in this route.
+ */
+function stripPersistentMemory(events) {
+    return events.filter((e) => e.mechanism !== "persistent_memory");
+}
+export function createTokenFlowRoutes(deps) {
+    const app = new Hono();
+    // ── /session — Current session summary ───────────────────────────
+    // RC1 fix: Read from disk JSONL, not in-memory buffer.
+    // The proxy's writer has the correct sessionId but no events (tool calls
+    // happen in the --mcp process). Disk has all events from all processes.
+    app.get("/session", (c) => {
+        const start = performance.now();
+        const writer = deps.getTokenFlowWriter();
+        const querySessionId = c.req.query("session_id");
+        // Read ALL events from disk (persistent_memory excluded — /reasoning only)
+        const allEvents = stripPersistentMemory(readTokenFlowEvents(deps.unerrDir));
+        // Priority: query param > proxy writer > most recent from disk
+        let sessionId = querySessionId || writer?.sessionId;
+        if (!sessionId && allEvents.length > 0) {
+            sessionId = allEvents[allEvents.length - 1]?.session_id;
+        }
+        // No events AND no resolvable session id — return zeroed summary
+        // (empty shape, not null, so consumers can read fields uniformly).
+        if (allEvents.length === 0 || !sessionId) {
+            return c.json({
+                data: {
+                    ...aggregateSession([], sessionId ?? "unknown"),
+                    event_count: 0,
+                },
+                _meta: {
+                    latency_ms: Math.round((performance.now() - start) * 100) / 100,
+                },
+            });
+        }
+        // Filter events for this session. When using query param (explicit selection),
+        // don't include "unknown" events — only include them for current session.
+        const sessionEvents = querySessionId
+            ? allEvents.filter((e) => e.session_id === sessionId)
+            : allEvents.filter((e) => e.session_id === sessionId || e.session_id === "unknown");
+        const summary = aggregateSession(sessionEvents, sessionId);
+        // If filtering by sessionId yields nothing, try aggregating all "unknown" events
+        // as they likely belong to the current session
+        if (summary.total_tokens_saved === 0) {
+            const unknownEvents = allEvents.filter((e) => e.session_id === "unknown");
+            if (unknownEvents.length > 0) {
+                const fallbackSummary = aggregateSession(unknownEvents, "unknown");
+                return c.json({
+                    data: {
+                        ...fallbackSummary,
+                        session_id: sessionId,
+                        event_count: unknownEvents.length,
+                    },
+                    _meta: {
+                        latency_ms: Math.round((performance.now() - start) * 100) / 100,
+                    },
+                });
+            }
+        }
+        return c.json({
+            data: {
+                ...summary,
+                event_count: sessionEvents.length,
+            },
+            _meta: {
+                latency_ms: Math.round((performance.now() - start) * 100) / 100,
+            },
+        });
+    });
+    // ── /global — Cross-session aggregate (all time or date range) ──
+    // Powers the Global view KPIs: total saved/delivered across ALL sessions.
+    // Supports: ?from_ts=ISO&to_ts=ISO
+    app.get("/global", (c) => {
+        const start = performance.now();
+        const fromTs = c.req.query("from_ts");
+        const toTs = c.req.query("to_ts");
+        const allEvents = stripPersistentMemory(readTokenFlowEvents(deps.unerrDir, {
+            from_ts: fromTs || undefined,
+            to_ts: toTs || undefined,
+        }));
+        const emptyCompound = {
+            total_sessions: 0,
+            total_turns: 0,
+            total_tokens_without: 0,
+            total_tokens_with: 0,
+            total_tokens_saved: 0,
+            efficiency_pct: 0,
+            by_mechanism: {},
+            event_count: 0,
+            avg_context_reduction: 0,
+            peak_context_reduction: 0,
+            total_context_avoided: 0,
+        };
+        if (allEvents.length === 0) {
+            return c.json({ data: emptyCompound, _meta: { latency_ms: 0 } });
+        }
+        let totalWithout = 0;
+        let totalWith = 0;
+        let totalSaved = 0;
+        const sessions = new Set();
+        const turns = new Set(); // "session:turn" for dedup
+        const mechMap = new Map();
+        for (const e of allEvents) {
+            totalWithout += e.tokens_without;
+            totalWith += e.tokens_with;
+            totalSaved += e.tokens_saved;
+            sessions.add(e.session_id);
+            turns.add(`${e.session_id}:${e.turn}`);
+            const m = mechMap.get(e.mechanism) ?? {
+                saved: 0,
+                delivered: 0,
+                count: 0,
+            };
+            m.saved += e.tokens_saved;
+            m.delivered += e.tokens_with;
+            m.count++;
+            mechMap.set(e.mechanism, m);
+        }
+        // Compound savings: per-session, per-turn cumulative sums.
+        // Context resets between sessions, so compute independently per session.
+        const sessionTurnSaved = new Map();
+        for (const e of allEvents) {
+            let turnMap = sessionTurnSaved.get(e.session_id);
+            if (!turnMap) {
+                turnMap = new Map();
+                sessionTurnSaved.set(e.session_id, turnMap);
+            }
+            turnMap.set(e.turn, (turnMap.get(e.turn) ?? 0) + e.tokens_saved);
+        }
+        let compoundTotal = 0;
+        for (const turnMap of sessionTurnSaved.values()) {
+            const sortedTurns = [...turnMap.entries()].sort(([a], [b]) => a - b);
+            let cumSaved = 0;
+            for (const [, saved] of sortedTurns) {
+                cumSaved += saved;
+                compoundTotal += cumSaved;
+            }
+        }
+        const byMechanism = {};
+        for (const [mech, data] of mechMap) {
+            byMechanism[mech] = {
+                tokens_saved: data.saved,
+                tokens_delivered: data.delivered,
+                event_count: data.count,
+                pct_of_total: totalSaved > 0 ? Math.round((data.saved / totalSaved) * 100) : 0,
+            };
+        }
+        return c.json({
+            data: {
+                total_sessions: sessions.size,
+                total_turns: turns.size,
+                total_tokens_without: totalWithout,
+                total_tokens_with: totalWith,
+                total_tokens_saved: totalSaved,
+                efficiency_pct: totalWithout > 0 ? Math.round((totalSaved / totalWithout) * 100) : 0,
+                by_mechanism: byMechanism,
+                event_count: allEvents.length,
+                avg_context_reduction: turns.size > 0 ? Math.round(compoundTotal / turns.size) : 0,
+                peak_context_reduction: totalSaved,
+                total_context_avoided: compoundTotal,
+            },
+            _meta: {
+                latency_ms: Math.round((performance.now() - start) * 100) / 100,
+            },
+        });
+    });
+    // ── /sessions — List all unique session IDs ─────────────────────
+    // Supports: ?limit=N&offset=N&from_ts=ISO&to_ts=ISO
+    app.get("/sessions", (c) => {
+        const start = performance.now();
+        const fromTs = c.req.query("from_ts");
+        const toTs = c.req.query("to_ts");
+        // Pagination is opt-in: callers without a `limit` get all sessions so they
+        // can compute aggregates that match `/global`. UI clients pass an explicit
+        // limit when they want a paginated view (capped at 200).
+        const rawLimit = c.req.query("limit");
+        const limit = rawLimit !== undefined
+            ? Math.min(Math.max(Number(rawLimit), 1), 200)
+            : Number.MAX_SAFE_INTEGER;
+        const offset = Math.max(Number(c.req.query("offset") ?? 0), 0);
+        const allEvents = stripPersistentMemory(readTokenFlowEvents(deps.unerrDir, {
+            from_ts: fromTs || undefined,
+            to_ts: toTs || undefined,
+        }));
+        // Build agent lookup from session history
+        const historyEntries = readSessionHistory(deps.unerrDir);
+        const agentBySession = new Map();
+        for (const h of historyEntries) {
+            if (h.agentName)
+                agentBySession.set(h.sessionId, h.agentName);
+        }
+        const sessionMap = new Map();
+        for (const e of allEvents) {
+            const entry = sessionMap.get(e.session_id) ?? {
+                event_count: 0,
+                total_saved: 0,
+                first_ts: e.ts,
+                last_ts: e.ts,
+                mechanisms: new Set(),
+                turnSaved: new Map(),
+            };
+            entry.event_count++;
+            entry.total_saved += e.tokens_saved;
+            if (e.ts < entry.first_ts)
+                entry.first_ts = e.ts;
+            if (e.ts > entry.last_ts)
+                entry.last_ts = e.ts;
+            entry.mechanisms.add(e.mechanism);
+            entry.turnSaved.set(e.turn, (entry.turnSaved.get(e.turn) ?? 0) + e.tokens_saved);
+            sessionMap.set(e.session_id, entry);
+        }
+        const allSessions = [...sessionMap.entries()]
+            .map(([id, data]) => {
+            // Compute avg context reduction: compound total / num turns
+            const sortedTurns = [...data.turnSaved.entries()].sort(([a], [b]) => a - b);
+            let cumSaved = 0;
+            let compoundTotal = 0;
+            for (const [, saved] of sortedTurns) {
+                cumSaved += saved;
+                compoundTotal += cumSaved;
+            }
+            const numTurns = sortedTurns.length;
+            return {
+                session_id: id,
+                event_count: data.event_count,
+                total_saved: data.total_saved,
+                total_turns: numTurns,
+                avg_context_reduction: numTurns > 0 ? Math.round(compoundTotal / numTurns) : 0,
+                first_ts: data.first_ts,
+                last_ts: data.last_ts,
+                mechanisms: [...data.mechanisms],
+                agent_name: agentBySession.get(id) ?? deps.getAgentName?.(id) ?? null,
+            };
+        })
+            .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,
+            },
+        });
+    });
+    // ── /history — Recent sessions from session-history.jsonl ───────
+    app.get("/history", (c) => {
+        const start = performance.now();
+        const limit = Math.min(Number(c.req.query("limit") ?? 20), 50);
+        const entries = readSessionHistory(deps.unerrDir);
+        const withFlow = entries
+            .filter((e) => e.tokenFlowSummary)
+            .slice(-limit)
+            .reverse();
+        return c.json({
+            data: withFlow.map((e) => ({
+                session_id: e.sessionId,
+                started_at: e.startedAt,
+                ended_at: e.endedAt,
+                duration_ms: e.durationMs,
+                tool_calls: e.toolCalls,
+                tokens_saved: e.tokensSaved,
+                efficiency: e.efficiency,
+                token_flow: e.tokenFlowSummary,
+            })),
+            total: withFlow.length,
+            _meta: {
+                latency_ms: Math.round((performance.now() - start) * 100) / 100,
+            },
+        });
+    });
+    // ── /events — Events with filters ───────────────────────────────
+    // Supports: ?session_id=X&turn=N&mechanism=X&from_ts=ISO&to_ts=ISO&limit=N&offset=N
+    // RC1 fix: Always read from disk, not in-memory.
+    app.get("/events", (c) => {
+        const start = performance.now();
+        const turnFilter = c.req.query("turn");
+        const mechanismFilter = c.req.query("mechanism");
+        const sessionFilter = c.req.query("session_id");
+        const fromTs = c.req.query("from_ts");
+        const toTs = c.req.query("to_ts");
+        const limit = Math.min(Number(c.req.query("limit") ?? 200), 500);
+        const offset = Math.max(Number(c.req.query("offset") ?? 0), 0);
+        // Always read from disk — the proxy process has no in-memory events
+        let events = stripPersistentMemory(readTokenFlowEvents(deps.unerrDir, {
+            session_id: sessionFilter || undefined,
+            mechanism: mechanismFilter || undefined,
+            from_ts: fromTs || undefined,
+            to_ts: toTs || undefined,
+        }));
+        // If no session filter provided, include current session + "unknown"
+        if (!sessionFilter) {
+            const writer = deps.getTokenFlowWriter();
+            if (writer) {
+                events = events.filter((e) => e.session_id === writer.sessionId || e.session_id === "unknown");
+            }
+        }
+        if (turnFilter) {
+            const turnNum = Number(turnFilter);
+            if (!Number.isNaN(turnNum)) {
+                events = events.filter((e) => e.turn === turnNum);
+            }
+        }
+        const paginated = events.slice(offset, offset + limit);
+        return c.json({
+            data: paginated,
+            total: events.length,
+            limit,
+            offset,
+            _meta: {
+                latency_ms: Math.round((performance.now() - start) * 100) / 100,
+            },
+        });
+    });
+    // ── /cumulative — Per-turn cumulative totals for charts ─────────
+    app.get("/cumulative", (c) => {
+        const start = performance.now();
+        const sessionFilter = c.req.query("session_id");
+        const writer = deps.getTokenFlowWriter();
+        let events = stripPersistentMemory(readTokenFlowEvents(deps.unerrDir));
+        // Filter to relevant session
+        const targetSession = sessionFilter ?? writer?.sessionId;
+        if (targetSession) {
+            events = events.filter((e) => e.session_id === targetSession || e.session_id === "unknown");
+        }
+        // Sort by turn, then by timestamp within turn
+        events.sort((a, b) => a.turn - b.turn || a.ts.localeCompare(b.ts));
+        // Build cumulative per-turn data
+        const turnData = [];
+        const cumulativeMechanisms = {};
+        let cumulativeSaved = 0;
+        let contextTurnsTotal = 0; // sum of cumulative savings at each turn
+        // Group events by turn
+        const turnGroups = new Map();
+        for (const e of events) {
+            const group = turnGroups.get(e.turn) ?? [];
+            group.push(e);
+            turnGroups.set(e.turn, group);
+        }
+        for (const [turn, turnEvents] of [...turnGroups.entries()].sort(([a], [b]) => a - b)) {
+            let turnSaved = 0;
+            const mechanismsThisTurn = {};
+            const tools = new Set();
+            for (const e of turnEvents) {
+                turnSaved += e.tokens_saved;
+                mechanismsThisTurn[e.mechanism] =
+                    (mechanismsThisTurn[e.mechanism] ?? 0) + e.tokens_saved;
+                cumulativeMechanisms[e.mechanism] =
+                    (cumulativeMechanisms[e.mechanism] ?? 0) + e.tokens_saved;
+                if (e.tool)
+                    tools.add(e.tool);
+            }
+            cumulativeSaved += turnSaved;
+            contextTurnsTotal += cumulativeSaved;
+            turnData.push({
+                turn,
+                tools: [...tools],
+                tokens_saved_this_turn: turnSaved,
+                cumulative_tokens_saved: cumulativeSaved,
+                context_avoided: cumulativeSaved,
+                mechanisms_this_turn: mechanismsThisTurn,
+                cumulative_by_mechanism: { ...cumulativeMechanisms },
+                event_count: turnEvents.length,
+            });
+        }
+        // Avg context reduction per turn: how much smaller context was on average
+        const numTurns = turnData.length;
+        const avgContextReduction = numTurns > 0 ? Math.round(contextTurnsTotal / numTurns) : 0;
+        return c.json({
+            data: turnData,
+            total_turns: numTurns,
+            total_saved: cumulativeSaved,
+            avg_context_reduction: avgContextReduction,
+            peak_context_reduction: cumulativeSaved, // max = final cumulative
+            total_context_avoided: contextTurnsTotal, // sum of cumulative savings at each turn
+            _meta: {
+                latency_ms: Math.round((performance.now() - start) * 100) / 100,
+            },
+        });
+    });
+    return app;
+}

package/dist/skills/effectiveness-tracker.js

@@ -0,0 +1,93 @@
+/**
+ * Skill Effectiveness Tracker — Phase 4.2
+ *
+ * Tracks skill activations and correlates them with outcomes:
+ * - Skill suggested by behavior → did the agent invoke related graph tools?
+ * - How many file reads were prevented (proxy for exploration loops avoided)?
+ *
+ * Surfaced in session summary: "blast-radius-first prevented 3 cascade failures"
+ */
+/**
+ * Session-scoped tracker for skill effectiveness.
+ */
+export class SkillEffectivenessTracker {
+    activations = [];
+    pendingSkillIds = new Set();
+    /**
+     * Record that a skill was suggested (by behavior or always-on injection).
+     */
+    recordActivation(skillId, triggeredBy, behaviorId) {
+        this.activations.push({
+            skillId,
+            triggeredBy,
+            behaviorId,
+            timestamp: Date.now(),
+            graphToolsCalled: [],
+            followed: false,
+        });
+        this.pendingSkillIds.add(skillId);
+    }
+    /**
+     * Record that a graph tool was called (correlates with pending skill activations).
+     * Call this from the proxy when any graph tool is invoked.
+     */
+    recordGraphToolCall(toolName) {
+        // Attribute to the most recent pending activation
+        for (let i = this.activations.length - 1; i >= 0; i--) {
+            const activation = this.activations[i];
+            if (this.pendingSkillIds.has(activation.skillId)) {
+                activation.graphToolsCalled.push(toolName);
+                activation.followed = true;
+                break;
+            }
+        }
+    }
+    /**
+     * Clear pending state (e.g., when a new tool call starts).
+     */
+    clearPending() {
+        this.pendingSkillIds.clear();
+    }
+    /**
+     * Get effectiveness stats for session summary.
+     */
+    getStats() {
+        const perSkillMap = new Map();
+        for (const a of this.activations) {
+            const existing = perSkillMap.get(a.skillId) ?? {
+                activations: 0,
+                graphToolsCalled: 0,
+                followed: 0,
+            };
+            existing.activations++;
+            existing.graphToolsCalled += a.graphToolsCalled.length;
+            if (a.followed)
+                existing.followed++;
+            perSkillMap.set(a.skillId, existing);
+        }
+        const perSkill = Array.from(perSkillMap.entries()).map(([skillId, stats]) => ({
+            skillId,
+            activations: stats.activations,
+            graphToolsCalled: stats.graphToolsCalled,
+            followRate: stats.activations > 0 ? stats.followed / stats.activations : 0,
+        }));
+        // Build summary line
+        const behaviorTriggered = this.activations.filter((a) => a.triggeredBy === "behavior");
+        const preventions = behaviorTriggered.filter((a) => a.followed).length;
+        const summaryLine = preventions > 0
+            ? `${preventions} skill-guided prevention(s) this session`
+            : "No skill-guided preventions this session";
+        return {
+            totalActivations: this.activations.length,
+            perSkill,
+            summaryLine,
+        };
+    }
+    /**
+     * Reset for new session.
+     */
+    reset() {
+        this.activations = [];
+        this.pendingSkillIds.clear();
+    }
+}