@unerr-ai/unerr 0.0.1 → 0.1.1

package/dist/__tests__/token-flow-persistence.test.js

@@ -0,0 +1,356 @@
+import { mkdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { appendSessionHistory, readSessionHistory, } from "../tracking/session-history.js";
+import { formatSessionReceipt, } from "../tracking/session-receipt.js";
+import { TokenFlowWriter, aggregateSession, } from "../tracking/token-flow.js";
+describe("token-flow-persistence", () => {
+    let tmpDir;
+    let unerrDir;
+    beforeEach(() => {
+        tmpDir = join(os.tmpdir(), `unerr-tfp-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        unerrDir = join(tmpDir, ".unerr");
+        mkdirSync(unerrDir, { recursive: true });
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    // ── TF-C.1 + TF-C.2: Session history persistence ─────────────────
+    describe("session history with tokenFlowSummary", () => {
+        it("persists tokenFlowSummary in session history entries", () => {
+            const entry = {
+                sessionId: "test-sess-001",
+                startedAt: "2026-01-01T00:00:00Z",
+                endedAt: "2026-01-01T00:23:00Z",
+                durationMs: 23 * 60_000,
+                toolCalls: 15,
+                tokensSaved: 51600,
+                tokensProcessed: 80200,
+                efficiency: 64,
+                dollarsSaved: 1.55,
+                modelId: "unknown",
+                entityCount: 0,
+                tokenFlowSummary: {
+                    by_mechanism: {
+                        graph_query: { tokens_saved: 38400, event_count: 8 },
+                        shell_compression: { tokens_saved: 4200, event_count: 3 },
+                        format_encoding: { tokens_saved: 1600, event_count: 5 },
+                    },
+                    top_mechanism: "graph_query",
+                    efficiency_pct: 64,
+                    total_tokens_saved: 51600,
+                    total_tokens_delivered: 28800,
+                },
+            };
+            appendSessionHistory(unerrDir, entry);
+            const entries = readSessionHistory(unerrDir);
+            expect(entries).toHaveLength(1);
+            expect(entries[0].tokenFlowSummary).toBeDefined();
+            expect(entries[0].tokenFlowSummary.top_mechanism).toBe("graph_query");
+            expect(entries[0].tokenFlowSummary.by_mechanism.graph_query.tokens_saved).toBe(38400);
+            expect(entries[0].tokenFlowSummary.total_tokens_saved).toBe(51600);
+        });
+        it("reads entries without tokenFlowSummary (backward compatibility)", () => {
+            const entry = {
+                sessionId: "old-session",
+                startedAt: "2026-01-01T00:00:00Z",
+                endedAt: "2026-01-01T00:10:00Z",
+                durationMs: 600_000,
+                toolCalls: 5,
+                tokensSaved: 10000,
+                tokensProcessed: 20000,
+                efficiency: 50,
+                dollarsSaved: 0.3,
+                modelId: "unknown",
+                entityCount: 0,
+            };
+            appendSessionHistory(unerrDir, entry);
+            const entries = readSessionHistory(unerrDir);
+            expect(entries).toHaveLength(1);
+            expect(entries[0].tokenFlowSummary).toBeUndefined();
+        });
+        it("aggregates multiple sessions with tokenFlowSummary", () => {
+            for (let i = 0; i < 3; i++) {
+                appendSessionHistory(unerrDir, {
+                    sessionId: `session-${i}`,
+                    startedAt: new Date().toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: 60_000,
+                    toolCalls: 5,
+                    tokensSaved: 1000 * (i + 1),
+                    tokensProcessed: 5000,
+                    efficiency: 20 * (i + 1),
+                    dollarsSaved: 0.1 * (i + 1),
+                    modelId: "unknown",
+                    entityCount: 0,
+                    tokenFlowSummary: {
+                        by_mechanism: {
+                            graph_query: { tokens_saved: 800 * (i + 1), event_count: 3 },
+                            shell_compression: {
+                                tokens_saved: 200 * (i + 1),
+                                event_count: 1,
+                            },
+                        },
+                        top_mechanism: "graph_query",
+                        efficiency_pct: 20 * (i + 1),
+                        total_tokens_saved: 1000 * (i + 1),
+                        total_tokens_delivered: 4000,
+                    },
+                });
+            }
+            const entries = readSessionHistory(unerrDir);
+            expect(entries).toHaveLength(3);
+            const totalGraphSaved = entries.reduce((s, e) => s + (e.tokenFlowSummary?.by_mechanism.graph_query?.tokens_saved ?? 0), 0);
+            expect(totalGraphSaved).toBe(800 + 1600 + 2400);
+        });
+    });
+    // ── TF-C.4: Session receipt formatting ────────────────────────────
+    describe("session receipt", () => {
+        function makeSummary() {
+            const writer = new TokenFlowWriter(unerrDir, "receipt-test");
+            writer.record({
+                session_id: "receipt-test",
+                turn: 1,
+                mechanism: "graph_query",
+                tool: "get_callers",
+                tokens_without: 5000,
+                tokens_with: 1800,
+                tokens_saved: 3200,
+            });
+            writer.record({
+                session_id: "receipt-test",
+                turn: 2,
+                mechanism: "shell_compression",
+                tool: null,
+                tokens_without: 2000,
+                tokens_with: 800,
+                tokens_saved: 1200,
+            });
+            writer.record({
+                session_id: "receipt-test",
+                turn: 3,
+                mechanism: "format_encoding",
+                tool: "get_callers",
+                tokens_without: 1800,
+                tokens_with: 1480,
+                tokens_saved: 320,
+            });
+            return aggregateSession(writer.getSessionEvents(), "receipt-test");
+        }
+        it("produces formatted receipt with all sections", () => {
+            const summary = makeSummary();
+            const receipt = formatSessionReceipt({
+                summary,
+                durationMs: 23 * 60_000,
+                toolCalls: 15,
+                weeklyTokensSaved: 312_000,
+                weeklySessions: 7,
+            });
+            expect(receipt).toContain("unerr");
+            expect(receipt).toContain("session receipt");
+            expect(receipt).toContain("23 minutes");
+            expect(receipt).toContain("15");
+            expect(receipt).toContain("graph_query");
+            expect(receipt).toContain("shell_compression");
+            expect(receipt).toContain("312.0K");
+        });
+        it("receipt includes efficiency percentage", () => {
+            const summary = makeSummary();
+            const receipt = formatSessionReceipt({
+                summary,
+                durationMs: 60_000,
+                toolCalls: 3,
+            });
+            expect(receipt).toContain(`${summary.efficiency_pct}%`);
+        });
+        it("receipt includes most efficient turn", () => {
+            const summary = makeSummary();
+            const receipt = formatSessionReceipt({
+                summary,
+                durationMs: 60_000,
+                toolCalls: 3,
+            });
+            expect(receipt).toContain("get_callers");
+        });
+        it("receipt handles empty session gracefully", () => {
+            const emptySummary = {
+                session_id: "empty",
+                total_turns: 0,
+                total_tokens_without: 0,
+                total_tokens_with: 0,
+                total_tokens_saved: 0,
+                efficiency_pct: 0,
+                by_mechanism: {},
+                top_turns: [],
+            };
+            const receipt = formatSessionReceipt({
+                summary: emptySummary,
+                durationMs: 0,
+                toolCalls: 0,
+            });
+            expect(receipt).toContain("0%");
+        });
+        it("receipt includes box-drawing characters", () => {
+            const summary = makeSummary();
+            const receipt = formatSessionReceipt({
+                summary,
+                durationMs: 60_000,
+                toolCalls: 3,
+            });
+            expect(receipt).toContain("┌");
+            expect(receipt).toContain("└");
+            expect(receipt).toContain("│");
+        });
+    });
+    // ── TF-C.3: WeeklyStats tokensByMechanism ────────────────────────
+    describe("weekly stats mechanism breakdown", () => {
+        it("formatStatsReport includes mechanism breakdown when present", async () => {
+            const { formatStatsReport } = await import("../tracking/weekly-accumulator.js");
+            const stats = {
+                version: 1,
+                weekly: {
+                    weekStart: "2026-01-06",
+                    sessions: 5,
+                    tokensSaved: 100_000,
+                    dollarsSaved: 3.0,
+                    toolCalls: 75,
+                    violationsCaught: 2,
+                    chokepointWarnings: 1,
+                    correctionsApplied: 0,
+                    blastRadiusComputed: 3,
+                    avgEfficiency: 65,
+                    avgLatencyP50: 2.1,
+                    tokensByMechanism: {
+                        graph_query: 74000,
+                        shell_compression: 12000,
+                        format_encoding: 8000,
+                        smart_truncation: 6000,
+                    },
+                },
+                allTime: {
+                    firstSessionDate: "2026-01-01T00:00:00Z",
+                    totalSessions: 20,
+                    totalTokensSaved: 500_000,
+                    totalDollarsSaved: 15.0,
+                    totalViolationsCaught: 10,
+                },
+                lastUpdated: new Date().toISOString(),
+            };
+            const report = formatStatsReport(stats);
+            expect(report).toContain("By mechanism:");
+            expect(report).toContain("graph_query");
+            expect(report).toContain("shell_compression");
+            expect(report).toContain("format_encoding");
+            expect(report).toContain("█");
+        });
+        it("formatStatsReport omits mechanism section when empty", async () => {
+            const { formatStatsReport } = await import("../tracking/weekly-accumulator.js");
+            const stats = {
+                version: 1,
+                weekly: {
+                    weekStart: "2026-01-06",
+                    sessions: 1,
+                    tokensSaved: 1000,
+                    dollarsSaved: 0.03,
+                    toolCalls: 5,
+                    violationsCaught: 0,
+                    chokepointWarnings: 0,
+                    correctionsApplied: 0,
+                    blastRadiusComputed: 0,
+                    avgEfficiency: 50,
+                    avgLatencyP50: 1.5,
+                },
+                allTime: {
+                    firstSessionDate: "2026-01-01T00:00:00Z",
+                    totalSessions: 1,
+                    totalTokensSaved: 1000,
+                    totalDollarsSaved: 0.03,
+                    totalViolationsCaught: 0,
+                },
+                lastUpdated: new Date().toISOString(),
+            };
+            const report = formatStatsReport(stats);
+            expect(report).not.toContain("By mechanism:");
+        });
+    });
+    // ── End-to-End: Token Flow → Summary → Receipt ───────────────────
+    describe("end-to-end flow", () => {
+        it("events → aggregation → session history → receipt", () => {
+            const writer = new TokenFlowWriter(unerrDir, "e2e-session");
+            writer.record({
+                session_id: "e2e-session",
+                turn: 1,
+                mechanism: "graph_query",
+                tool: "search_code",
+                tokens_without: 5000,
+                tokens_with: 1800,
+                tokens_saved: 3200,
+            });
+            writer.record({
+                session_id: "e2e-session",
+                turn: 2,
+                mechanism: "graph_query",
+                tool: "get_entity",
+                tokens_without: 3000,
+                tokens_with: 2400,
+                tokens_saved: 600,
+            });
+            writer.record({
+                session_id: "e2e-session",
+                turn: 3,
+                mechanism: "graph_query",
+                tool: "get_callers",
+                tokens_without: 6800,
+                tokens_with: 2000,
+                tokens_saved: 4800,
+            });
+            writer.record({
+                session_id: "e2e-session",
+                turn: 4,
+                mechanism: "shell_compression",
+                tool: null,
+                tokens_without: 2000,
+                tokens_with: 800,
+                tokens_saved: 1200,
+            });
+            const summary = aggregateSession(writer.getSessionEvents(), "e2e-session");
+            expect(summary.total_tokens_saved).toBe(9800);
+            expect(summary.by_mechanism.graph_query.tokens_saved).toBe(8600);
+            const topMech = Object.entries(summary.by_mechanism).sort(([, a], [, b]) => b.tokens_saved - a.tokens_saved)[0];
+            appendSessionHistory(unerrDir, {
+                sessionId: "e2e-session",
+                startedAt: new Date().toISOString(),
+                endedAt: new Date().toISOString(),
+                durationMs: 300_000,
+                toolCalls: 4,
+                tokensSaved: summary.total_tokens_saved,
+                tokensProcessed: summary.total_tokens_without,
+                efficiency: summary.efficiency_pct,
+                dollarsSaved: 0,
+                modelId: "unknown",
+                entityCount: 0,
+                tokenFlowSummary: {
+                    by_mechanism: Object.fromEntries(Object.entries(summary.by_mechanism).map(([k, v]) => [
+                        k,
+                        { tokens_saved: v.tokens_saved, event_count: v.event_count },
+                    ])),
+                    top_mechanism: topMech?.[0] ?? "none",
+                    efficiency_pct: summary.efficiency_pct,
+                    total_tokens_saved: summary.total_tokens_saved,
+                    total_tokens_delivered: summary.total_tokens_with,
+                },
+            });
+            const history = readSessionHistory(unerrDir);
+            expect(history).toHaveLength(1);
+            expect(history[0].tokenFlowSummary.top_mechanism).toBe("graph_query");
+            const receipt = formatSessionReceipt({
+                summary,
+                durationMs: 300_000,
+                toolCalls: 4,
+            });
+            expect(receipt).toContain("graph_query");
+            expect(receipt).toContain("shell_compression");
+        });
+    });
+});

package/dist/__tests__/token-flow-routes.test.js

@@ -0,0 +1,199 @@
+/**
+ * Integration tests for token-flow API routes.
+ * Tests all 6 endpoints against real data in `.unerr/metrics.db`
+ * (token_flow_events table).
+ */
+import { join } from "node:path";
+import { beforeAll, describe, expect, it } from "vitest";
+import { createTokenFlowRoutes } from "../server/routes/token-flow.js";
+import { readTokenFlowEvents } from "../tracking/token-flow.js";
+const unerrDir = join(process.cwd(), ".unerr");
+// Count raw events for validation — driven by the same reader the routes use.
+// The routes strip "persistent_memory" events before aggregating (see
+// stripPersistentMemory in src/server/routes/token-flow.ts), so we match that
+// filter here to keep totals comparable.
+function countRawEvents() {
+    const events = readTokenFlowEvents(unerrDir).filter((e) => e.mechanism !== "persistent_memory");
+    const sessions = new Set();
+    let saved = 0;
+    let without = 0;
+    let with_ = 0;
+    for (const e of events) {
+        sessions.add(e.session_id);
+        saved += e.tokens_saved;
+        without += e.tokens_without;
+        with_ += e.tokens_with;
+    }
+    return { total: events.length, sessions, saved, without, with_ };
+}
+const hasData = countRawEvents().total > 0;
+async function fetchRoute(app, path) {
+    const res = await app.fetch(new Request(`http://localhost${path}`));
+    return {
+        status: res.status,
+        json: (await res.json()),
+    };
+}
+describe.skipIf(!hasData)("token-flow API routes", () => {
+    let app;
+    let raw;
+    beforeAll(() => {
+        app = createTokenFlowRoutes({ unerrDir, getTokenFlowWriter: () => null });
+        raw = countRawEvents();
+    });
+    describe("GET /global", () => {
+        it("returns aggregate KPIs across all sessions", async () => {
+            const { status, json } = await fetchRoute(app, "/global");
+            expect(status).toBe(200);
+            const d = json.data;
+            expect(d.total_sessions).toBe(raw.sessions.size);
+            expect(d.event_count).toBe(raw.total);
+            expect(d.total_tokens_saved).toBe(raw.saved);
+            expect(d.total_tokens_without).toBe(raw.without);
+            expect(d.total_tokens_with).toBe(raw.with_);
+            expect(d.efficiency_pct).toBe(Math.round((raw.saved / raw.without) * 100));
+        });
+        it("mechanism percentages sum to ~100", async () => {
+            const { json } = await fetchRoute(app, "/global");
+            const mechs = json.data
+                .by_mechanism;
+            const pctSum = Object.values(mechs).reduce((s, m) => s + m.pct_of_total, 0);
+            expect(pctSum).toBeGreaterThanOrEqual(98);
+            expect(pctSum).toBeLessThanOrEqual(102);
+        });
+        it("mechanism event counts sum to total", async () => {
+            const { json } = await fetchRoute(app, "/global");
+            const mechs = json.data
+                .by_mechanism;
+            const evtSum = Object.values(mechs).reduce((s, m) => s + m.event_count, 0);
+            expect(evtSum).toBe(raw.total);
+        });
+    });
+    describe("GET /sessions", () => {
+        it("lists all unique sessions sorted by recency", async () => {
+            const { status, json } = await fetchRoute(app, "/sessions");
+            expect(status).toBe(200);
+            const sessions = json.data;
+            expect(sessions.length).toBe(raw.sessions.size);
+            // Event counts sum to total
+            const evtSum = sessions.reduce((s, x) => s + x.event_count, 0);
+            expect(evtSum).toBe(raw.total);
+            // Saved sums match
+            const savedSum = sessions.reduce((s, x) => s + x.total_saved, 0);
+            expect(savedSum).toBe(raw.saved);
+            // Sorted descending by last_ts
+            for (let i = 1; i < sessions.length; i++) {
+                expect(sessions[i].last_ts <= sessions[i - 1].last_ts).toBe(true);
+            }
+            // Each session has mechanisms
+            for (const s of sessions) {
+                expect(s.mechanisms.length).toBeGreaterThan(0);
+            }
+        });
+    });
+    describe("GET /session", () => {
+        it("returns current session summary when no session_id param", async () => {
+            const { status, json } = await fetchRoute(app, "/session");
+            expect(status).toBe(200);
+            // With no writer, it picks the most recent session from disk
+            const d = json.data;
+            // Could be null if aggregation yields 0 (unlikely with real data)
+            if (d) {
+                expect(d.session_id).toBeDefined();
+                expect(typeof d.total_tokens_saved).toBe("number");
+                expect(typeof d.efficiency_pct).toBe("number");
+                expect(d.by_mechanism).toBeDefined();
+            }
+        });
+        it("returns specific session when session_id param provided", async () => {
+            // Get first session ID from /sessions
+            const { json: sessionsJson } = await fetchRoute(app, "/sessions");
+            const sessions = sessionsJson.data;
+            const targetId = sessions[sessions.length - 1].session_id; // oldest session
+            const expectedEvents = sessions[sessions.length - 1].event_count;
+            const { status, json } = await fetchRoute(app, `/session?session_id=${targetId}`);
+            expect(status).toBe(200);
+            const d = json.data;
+            expect(d).not.toBeNull();
+            expect(d.session_id).toBe(targetId);
+            expect(d.event_count).toBe(expectedEvents);
+            expect(typeof d.total_tokens_saved).toBe("number");
+            expect(d.total_tokens_saved).toBeGreaterThan(0);
+        });
+    });
+    describe("GET /cumulative", () => {
+        it("returns monotonically increasing cumulative data", async () => {
+            const { json: sessionsJson } = await fetchRoute(app, "/sessions");
+            const sessions = sessionsJson.data;
+            const targetId = sessions[0].session_id;
+            const { status, json } = await fetchRoute(app, `/cumulative?session_id=${targetId}`);
+            expect(status).toBe(200);
+            const turns = json.data;
+            expect(turns.length).toBeGreaterThan(0);
+            // Monotonically non-decreasing
+            for (let i = 1; i < turns.length; i++) {
+                expect(turns[i].cumulative_tokens_saved).toBeGreaterThanOrEqual(turns[i - 1].cumulative_tokens_saved);
+            }
+            // Last cumulative equals total_saved
+            expect(turns[turns.length - 1].cumulative_tokens_saved).toBe(json.total_saved);
+            // Each turn has events and tools array
+            for (const t of turns) {
+                expect(t.event_count).toBeGreaterThan(0);
+                expect(Array.isArray(t.tools)).toBe(true);
+                expect(typeof t.tokens_saved_this_turn).toBe("number");
+                expect(typeof t.mechanisms_this_turn).toBe("object");
+                expect(typeof t.cumulative_by_mechanism).toBe("object");
+            }
+        });
+    });
+    describe("GET /events", () => {
+        it("filters by session_id and turn", async () => {
+            const { json: sessionsJson } = await fetchRoute(app, "/sessions");
+            const sessions = sessionsJson.data;
+            const targetId = sessions[0].session_id;
+            const { status, json } = await fetchRoute(app, `/events?session_id=${targetId}&turn=0`);
+            expect(status).toBe(200);
+            const evts = json.data;
+            expect(evts.length).toBeGreaterThan(0);
+            for (const e of evts) {
+                expect(e.session_id).toBe(targetId);
+                expect(e.turn).toBe(0);
+                expect(typeof e.tokens_saved).toBe("number");
+                expect(typeof e.tokens_without).toBe("number");
+                expect(typeof e.tokens_with).toBe("number");
+                expect(typeof e.mechanism).toBe("string");
+                expect(typeof e.ts).toBe("string");
+            }
+        });
+        it("filters by mechanism", async () => {
+            const { status, json } = await fetchRoute(app, "/events?mechanism=graph_query");
+            expect(status).toBe(200);
+            const evts = json.data;
+            for (const e of evts) {
+                expect(e.mechanism).toBe("graph_query");
+            }
+        });
+    });
+    describe("cross-endpoint consistency", () => {
+        it("global totals match sum of all session totals", async () => {
+            const { json: globalJson } = await fetchRoute(app, "/global");
+            const g = globalJson.data;
+            const { json: sessionsJson } = await fetchRoute(app, "/sessions");
+            const sessions = sessionsJson.data;
+            const sessionSavedSum = sessions.reduce((s, x) => s + x.total_saved, 0);
+            expect(sessionSavedSum).toBe(g.total_tokens_saved);
+        });
+        it("session detail matches session list entry", async () => {
+            const { json: sessionsJson } = await fetchRoute(app, "/sessions");
+            const sessions = sessionsJson.data;
+            for (const s of sessions) {
+                const { json } = await fetchRoute(app, `/session?session_id=${s.session_id}`);
+                const d = json.data;
+                if (d) {
+                    expect(d.event_count).toBe(s.event_count);
+                    expect(d.total_tokens_saved).toBe(s.total_saved);
+                }
+            }
+        });
+    });
+});