dsh-plugin-usage 0.1.4 → 0.2.0

package/lib/host/aggregate.js

@@ -0,0 +1,98 @@
+/**
+ * Incremental aggregation index over state.records.
+ *
+ * P1-5 LOCKED CONTRACT — query.js consumes exactly these members and fold.js
+ * feeds them; do not change the signatures:
+ *   add(record)              — fold calls for every record inserted
+ *   remove(record)           — fold calls when a dedup replacement drops a record
+ *   recordsInRange(from, to) — iterable of records with from <= time <= to
+ *
+ * Implementation: a Map<dayOrdinal, records[]> slice index maintained
+ * incrementally by add()/remove(). Records are folded chronologically, so each
+ * day array preserves insertion order and iterating day ordinals in ascending
+ * order reproduces the baseline scan's order while skipping out-of-range days.
+ * recordsInRange() additionally sweeps state.records for entries missing from
+ * the map (bookkeeping gaps, e.g. records pushed before the index existed) so
+ * query results stay identical to the baseline O(N) scan even on partial
+ * indexes — each such record is guarded by a per-call Set against duplicates.
+ */
+import { DAY_MS, alignFloor } from './time.js';
+const dayOrdinal = (t) => Math.floor(alignFloor(t, 'day') / DAY_MS);
+export function createUsageIndex(state) {
+    const days = new Map();
+    return {
+        add(record) {
+            const o = dayOrdinal(record.time);
+            let day = days.get(o);
+            if (day === undefined) {
+                day = [];
+                days.set(o, day);
+            }
+            day.push(record);
+        },
+        remove(record) {
+            const day = days.get(dayOrdinal(record.time));
+            if (day === undefined)
+                return; // missing record: tolerate silently
+            const i = day.indexOf(record);
+            if (i === -1)
+                return; // not indexed: tolerate silently
+            day.splice(i, 1);
+            if (day.length === 0)
+                days.delete(dayOrdinal(record.time));
+        },
+        *recordsInRange(from, to) {
+            const startOrd = Number.isFinite(from) ? dayOrdinal(from) : null;
+            const endOrd = Number.isFinite(to) ? dayOrdinal(to) : null;
+            // Finite bounds cover ordinal ranges directly; unbounded sides fall back
+            // to scanning the known day keys (never an infinite loop on ±Infinity).
+            const ords = [];
+            if (startOrd !== null && endOrd !== null) {
+                for (let o = startOrd; o <= endOrd; o++)
+                    ords.push(o);
+            }
+            else {
+                for (const o of days.keys()) {
+                    if (startOrd === null || o >= startOrd) {
+                        if (endOrd === null || o <= endOrd)
+                            ords.push(o);
+                    }
+                }
+                ords.sort((a, b) => a - b);
+            }
+            const seen = new Set();
+            for (const o of ords) {
+                const day = days.get(o);
+                if (day === undefined)
+                    continue;
+                for (const r of day) {
+                    if (r.time >= from && r.time <= to) {
+                        seen.add(r);
+                        yield r;
+                    }
+                }
+            }
+            // Defensive sweep: surface any record the slice index missed (bookkeeping
+            // gaps) without yielding anything twice.
+            for (const r of state.records) {
+                if (r.time >= from && r.time <= to && !seen.has(r))
+                    yield r;
+            }
+        },
+        /** Total indexed records (day slices only). */
+        size() {
+            let n = 0;
+            for (const day of days.values())
+                n += day.length;
+            return n;
+        },
+        /** Drop whole day slices strictly before ts (keeps the day containing ts). */
+        pruneBefore(ts) {
+            const cut = dayOrdinal(ts);
+            for (const o of days.keys()) {
+                if (o < cut)
+                    days.delete(o);
+            }
+        },
+    };
+}

package/lib/host/client-source.js

