@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/__tests__/token-counter.test.js

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { createTokenCounter } from "../proxy/token-counter.js";
+describe("createTokenCounter", () => {
+    it("accumulates tokens saved", () => {
+        const counter = createTokenCounter({ emitEveryN: 100 });
+        counter.record(500, 1000);
+        counter.record(300, 800);
+        expect(counter.getTotalSaved()).toBe(800);
+        expect(counter.getTotalProcessed()).toBe(1800);
+        expect(counter.getCallCount()).toBe(2);
+    });
+    it("emits to sink every N calls", () => {
+        const messages = [];
+        const counter = createTokenCounter({
+            emitEveryN: 3,
+            sink: (msg) => messages.push(msg),
+        });
+        counter.record(100, 200);
+        counter.record(100, 200);
+        expect(messages).toHaveLength(0);
+        counter.record(100, 200);
+        expect(messages).toHaveLength(1);
+        expect(messages[0]).toContain("tokens saved");
+        expect(messages[0]).toContain("efficiency");
+    });
+    it("formats large token counts with K/M suffixes", () => {
+        const messages = [];
+        const counter = createTokenCounter({
+            emitEveryN: 1,
+            sink: (msg) => messages.push(msg),
+        });
+        counter.record(23_400, 50_000);
+        expect(messages[0]).toContain("23.4K");
+    });
+    it("calculates efficiency correctly", () => {
+        const counter = createTokenCounter({ emitEveryN: 100 });
+        counter.record(500, 1000);
+        expect(counter.getEfficiency()).toBe(50);
+    });
+    it("handles zero processed tokens", () => {
+        const counter = createTokenCounter({ emitEveryN: 100 });
+        expect(counter.getEfficiency()).toBe(0);
+    });
+    it("emits at exactly the Nth call", () => {
+        const messages = [];
+        const counter = createTokenCounter({
+            emitEveryN: 10,
+            sink: (msg) => messages.push(msg),
+        });
+        for (let i = 0; i < 9; i++) {
+            counter.record(10, 100);
+        }
+        expect(messages).toHaveLength(0);
+        counter.record(10, 100);
+        expect(messages).toHaveLength(1);
+    });
+    it("emits again at 2N calls", () => {
+        const messages = [];
+        const counter = createTokenCounter({
+            emitEveryN: 5,
+            sink: (msg) => messages.push(msg),
+        });
+        for (let i = 0; i < 10; i++) {
+            counter.record(10, 100);
+        }
+        expect(messages).toHaveLength(2);
+    });
+    it("reset clears all state", () => {
+        const counter = createTokenCounter({ emitEveryN: 100 });
+        counter.record(500, 1000);
+        counter.reset();
+        expect(counter.getTotalSaved()).toBe(0);
+        expect(counter.getTotalProcessed()).toBe(0);
+        expect(counter.getCallCount()).toBe(0);
+    });
+    it("defaults to emitEveryN=10", () => {
+        const messages = [];
+        const counter = createTokenCounter({
+            sink: (msg) => messages.push(msg),
+        });
+        for (let i = 0; i < 10; i++) {
+            counter.record(10, 100);
+        }
+        expect(messages).toHaveLength(1);
+    });
+});

