clauderipple 0.9.5 → 0.10.0

package/dist/router/src/requestlog.js

@@ -2,11 +2,9 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import zlib from "node:zlib";
 import path from "node:path";
+import { UsageHistory, addTotals, emptyTotals, finishTotals, recordTotals, sortByVolume } from "./usage-history.js";
 const DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
 const MAX_CARRY = 64 * 1024;
-function emptyBucket() {
-    return { count: 0, ok: 0, failed: 0, input: 0, cached: 0, cacheWrite: 0, output: 0, cacheHitPercent: 0, avgMs: 0 };
-}
 function isRecord(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -21,13 +19,29 @@ export class RequestLog {
     max;
     maxBytes;
     records;
+    history;
     constructor(file, max = 2000, maxBytes = DEFAULT_MAX_BYTES) {
         this.file = file;
         this.max = max;
         this.maxBytes = maxBytes;
-        this.records = this.load();
+        const persisted = this.readRecords(this.file);
+        this.records = persisted.slice(-this.max);
+        this.history = new UsageHistory(path.join(path.dirname(file), "usage-hourly.jsonl"));
+        // Replay what the history has not seen yet: the `.1` file first when it may hold a record above
+        // the watermark, so the first run backfills both files. Its mtime is its last append, and a
+        // record starts before it is written, so an mtime at or below the watermark hour rules it out;
+        // the first record of requests.jsonl does not, since a long request that straddled the rotation
+        // starts earlier than records left in `.1`. The history skips everything at or below its
+        // watermark, so a restart counts no hour twice.
+        const watermark = this.history.watermark;
+        const rotatedHour = usageHourOfFile(`${file}.1`);
+        const replay = rotatedHour !== null && (watermark === null || rotatedHour > watermark)
+            ? [...this.readRecords(`${file}.1`), ...persisted]
+            : persisted;
+        this.history.replay(replay);
     }
     add(record) {
+        this.history.add(record);
         this.records.push(record);
         if (this.records.length > this.max)
             this.records.splice(0, this.records.length - this.max);
@@ -64,47 +78,34 @@ export class RequestLog {
     }
     /** Summarise records at or after an epoch timestamp in milliseconds. */
     summary(sinceMs) {
-        const total = emptyBucket();
-        const providers = {};
-        const cacheBases = new Map();
-        const add = (bucket, record) => {
-            bucket.count++;
-            if (record.ok)
-                bucket.ok++;
-            else if (!record.resent)
-                bucket.failed++;
-            bucket.avgMs += record.ms;
-            if (record.usage) {
-                bucket.input += record.usage.input;
-                bucket.cached += record.usage.cached;
-                bucket.cacheWrite += record.usage.cacheWrite ?? 0;
-                bucket.output += record.usage.output;
-                // A cache write is input the model read fresh, so it counts against the hit rate. Leaving it
-                // out read a turn that wrote 2,218 tokens and uncached 2 as a 100% hit (2026-09-23).
-                cacheBases.set(bucket, (cacheBases.get(bucket) ?? 0) + record.usage.input + record.usage.cached + (record.usage.cacheWrite ?? 0));
-            }
-        };
+        const total = emptyTotals();
+        const providers = new Map();
+        const models = new Map();
         for (const record of this.records) {
             const at = Date.parse(record.at);
             if (!Number.isFinite(at) || at < sinceMs)
                 continue;
-            const provider = providers[record.provider] ?? (providers[record.provider] = emptyBucket());
-            add(total, record);
-            add(provider, record);
+            const provider = providers.get(record.provider) ?? providers.set(record.provider, emptyTotals()).get(record.provider);
+            const key = `${record.provider}\u0000${record.target}`;
+            const model = models.get(key) ?? models.set(key, { totals: emptyTotals(), provider: record.provider, model: record.target }).get(key);
+            for (const bucket of [total, provider, model.totals])
+                addTotals(bucket, recordTotals(record));
         }
-        for (const bucket of [total, ...Object.values(providers)]) {
-            if (bucket.count > 0)
-                bucket.avgMs = Math.round(bucket.avgMs / bucket.count);
-            const base = cacheBases.get(bucket) ?? 0;
-            bucket.cacheHitPercent = base > 0 ? Math.round((bucket.cached / base) * 1000) / 10 : 0;
-        }
-        return { total, providers };
+        const modelsList = [...models.values()].map(({ totals, provider, model }) => ({ ...finishTotals(totals), provider, model }));
+        sortByVolume(modelsList);
+        return {
+            total: finishTotals(total),
+            providers: Object.fromEntries([...providers].map(([name, totals]) => [name, finishTotals(totals)])),
+            models: modelsList,
+        };
+    }
+    /** Durable hourly usage over [fromMs, toMs), beyond the in-memory ring. */
+    usage(fromMs, toMs) {
+        return this.history.summary(fromMs, toMs);
     }
-    load() {
+    readRecords(file) {
         try {
-            if (!fs.existsSync(this.file))
-                return [];
-            const records = fs.readFileSync(this.file, "utf8")
+            return fs.readFileSync(file, "utf8")
                 .split("\n")
                 .flatMap((line) => {
                 try {
@@ -115,13 +116,21 @@ export class RequestLog {
                     return [];
                 }
             });
-            return records.slice(-this.max);
         }
         catch {
             return [];
         }
     }
 }
+/** The hour of a file's last write, or null when it does not exist. */
+function usageHourOfFile(file) {
+    try {
+        return Math.floor(fs.statSync(file).mtimeMs / 3_600_000);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Observes an Anthropic-compatible response without retaining or modifying its bytes.
  * Call feed() after forwarding each response chunk, then finish() on response end.

package/dist/router/src/usage-history.js

@@ -0,0 +1,227 @@
+import fs from "node:fs";
+import path from "node:path";
+const HOUR_MS = 3_600_000;
+export function emptyTotals() {
+    return { count: 0, ok: 0, failed: 0, input: 0, cached: 0, cacheWrite: 0, output: 0, ms: 0 };
+}
+/** The same counting rules as `RequestLog.summary`, for one record. */
+export function recordTotals(record) {
+    const totals = emptyTotals();
+    totals.count = 1;
+    if (record.ok)
+        totals.ok = 1;
+    else if (!record.resent)
+        totals.failed = 1;
+    totals.ms = record.ms;
+    if (record.usage) {
+        totals.input = record.usage.input;
+        totals.cached = record.usage.cached;
+        totals.cacheWrite = record.usage.cacheWrite ?? 0;
+        totals.output = record.usage.output;
+    }
+    return totals;
+}
+export function addTotals(target, source) {
+    target.count += source.count;
+    target.ok += source.ok;
+    target.failed += source.failed;
+    target.input += source.input;
+    target.cached += source.cached;
+    target.cacheWrite += source.cacheWrite;
+    target.output += source.output;
+    target.ms += source.ms;
+}
+/** Derives the rate columns from summed totals. A cache write is input the model read fresh, so it
+ * counts against the hit rate (leaving it out read a turn that wrote 2,218 tokens and uncached 2 as
+ * a 100% hit, 2026-09-23). */
+export function finishTotals(totals) {
+    const base = totals.input + totals.cached + totals.cacheWrite;
+    return {
+        count: totals.count,
+        ok: totals.ok,
+        failed: totals.failed,
+        input: totals.input,
+        cached: totals.cached,
+        cacheWrite: totals.cacheWrite,
+        output: totals.output,
+        cacheHitPercent: base > 0 ? Math.round((totals.cached / base) * 1000) / 10 : 0,
+        avgMs: totals.count > 0 ? Math.round(totals.ms / totals.count) : 0,
+    };
+}
+function bucketKey(h, provider, model) {
+    return `${h}\u0000${provider}\u0000${model}`;
+}
+function modelKey(provider, model) {
+    return `${provider}\u0000${model}`;
+}
+/** Models with the most tokens read first (input + cached + cacheWrite), then the busiest. */
+export function sortByVolume(models) {
+    const volume = (bucket) => bucket.input + bucket.cached + bucket.cacheWrite;
+    models.sort((a, b) => volume(b) - volume(a) || b.count - a.count);
+}
+function isHourBucket(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const b = value;
+    return typeof b.h === "number" && Number.isFinite(b.h) && Number.isInteger(b.h) &&
+        typeof b.p === "string" && typeof b.m === "string" &&
+        ["count", "ok", "failed", "input", "cached", "cacheWrite", "output", "ms"].every((key) => {
+            const n = b[key];
+            return typeof n === "number" && Number.isFinite(n);
+        });
+}
+function toLine(bucket) {
+    return JSON.stringify({
+        h: bucket.h,
+        p: bucket.p,
+        m: bucket.m,
+        count: bucket.count,
+        ok: bucket.ok,
+        failed: bucket.failed,
+        input: bucket.input,
+        cached: bucket.cached,
+        cacheWrite: bucket.cacheWrite,
+        output: bucket.output,
+        ms: bucket.ms,
+    }) + "\n";
+}
+/**
+ * Durable hourly usage history, appended to `usage-hourly.jsonl` next to `requests.jsonl`.
+ *
+ * Invariant: every hour below the open hour is fully on disk (possibly as several additive lines
+ * for the same (h,p,m)); only the open hour lives in memory. A late record (its hour is below the
+ * open hour because a request started earlier and finished later) is appended immediately as its
+ * own line. On startup the file's highest hour is the watermark, and request records above it are
+ * replayed, so an hour never counted twice yet the open hour survives a restart.
+ */
+export class UsageHistory {
+    file;
+    buckets = new Map();
+    open = new Map();
+    openHour = null;
+    highestHour = null;
+    earliestHour = null;
+    constructor(file) {
+        this.file = file;
+        this.load();
+    }
+    /** Highest hour already on disk, or null when nothing was persisted yet. */
+    get watermark() {
+        return this.highestHour;
+    }
+    /** Feeds startup replay: records at or below the watermark are already on disk. */
+    replay(records) {
+        const floor = this.highestHour;
+        for (const record of records) {
+            const hour = hourOf(record);
+            if (hour === null)
+                continue;
+            if (floor !== null && hour <= floor)
+                continue;
+            this.add(record);
+        }
+    }
+    add(record) {
+        const hour = hourOf(record);
+        if (hour === null)
+            return;
+        this.observe(hour);
+        const bucket = { h: hour, p: record.provider, m: record.target, ...recordTotals(record) };
+        if (this.openHour !== null && hour < this.openHour) {
+            this.append([bucket]);
+            this.merge(this.buckets, bucket);
+            return;
+        }
+        if (this.openHour === null || hour > this.openHour) {
+            this.flush();
+            this.openHour = hour;
+        }
+        this.merge(this.open, bucket);
+    }
+    /** Buckets whose hour start lies in [fromMs, toMs), summed across providers and models. */
+    summary(fromMs, toMs) {
+        const fromHour = Math.floor(fromMs / HOUR_MS);
+        const total = emptyTotals();
+        const providers = new Map();
+        const models = new Map();
+        for (const bucket of [...this.buckets.values(), ...this.open.values()]) {
+            if (bucket.h < fromHour || bucket.h * HOUR_MS >= toMs)
+                continue;
+            addTotals(total, bucket);
+            const provider = providers.get(bucket.p) ?? providers.set(bucket.p, emptyTotals()).get(bucket.p);
+            addTotals(provider, bucket);
+            const key = modelKey(bucket.p, bucket.m);
+            const model = models.get(key) ?? (models.set(key, { totals: emptyTotals(), provider: bucket.p, model: bucket.m }).get(key));
+            addTotals(model.totals, bucket);
+        }
+        const modelList = [...models.values()].map(({ totals, provider, model }) => ({ ...finishTotals(totals), provider, model }));
+        sortByVolume(modelList);
+        return {
+            total: finishTotals(total),
+            providers: Object.fromEntries([...providers].map(([name, totals]) => [name, finishTotals(totals)])),
+            models: modelList,
+            earliest: this.earliestHour === null ? null : new Date(this.earliestHour * HOUR_MS).toISOString(),
+        };
+    }
+    observe(hour) {
+        if (this.earliestHour === null || hour < this.earliestHour)
+            this.earliestHour = hour;
+    }
+    merge(target, bucket) {
+        const key = bucketKey(bucket.h, bucket.p, bucket.m);
+        const existing = target.get(key);
+        if (existing)
+            addTotals(existing, bucket);
+        else
+            target.set(key, { ...bucket });
+        if (target === this.buckets && (this.highestHour === null || bucket.h > this.highestHour))
+            this.highestHour = bucket.h;
+    }
+    flush() {
+        if (this.open.size === 0)
+            return;
+        const lines = [...this.open.values()];
+        this.open.clear();
+        this.append(lines);
+        for (const line of lines)
+            this.merge(this.buckets, line);
+    }
+    append(lines) {
+        if (lines.length === 0)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.file), { recursive: true });
+            fs.appendFileSync(this.file, lines.map(toLine).join(""), "utf8");
+        }
+        catch {
+            // Usage history is best-effort: it must never alter the proxy response path.
+        }
+    }
+    load() {
+        let text;
+        try {
+            text = fs.readFileSync(this.file, "utf8");
+        }
+        catch {
+            return;
+        }
+        for (const line of text.split("\n")) {
+            if (line === "")
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (isHourBucket(parsed)) {
+                    this.observe(parsed.h);
+                    this.merge(this.buckets, parsed);
+                }
+            }
+            catch {
+                // A torn write stays behind; the neighbouring lines still count.
+            }
+        }
+    }
+}
+function hourOf(record) {
+    const at = Date.parse(record.at);
+    return Number.isFinite(at) ? Math.floor(at / HOUR_MS) : null;
+}

package/dist/router/src/version.js

@@ -5,4 +5,4 @@
 // from the manifests. Until 0.1.1 the router and the CLI each carried their own literal, and both
 // still said "0.1.0" in the 0.1.1 release: after an update nobody could tell which router was
 // running, and the tray app had nothing to compare (2026-09-15, reported from a Windows install).
-export const VERSION = "0.9.5";
+export const VERSION = "0.10.0";