@@ -0,0 +1,34 @@
+/**
+ * Client source loader.
+ *
+ * The full dashboard UI lives in src/client/index.js (single source of
+ * truth). A dynamic plugin cannot import files, so the host reads the file
+ * and serves it to the browser half, which evaluates it with new Function.
+ *
+ * P1-4: candidates are derived from import.meta.url so the dynamic-plugin
+ * dev flow works from any checkout location.
+ */
+import { fileURLToPath } from 'node:url';
+const CLIENT_SOURCE_CANDIDATES = [
+    // src/host -> src/client in dev; lib/host -> lib/client when built.
+    fileURLToPath(new URL('../client/index.js', import.meta.url)),
+    // Repo source fallback when the built lib runs inside a checkout.
+    fileURLToPath(new URL('../../src/client/index.js', import.meta.url)),
+];
+export async function getClientSource(ctx) {
+    const fs = ctx.get('fs');
+    if (fs === undefined)
+        return { ok: false, error: 'fs service unavailable' };
+    for (const p of CLIENT_SOURCE_CANDIDATES) {
+        try {
+            const target = await fs.resolve(p);
+            const body = await fs.readText(target);
+            if (typeof body === 'string' && body.length > 0)
+                return { ok: true, body };
+        }
+        catch (error) {
+            // try the next candidate
+        }
+    }
+    return { ok: false, error: 'client source not found (tried: ' + CLIENT_SOURCE_CANDIDATES.join(', ') + ')' };
+}

package/lib/host/fold.js

@@ -0,0 +1,66 @@
+/**
+ * Fold session events into usage records.
+ *
+ * foldNew is called by scan.js for both live and persisted sessions.
+ *
+ * P0-2: dedup ownership lives here. Records are keyed by
+ * state.dedup (sessionId + turn + step); a later sample for the same
+ * (turn, step) REPLACES the previous one in place instead of appending,
+ * calling state.index.remove() for the dropped record and state.index.add()
+ * for the replacement. Records without turn/step (legacy logs) are never
+ * deduped — they always append.
+ */
+export function foldEvent(state, sessionId, e) {
+    if (!e || e.type !== 'assistant/message' || !e.data || !e.data.usage)
+        return null;
+    const source = (e.data.message && e.data.message.source) || {};
+    const u = e.data.usage;
+    const rec = {
+        time: e.time,
+        session: sessionId,
+        provider: source.provider || '',
+        model: source.model || '',
+        turn: e.data.turn,
+        step: e.data.step,
+        inputTokens: u.inputTokens || 0,
+        outputTokens: u.outputTokens || 0,
+        cacheReadTokens: u.cacheReadTokens || 0,
+        cacheWriteTokens: u.cacheWriteTokens || 0,
+        reasoningTokens: u.reasoningTokens || 0,
+        totalTokens: (u.inputTokens || 0) + (u.outputTokens || 0) + (u.cacheReadTokens || 0) + (u.cacheWriteTokens || 0),
+    };
+    const key = sessionId + ':' + rec.turn + ':' + rec.step;
+    if (rec.turn !== undefined && rec.step !== undefined) {
+        const prevIndex = state.dedup.get(key);
+        if (prevIndex !== undefined) {
+            const prev = state.records[prevIndex];
+            if (state.index)
+                state.index.remove(prev);
+            Object.assign(prev, rec);
+            if (state.index)
+                state.index.add(prev);
+            return prev;
+        }
+        state.records.push(rec);
+        state.dedup.set(key, state.records.length - 1);
+        if (state.index)
+            state.index.add(rec);
+        return rec;
+    }
+    state.records.push(rec);
+    if (state.index)
+        state.index.add(rec);
+    return rec;
+}
+/** Fold events with seq > watermark for one session; returns new watermark. */
+export function foldNew(state, sessionId, events, wm) {
+    let max = wm;
+    for (const e of events) {
+        if (e && typeof e.seq === 'number' && e.seq > wm) {
+            foldEvent(state, sessionId, e);
+            if (e.seq > max)
+                max = e.seq;
+        }
+    }
+    return max;
+}

package/lib/host/index.js