package/dist/__tests__/token-estimator.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { estimateCost, estimateSavings, estimateTokenCount, estimateTokens, getModelCostRate, } from "../intelligence/token-estimator.js";
+describe("estimateTokenCount", () => {
+    it("returns 0 for empty string", () => {
+        expect(estimateTokenCount("")).toBe(0);
+    });
+    it("estimates English prose at ~chars/4", () => {
+        const text = "The quick brown fox jumps over the lazy dog. This is a sample of English prose that should be tokenized at approximately four characters per token.";
+        const tokens = estimateTokenCount(text);
+        const expectedApprox = Math.ceil(text.length / 4);
+        expect(tokens).toBeGreaterThan(expectedApprox * 0.7);
+        expect(tokens).toBeLessThan(expectedApprox * 1.4);
+    });
+    it("estimates code at ~chars/3.5", () => {
+        const code = `export function processOrder(orderId: string): Promise<OrderResult> {
+  const order = await db.findOrder(orderId);
+  if (!order) throw new Error("Order not found");
+  const items = await db.getOrderItems(orderId);
+  return { order, items, total: items.reduce((s, i) => s + i.price, 0) };
+}`;
+        const tokens = estimateTokenCount(code);
+        expect(tokens).toBeGreaterThan(code.length / 5);
+        expect(tokens).toBeLessThan(code.length / 2);
+    });
+    it("estimates JSON at ~chars/3", () => {
+        const json = JSON.stringify({
+            name: "test-project",
+            version: "1.0.0",
+            dependencies: { react: "^19.0.0", typescript: "^5.0.0" },
+            scripts: { build: "tsc", test: "vitest run" },
+        });
+        const tokens = estimateTokenCount(json);
+        const expectedApprox = Math.ceil(json.length / 3);
+        expect(tokens).toBeGreaterThan(expectedApprox * 0.6);
+        expect(tokens).toBeLessThan(expectedApprox * 1.5);
+    });
+    it("handles whitespace-heavy input", () => {
+        const text = "hello\n\n\n   \n\n   world   \n\n\n";
+        const tokens = estimateTokenCount(text);
+        expect(tokens).toBeGreaterThan(0);
+        expect(tokens).toBeLessThan(text.length);
+    });
+    it("estimates are consistent across multiple calls", () => {
+        const text = "function hello() { return 42; }";
+        const t1 = estimateTokenCount(text);
+        const t2 = estimateTokenCount(text);
+        expect(t1).toBe(t2);
+    });
+});
+describe("estimateTokens", () => {
+    it("handles null/undefined", () => {
+        expect(estimateTokens(null)).toBe(0);
+        expect(estimateTokens(undefined)).toBe(0);
+    });
+    it("handles objects by serializing", () => {
+        const obj = { key: "value" };
+        const tokens = estimateTokens(obj);
+        expect(tokens).toBeGreaterThan(0);
+    });
+});
+describe("estimateCost", () => {
+    it("calculates cost for Claude Sonnet", () => {
+        const cost = estimateCost("claude-sonnet-4-20250514", 1_000_000, 500_000);
+        expect(cost).toBe(3 + 7.5);
+    });
+    it("uses default rates for unknown models", () => {
+        const cost = estimateCost("unknown-model", 1_000_000, 1_000_000);
+        expect(cost).toBe(3 + 15);
+    });
+    it("returns 0 for Ollama", () => {
+        const cost = estimateCost("ollama", 1_000_000, 1_000_000);
+        expect(cost).toBe(0);
+    });
+});
+describe("estimateSavings", () => {
+    it("calculates dollar savings from token reduction", () => {
+        const savings = estimateSavings("claude-sonnet-4-20250514", 10000, 3000);
+        expect(savings).toBeGreaterThan(0);
+    });
+    it("returns 0 when no savings", () => {
+        const savings = estimateSavings("claude-sonnet-4-20250514", 1000, 1000);
+        expect(savings).toBe(0);
+    });
+});
+describe("getModelCostRate", () => {
+    it("returns known model rates", () => {
+        const rate = getModelCostRate("gpt-4o");
+        expect(rate.inputPerMillion).toBe(2.5);
+        expect(rate.outputPerMillion).toBe(10);
+    });
+    it("returns default rates for unknown models", () => {
+        const rate = getModelCostRate("imaginary-model");
+        expect(rate.inputPerMillion).toBe(3);
+        expect(rate.outputPerMillion).toBe(15);
+    });
+});

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

