clauderipple 0.9.4 → 0.10.0

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.4";
+export const VERSION = "0.10.0";