@@ -1,444 +1,56 @@
 /**
- * usage — Token usage statistics host half.
+ * usage — Token usage statistics host half (entry module).
  *
- * Strategy (dynamic-plugin safe):
+ * Wires the submodules (fold / scan / query / settings / aggregate / rpc /
+ * client-source) into the cordis plugin lifecycle. Strategy notes:
  *  - DSH already persists every loop model call's token usage durably in each
- *    session log as `assistant/message` events carrying `usage` (TokenUsage) and
- *    `message.source.{provider,model}`. We fold those events into an in-memory
- *    index instead of tapping `llm/stream` (unreachable from an agent-scoped
- *    dynamic plugin) and instead of writing our own files.
+ *    session log as `assistant/message` events carrying `usage` (TokenUsage)
+ *    and `message.source.{provider,model}`. We fold those events instead of
+ *    tapping `llm/stream` (unreachable from an agent-scoped dynamic plugin).
  *  - Live sessions are scanned from the in-memory store every poll tick;
  *    persisted sessions are backfilled at startup and re-scanned incrementally
- *    on a slower cadence (watermark per session, `seq >= fromSeq`).
- *  - Aggregation, cost (own user-configurable price table — the runtime has no
- *    pricing concept) and model list are served to the Client via harness RPC.
+ *    on a slower cadence (watermark per session).
+ *  - Aggregation, cost (user-configurable price table) and model list are
+ *    served to the Client via the RPC bridge (rpc.js).
  *
- * The same file doubles as the cordis.yml host plugin module (exports name /
+ * The same entry doubles as the cordis.yml host plugin module (exports name /
  * inject / apply) and as the `code.host` function body for a dynamic plugin.
  */
 export const name = 'usage-host';
 export const inject = ['timer'];