@@ -0,0 +1,239 @@
+import { mkdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { Hono } from "hono";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createTokenFlowRoutes } from "../server/routes/token-flow.js";
+import { appendSessionHistory } from "../tracking/session-history.js";
+import { TokenFlowWriter } from "../tracking/token-flow.js";
+describe("token-flow-api", () => {
+    let tmpDir;
+    let unerrDir;
+    let writer;
+    let app;
+    beforeEach(() => {
+        tmpDir = join(os.tmpdir(), `unerr-tfa-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        unerrDir = join(tmpDir, ".unerr");
+        mkdirSync(unerrDir, { recursive: true });
+        writer = new TokenFlowWriter(unerrDir, "api-test-session");
+        const routes = createTokenFlowRoutes({
+            unerrDir,
+            getTokenFlowWriter: () => writer,
+        });
+        app = new Hono();
+        app.route("/api/token-flow", routes);
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    // ── /api/token-flow/session ───────────────────────────────────────
+    describe("GET /api/token-flow/session", () => {
+        it("returns null data when no events recorded", async () => {
+            const emptyWriter = new TokenFlowWriter(unerrDir, "empty-session");
+            const routes = createTokenFlowRoutes({
+                unerrDir,
+                getTokenFlowWriter: () => emptyWriter,
+            });
+            const testApp = new Hono();
+            testApp.route("/api/token-flow", routes);
+            const res = await testApp.request("/api/token-flow/session");
+            const body = await res.json();
+            expect(res.status).toBe(200);
+            expect(body.data.total_tokens_saved).toBe(0);
+        });
+        it("returns session summary with mechanism breakdown", async () => {
+            writer.record({
+                session_id: "api-test-session",
+                turn: 1,
+                mechanism: "graph_query",
+                tool: "get_callers",
+                tokens_without: 5000,
+                tokens_with: 1800,
+                tokens_saved: 3200,
+            });
+            writer.record({
+                session_id: "api-test-session",
+                turn: 2,
+                mechanism: "shell_compression",
+                tool: null,
+                tokens_without: 2000,
+                tokens_with: 800,
+                tokens_saved: 1200,
+            });
+            const res = await app.request("/api/token-flow/session");
+            const body = await res.json();
+            expect(res.status).toBe(200);
+            expect(body.data.total_tokens_saved).toBe(4400);
+            expect(body.data.efficiency_pct).toBeGreaterThan(0);
+            expect(body.data.by_mechanism.graph_query).toBeDefined();
+            expect(body.data.by_mechanism.graph_query.tokens_saved).toBe(3200);
+            expect(body.data.event_count).toBe(2);
+            expect(body._meta.latency_ms).toBeDefined();
+        });
+        it("includes top_turns sorted by savings", async () => {
+            writer.record({
+                session_id: "api-test-session",
+                turn: 1,
+                mechanism: "graph_query",
+                tool: "search_code",
+                tokens_without: 1000,
+                tokens_with: 800,
+                tokens_saved: 200,
+            });
+            writer.record({
+                session_id: "api-test-session",
+                turn: 2,
+                mechanism: "graph_query",
+                tool: "get_callers",
+                tokens_without: 5000,
+                tokens_with: 1000,
+                tokens_saved: 4000,
+            });
+            const res = await app.request("/api/token-flow/session");
+            const body = await res.json();
+            expect(body.data.top_turns[0].turn).toBe(2);
+            expect(body.data.top_turns[0].tokens_saved).toBe(4000);
+        });
+    });
+    // ── /api/token-flow/history ───────────────────────────────────────
+    describe("GET /api/token-flow/history", () => {
+        it("returns empty array when no history", async () => {
+            const res = await app.request("/api/token-flow/history");
+            const body = await res.json();
+            expect(res.status).toBe(200);
+            expect(body.data).toEqual([]);
+        });
+        it("returns sessions with tokenFlowSummary", async () => {
+            appendSessionHistory(unerrDir, {
+                sessionId: "hist-1",
+                startedAt: "2026-01-01T00:00:00Z",
+                endedAt: "2026-01-01T00:10:00Z",
+                durationMs: 600_000,
+                toolCalls: 10,
+                tokensSaved: 5000,
+                tokensProcessed: 15000,
+                efficiency: 33,
+                dollarsSaved: 0.15,
+                modelId: "unknown",
+                entityCount: 0,
+                tokenFlowSummary: {
+                    by_mechanism: { graph_query: { tokens_saved: 4000, event_count: 5 } },
+                    top_mechanism: "graph_query",
+                    efficiency_pct: 33,
+                    total_tokens_saved: 5000,
+                    total_tokens_delivered: 10000,
+                },
+            });
+            const res = await app.request("/api/token-flow/history");
+            const body = await res.json();
+            expect(body.data).toHaveLength(1);
+            expect(body.data[0].token_flow.top_mechanism).toBe("graph_query");
+            expect(body.data[0].tokens_saved).toBe(5000);
+        });
+        it("respects limit parameter", async () => {
+            for (let i = 0; i < 5; i++) {
+                appendSessionHistory(unerrDir, {
+                    sessionId: `hist-${i}`,
+                    startedAt: new Date(Date.now() - i * 60_000).toISOString(),
+                    endedAt: new Date().toISOString(),
+                    durationMs: 60_000,
+                    toolCalls: 5,
+                    tokensSaved: 1000,
+                    tokensProcessed: 3000,
+                    efficiency: 33,
+                    dollarsSaved: 0,
+                    modelId: "unknown",
+                    entityCount: 0,
+                    tokenFlowSummary: {
+                        by_mechanism: {
+                            graph_query: { tokens_saved: 1000, event_count: 3 },
+                        },
+                        top_mechanism: "graph_query",
+                        efficiency_pct: 33,
+                        total_tokens_saved: 1000,
+                        total_tokens_delivered: 2000,
+                    },
+                });
+            }
+            const res = await app.request("/api/token-flow/history?limit=3");
+            const body = await res.json();
+            expect(body.data).toHaveLength(3);
+        });
+    });
+    // ── /api/token-flow/events ────────────────────────────────────────
+    describe("GET /api/token-flow/events", () => {
+        it("returns all session events", async () => {
+            writer.record({
+                session_id: "api-test-session",
+                turn: 1,
+                mechanism: "graph_query",
+                tool: "t",
+                tokens_without: 100,
+                tokens_with: 50,
+                tokens_saved: 50,
+            });
+            writer.record({
+                session_id: "api-test-session",
+                turn: 2,
+                mechanism: "graph_query",
+                tool: "t",
+                tokens_without: 200,
+                tokens_with: 100,
+                tokens_saved: 100,
+            });
+            const res = await app.request("/api/token-flow/events");
+            const body = await res.json();
+            expect(body.data).toHaveLength(2);
+            expect(body.total).toBe(2);
+        });
+        it("filters by turn number", async () => {
+            writer.record({
+                session_id: "api-test-session",
+                turn: 1,
+                mechanism: "graph_query",
+                tool: "a",
+                tokens_without: 100,
+                tokens_with: 50,
+                tokens_saved: 50,
+            });
+            writer.record({
+                session_id: "api-test-session",
+                turn: 2,
+                mechanism: "graph_query",
+                tool: "b",
+                tokens_without: 200,
+                tokens_with: 100,
+                tokens_saved: 100,
+            });
+            writer.record({
+                session_id: "api-test-session",
+                turn: 2,
+                mechanism: "format_encoding",
+                tool: "b",
+                tokens_without: 100,
+                tokens_with: 80,
+                tokens_saved: 20,
+            });
+            const res = await app.request("/api/token-flow/events?turn=2");
+            const body = await res.json();
+            expect(body.data).toHaveLength(2);
+            expect(body.data.every((e) => e.turn === 2)).toBe(true);
+        });
+    });
+    // ── Response structure validation ─────────────────────────────────
+    describe("response structure", () => {
+        it("all endpoints include _meta.latency_ms", async () => {
+            const endpoints = [
+                "/api/token-flow/session",
+                "/api/token-flow/history",
+                "/api/token-flow/events",
+            ];
+            for (const ep of endpoints) {
+                const res = await app.request(ep);
+                const body = await res.json();
+                expect(body._meta?.latency_ms).toBeDefined();
+                expect(typeof body._meta.latency_ms).toBe("number");
+            }
+        });
+    });
+});