+import { DEFAULT_PRICES, DEFAULT_CURRENCY, createPriceStore, initSettings } from './settings.js';
+import { createState } from './state.js';
+import { createUsageIndex } from './aggregate.js';
+import { scanLive, scanPersisted, runBackfill } from './scan.js';
+import { query } from './query.js';
+import { registerRPC } from './rpc.js';
+import { getClientSource } from './client-source.js';
+const LIVE_POLL_MS = 2000;
+const PERSISTED_POLL_MS = 30000;
 export function apply(ctx) {
-    // ---------------------------------------------------------------- constants
-    const RPC_QUERY = 'usage/query';
-    const RPC_PRICES = 'usage/prices';
-    const DEFAULT_CURRENCY = '¥';
-    const DEFAULT_PRICES = {
-        'deepseek-chat': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
-        'deepseek-v3': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
-        'deepseek-v3.1': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
-        'deepseek-v4': { inputPerM: 0.27, outputPerM: 1.1, cacheReadPerM: 0.07, cacheWritePerM: 0.27 },
-        'deepseek-v4-flash': { inputPerM: 0.14, outputPerM: 0.56, cacheReadPerM: 0.04, cacheWritePerM: 0.14 },
-        'deepseek-reasoner': { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14, cacheWritePerM: 0.55 },
-        'deepseek-r1': { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14, cacheWritePerM: 0.55 },
-    };
-    const LIVE_POLL_MS = 2000;
-    const PERSISTED_POLL_MS = 30000;
-    // ------------------------------------------------------------------- state
-    /** Folded usage records, one per assistant/message with usage. */
-    const records = [];
-    /** sessionId -> last folded event seq. */
-    const watermarks = new Map();
-    /** User-overridable price table (model -> ModelPrice). */
-    const prices = Object.assign({}, DEFAULT_PRICES);
-    let currency = DEFAULT_CURRENCY;
-    const backfill = { status: 'idle', total: 0, done: 0 };
-    // -------------------------------------------------------------------- fold
-    function foldEvent(sessionId, e) {
-        if (!e || e.type !== 'assistant/message' || !e.data || !e.data.usage)
-            return;
-        const source = (e.data.message && e.data.message.source) || {};
-        const u = e.data.usage;
-        records.push({
-            time: e.time,
-            session: sessionId,
-            provider: source.provider || '',
-            model: source.model || '',
-            inputTokens: u.inputTokens || 0,
-            outputTokens: u.outputTokens || 0,
-            cacheReadTokens: u.cacheReadTokens || 0,
-            cacheWriteTokens: u.cacheWriteTokens || 0,
-            reasoningTokens: u.reasoningTokens || 0,
-            totalTokens: (u.inputTokens || 0) + (u.outputTokens || 0) + (u.cacheReadTokens || 0) + (u.cacheWriteTokens || 0),
-        });
-    }
-    /** Fold events with seq > watermark for one session; returns new watermark. */
-    function foldNew(sessionId, events, wm) {
-        let max = wm;
-        for (const e of events) {
-            if (e && typeof e.seq === 'number' && e.seq > wm) {
-                foldEvent(sessionId, e);
-                if (e.seq > max)
-                    max = e.seq;
-            }
-        }
-        return max;
-    }
-    // ------------------------------------------------------------------ scans
-    /** Scan live in-memory sessions (cheap, every tick). */
-    function scanLive() {
-        const sessions = ctx.get('sessions');
-        if (sessions === undefined)
-            return;
-        for (const s of sessions.list()) {
-            if (!s || !s.id)
-                continue;
-            const wm = watermarks.get(s.id) ?? -1;
-            const next = foldNew(s.id, s.events || [], wm);
-            if (next > wm)
-                watermarks.set(s.id, next);
-        }
-    }
-    /** Incremental scan of persisted sessions (slow cadence). */
-    async function scanPersisted() {
-        const sp = ctx.get('sessionPersistence');
-        if (sp === undefined)
-            return;
-        const headers = await sp.list();
-        if (!Array.isArray(headers))
-            return;
-        backfill.total = headers.length;
-        for (const h of headers) {
-            if (!h || !h.id)
-                continue;
-            const wm = watermarks.get(h.id) ?? -1;
-            try {
-                const page = await sp.readFrom(h.id, wm + 1);
-                const events = (page && page.events) || [];
-                const next = foldNew(h.id, events, wm);
-                if (next > wm)
-                    watermarks.set(h.id, next);
-            }
-            catch (error) {
-                // A session may be gone or mid-rewrite; skip and retry next pass.
-            }
-            if (backfill.status === 'running')
-                backfill.done += 1;
-        }
-    }
-    /** Full history scan, once at startup. */
-    async function runBackfill() {
-        const sp = ctx.get('sessionPersistence');
-        if (sp === undefined) {
-            backfill.status = 'done';
-            return;
-        }
-        backfill.status = 'running';
-        backfill.done = 0;
-        try {
-            await scanPersisted();
-            backfill.status = 'done';
-        }
-        catch (error) {
-            backfill.status = 'done';
-        }
-    }
-    // ------------------------------------------------------------------- cost
-    /** Look up a price by `provider/model` composite first, then bare model. */
-    function priceOf(r) {
-        const composite = r.provider ? r.provider + '/' + r.model : '';
-        return prices[composite] || prices[r.model];
-    }
-    function costOf(r) {
-        const p = priceOf(r);
-        if (!p)
-            return 0;
-        return (r.inputTokens * p.inputPerM +
-            r.outputTokens * p.outputPerM +
-            r.cacheReadTokens * (p.cacheReadPerM || 0) +
-            r.cacheWriteTokens * (p.cacheWritePerM || 0)) / 1e6;
-    }
-    // ------------------------------------------------------------------ query
-    function dayKey(t) {
-        const d = new Date(t);
-        const pad = (n) => String(n).padStart(2, '0');
-        return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
-    }
-    const DAY_MS = 86400000;
-    /** Ordinal day number (local calendar day -> UTC-day index), for step alignment. */
-    function dayIndex(t) {
-        const d = new Date(t);
-        return Math.floor(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / DAY_MS);
-    }
-    /** Bucket key for one instant under a granularity (day buckets may span stepDays). */
-    function bucketKeyFor(t, g, stepDays) {
-        const pad = (n) => String(n).padStart(2, '0');
-        if (g === 'day') {
-            const block = Math.floor(dayIndex(t) / stepDays) * stepDays;
-            const d = new Date(block * DAY_MS); // UTC midnight; UTC components == local calendar day
-            return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
-        }
-        const d = new Date(t);
-        const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
-        const hm = pad(d.getHours()) + ':' + (g === 'hour' ? '00' : pad(d.getMinutes()));
-        return date + ' ' + hm;
-    }
-    function stepMs(g) {
-        return g === 'day' ? DAY_MS : g === 'hour' ? 3600000 : 60000;
-    }
-    /** Floor an instant to its granularity boundary. */
-    function alignFloor(t, g) {
-        const d = new Date(t);
-        if (g === 'day') {
-            d.setHours(0, 0, 0, 0);
-            return d.getTime();
-        }
-        if (g === 'hour') {
-            d.setMinutes(0, 0, 0);
-            return d.getTime();
-        }
-        d.setSeconds(0, 0);
-        return d.getTime();
-    }
-    /** Floor an instant to its stepDays block start (UTC midnight of the block). */
-    function alignBlock(t, stepDays) {
-        const block = Math.floor(dayIndex(t) / stepDays) * stepDays;
-        return block * DAY_MS;
-    }
-    /**
-     * Bucket key under a day granularity with a range-anchored step grid:
-     * blocks start at the range's first day, so a custom range reads naturally
-     * (e.g. 90 days -> 18 x 5-day buckets starting on the range's first day).
-     */
-    function stepDayKey(r, dayStart, stepDays) {
-        const k = Math.floor((alignFloor(r.time, 'day') - dayStart) / (stepDays * DAY_MS));
-        return dayKey(dayStart + k * stepDays * DAY_MS);
-    }
-    const MAX_BUCKETS = 2000;
-    function emptyBucket(key) {
-        return {
-            key,
-            calls: 0,
-            inputTokens: 0,
-            outputTokens: 0,
-            cacheReadTokens: 0,
-            cacheWriteTokens: 0,
-            totalTokens: 0,
-            cost: 0,
-        };
-    }
-    function addToBucket(b, r, cost) {
-        b.calls += 1;
-        b.inputTokens += r.inputTokens;
-        b.outputTokens += r.outputTokens;
-        b.cacheReadTokens += r.cacheReadTokens;
-        b.cacheWriteTokens += r.cacheWriteTokens;
-        b.totalTokens += r.inputTokens + r.outputTokens + r.cacheReadTokens + r.cacheWriteTokens;
-        b.cost += cost;
-        return b;
-    }
-    function query(args) {
-        const from = typeof args.from === 'number' ? args.from : -Infinity;
-        const to = typeof args.to === 'number' ? args.to : Infinity;
-        const granularity = args.granularity === 'minute' || args.granularity === 'hour' ? args.granularity : 'day';
-        const stepDays = granularity === 'day' && Number.isInteger(args.stepDays) && args.stepDays > 0 ? args.stepDays : 1;
-        // Zero-filled step series require a finite range.
-        const fill = Boolean(args.fill) && Number.isFinite(from) && Number.isFinite(to);
-        const modelSet = Array.isArray(args.models) && args.models.length > 0
-            ? new Set(args.models)
-            : null;
-        /** Match either a bare model id or a `provider/model` composite key. */
-        const modelMatches = (r) => {
-            if (!modelSet)
-                return true;
-            if (modelSet.has(r.model))
-                return true;
-            return Boolean(r.provider) && modelSet.has(r.provider + '/' + r.model);
-        };
-        const dailyMap = new Map();
-        const modelMap = new Map();
-        const total = emptyBucket('total');
-        const seenModels = new Map(); // model -> {provider, model} (first provider wins)
-        let unpricedCalls = 0;
-        // Range-anchored day-step grid: blocks start at the range's first day.
-        const dayAnchor = Number.isFinite(from) ? alignFloor(from, 'day') : null;
-        const useStepGrid = granularity === 'day' && stepDays > 1 && dayAnchor !== null;
-        for (const r of records) {
-            if (r.time < from || r.time > to)
-                continue;
-            if (!modelMatches(r))
-                continue;
-            const cost = costOf(r);
-            if (cost === 0 && r.totalTokens > 0)
-                unpricedCalls += 1;
-            if (!seenModels.has(r.model))
-                seenModels.set(r.model, { provider: r.provider, model: r.model });
-            const dk = useStepGrid ? stepDayKey(r, dayAnchor, stepDays) : bucketKeyFor(r.time, granularity, stepDays);
-            let db = dailyMap.get(dk);
-            if (db === undefined) {
-                db = emptyBucket(dk);
-                dailyMap.set(dk, db);
-            }
-            addToBucket(db, r, cost);
-            let mb = modelMap.get(r.model);
-            if (mb === undefined) {
-                mb = emptyBucket(r.model);
-                modelMap.set(r.model, mb);
-            }
-            addToBucket(mb, r, cost);
-            addToBucket(total, r, cost);
-        }
-        let daily;
-        if (fill) {
-            let start;
-            let step;
-            let end;
-            if (granularity === 'day') {
-                step = stepDays * DAY_MS;
-                start = dayAnchor !== null ? dayAnchor : alignFloor(from, 'day');
-                end = alignFloor(to, 'day') + step;
-            }
-            else {
-                step = stepMs(granularity);
-                start = alignFloor(from, granularity);
-                end = alignFloor(to, granularity) + step;
-            }
-            const count = Math.round((end - start) / step);
-            if (count <= MAX_BUCKETS) {
-                daily = [];
-                for (let i = 0; i < count; i++) {
-                    const t = start + i * step;
-                    const k = useStepGrid ? dayKey(t) : bucketKeyFor(t, granularity, stepDays);
-                    daily.push(dailyMap.get(k) || emptyBucket(k));
-                }
-            }
-            else {
-                // Degenerate: too many steps; fall back to present-only buckets.
-                daily = [...dailyMap.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-            }
-        }
-        else {
-            daily = [...dailyMap.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-        }
-        const byModel = [...modelMap.values()].sort((a, b) => b.totalTokens - a.totalTokens);
-        const models = [...seenModels.values()];
-        // GitHub-style yearly heatmap: every calendar day of the current year up to
-        // today, zero-filled.
-        let heatmap = null;
-        if (args.heatmap) {
-            const now = Date.now();
-            const year = new Date(now).getFullYear();
-            const hmMap = new Map();
-            const yearStart = new Date(year, 0, 1).getTime();
-            for (const r of records) {
-                if (r.time < yearStart || r.time > now)
-                    continue;
-                if (!modelMatches(r))
-                    continue;
-                const dk = dayKey(r.time);
-                let b = hmMap.get(dk);
-                if (b === undefined) {
-                    b = emptyBucket(dk);
-                    hmMap.set(dk, b);
-                }
-                addToBucket(b, r, costOf(r));
-            }
-            heatmap = [];
-            const todayStart = alignFloor(now, 'day');
-            for (let d = new Date(year, 0, 1); d.getTime() <= todayStart; d.setDate(d.getDate() + 1)) {
-                const k = dayKey(d.getTime());
-                heatmap.push(hmMap.get(k) || emptyBucket(k));
-            }
-        }
-        return {
-            daily,
-            byModel,
-            total,
-            models,
-            unpricedCalls,
-            ...heatmap === null ? {} : { heatmap },
-            backfill: { status: backfill.status, total: backfill.total, done: backfill.done },
-        };
-    }
-    // ------------------------------------------------------------------- RPC
-    // Static (bundle) installs expose the generic Connection RPC bridge (the
-    // browser half calls `connection.rpc.call('/usage', endpoint, args)`);
-    // dynamic-plugin runs expose `harness` directly. Support both from one file.
-    const usageHandlers = new Map();
-    function usageHandle(method, fn) {
-        const name = String(method);
-        usageHandlers.set(name.indexOf('/') === -1 ? name : name.slice(name.indexOf('/') + 1), fn);
-    }
-    usageHandle(RPC_QUERY, (args) => query(args || {}));
-    usageHandle(RPC_PRICES, (args) => {
-        const incoming = (args && args.prices) || null;
-        if (incoming && typeof incoming === 'object') {
-            for (const [model, p] of Object.entries(incoming)) {
-                if (p && typeof p === 'object') {
-                    prices[model] = {
-                        inputPerM: Number(p.inputPerM) || 0,
-                        outputPerM: Number(p.outputPerM) || 0,
-                        cacheReadPerM: Number(p.cacheReadPerM) || 0,
-                        cacheWritePerM: Number(p.cacheWritePerM) || 0,
-                    };
-                }
-            }
-        }
+    const priceStore = createPriceStore(DEFAULT_PRICES, DEFAULT_CURRENCY);
+    initSettings(ctx, priceStore);
+    const state = createState(priceStore);
+    state.index = createUsageIndex(state);
+    const handlers = new Map();
+    handlers.set('query', (args) => query(state, args || {}));
+    handlers.set('prices', (args) => {
+        const store = state.prices;
+        store.setPrices(args && args.prices);
         if (args && typeof args.currency === 'string')
-            currency = args.currency;
-        return { prices: Object.assign({}, prices), currency };
+            store.setCurrency(args.currency);
+        return store.snapshot();
     });
-    // ------------------------------------------------- client source loader
-    // The full dashboard UI lives in src/client/index.js (single source of
-    // truth). A dynamic plugin cannot import files, so the host reads the file
-    // and serves it to the browser half, which evaluates it with new Function.
-    const CLIENT_SOURCE_CANDIDATES = [
-        '/Users/ruanbw/projects/usage/src/client/index.js',
-        '/Users/ruanbw/projects/usage/lib/client/index.js',
-    ];
-    usageHandle('usage/client-source', async () => {
-        const fs = ctx.get('fs');
-        if (fs === undefined)
-            return { ok: false, error: 'fs service unavailable' };
-        for (const p of CLIENT_SOURCE_CANDIDATES) {
-            try {
-                const target = await fs.resolve(p);
-                const body = await fs.readText(target);
-                if (typeof body === 'string' && body.length > 0)
-                    return { ok: true, body };
-            }
-            catch (error) {
-                // try the next candidate
-            }
-        }
-        return { ok: false, error: 'client source not found (tried: ' + CLIENT_SOURCE_CANDIDATES.join(', ') + ')' };
-    });
-    const dynamicHarness = (typeof harness !== 'undefined' && harness && typeof harness.handle === 'function') ? harness : null;
-    if (dynamicHarness !== null) {
-        for (const [endpoint, fn] of usageHandlers) {
-            dynamicHarness.handle('usage/' + endpoint, fn);
-        }
-    }
-    else {
-        // Static (bundle) installs: the `connection` service is provided
-        // asynchronously by the client-connection plugin, so wait for it before
-        // registering the /usage channel (the official api-gateway pattern).
-        ctx.inject(['connection'], (connectionCtx) => {
-            const connection = connectionCtx.connection;
-            if (connection === undefined || connection.rpc === undefined)
-                return;
-            connection.rpc.handle('/usage', async (endpoint, args) => {
-                const fn = usageHandlers.get(endpoint);
-                if (fn === undefined) {
-                    return { ok: false, error: { code: 'bad-request', message: `unknown endpoint: ${endpoint}`, details: { issues: [] } } };
-                }
-                try {
-                    return { ok: true, value: await fn(args) };
-                }
-                catch (error) {
-                    return { ok: false, error: { code: 'internal', message: String((error && error.message) || error), details: {} } };
-                }
-            }, { authority: 'loopback' });
-        });
-    }
-    // ---------------------------------------------------------------- startup
-    runBackfill();
+    handlers.set('client-source', () => getClientSource(ctx));
+    registerRPC(ctx, handlers);
+    // Full history scan once at startup.
+    runBackfill(ctx, state);
     // Live sessions every tick; persisted sessions on a slow cadence to keep
     // per-session JSONL re-parsing cheap.
     ctx.interval(() => {
-        scanLive();
+        scanLive(ctx, state);
     }, LIVE_POLL_MS);
     ctx.interval(() => {
-        scanPersisted().catch(() => { });
+        scanPersisted(ctx, state).catch(() => { });
     }, PERSISTED_POLL_MS);
 }